نظام الإحداثيات

في كل من مستند PDF وعند العمل مع مكتبة Aspose.PDF، يبدأ نظام الإحداثيات من الزاوية السفلى اليسرى من الصفحة. النقطة (0،0) تتوافق مع الزاوية السفلى اليسرى. هذا يعني أنه عند وضع الصور أو النصوص أو الكائنات الأخرى، من المهم أن نتذكر أن المحور Y يزيد لأعلى، على عكس بعض أنظمة الإحداثيات الأخرى. كل صفحة لها نظام إحداثيات خاص بها. يتم تحديد الإحداثيات بوحدات مستقلة عن النظام الأساسي. تنص مواصفات PDF على أن PDF يعمل مع مساحات إحداثيات متعددة.

مساحة الجهاز

كل جهاز إخراج - سواء كان شاشة أو طابعة، إلخ. يستخدم نظام إحداثيات خاص به لعرض الصور. يسمى هذا النظام مساحة الجهاز. قد يكون الأصل (النقطة 0،0) موجودًا في مواضع مختلفة اعتمادًا على الجهاز. بالإضافة إلى ذلك، قد تختلف اتجاهات محاور الإحداثيات: يمكن أن يزيد المحور Y العمودي إما من الأسفل إلى الأعلى أو من الأعلى إلى الأسفل. تختلف دقة الأجهزة أيضًا. غالبًا ما تحتوي الشاشات على دقة 72 أو 96 بكسل لكل بوصة، بينما قد تحتوي الطابعات على 300 أو 600 أو حتى دقات أعلى لكل بوصة. قد تحتوي بعض الأجهزة أيضًا على دقات مختلفة على المحاور الأفقية والعمودية. إذا تم تحديد العناصر الرسومية مباشرة في إحداثيات مساحة الجهاز، فإن النتيجة تصبح معتمدة على خصائص الجهاز المعين. يمكن أن يؤدي ذلك إلى عرض مشوه: قد يظهر نفس الكائن بشكل مختلف على الشاشة وفي الطباعة. على سبيل المثال، خط طوله 8 بوصات، محدد بإحداثيات العرض بدقة 72 بكسل لكل بوصة، سيشغل أقل من بوصة واحدة عند طباعته على طابعة بدقة 600 نقطة لكل بوصة.

مساحة المستخدم

لتجنب مثل هذه المشكلات، يستخدم PDF نظام إحداثيات مستقل عن الجهاز (مساحة المستخدم) والذي يضمن عرض الرسوميات بشكل متسق بغض النظر عن جهاز الإخراج. أثناء عرض الصفحة، يتم تحويل المحتوى من مساحة المستخدم إلى مساحة الجهاز، مع الأخذ في الاعتبار الميزات المحددة لجهاز الإخراج. كل صفحة في المستند لها نظام إحداثيات مساحة مستخدم خاص بها. طول وحدة واحدة على كلا المحورين يساوي 1/72 بوصة. يمكنك تغيير وحدات القياس عن طريق تعيين UserUnit، الذي يساوي افتراضيًا 1. يمكن تحديد هذه القيمة باستخدام خاصية UserUnit لكائن الصفحة. يعمل UserUnit كعامل مضاعف لـ 1/72 بوصة.

يتم تعريف التحويل من مساحة المستخدم إلى مساحة الجهاز بواسطة مصفوفة التحويل الحالية (CTM).

الصورة 1. تحويل مصفوفة مساحة الإحداثيات. مأخوذ من مواصفة ISO 32000-2:2020

إذا كنت تقوم بإنشاء محتوى الصفحة باستخدام مشغلات PDF، يمكنك تعديل CTM (مصفوفة التحويل الحالية) باستخدام مشغل Aspose.Pdf.ConcatenateMatrix، الذي يدمج المصفوفة الحالية مع تلك التي تقدمها. يسمح لك ذلك بإجراء التدوير والترجمة والتكبير للمحتوى المعروض.

الصورة 2. التحويل إلى مساحة الجهاز. مأخوذ من مواصفة ISO 32000-2:2020

بالإضافة إلى مساحة المستخدم ومساحة الجهاز، يستخدم PDF عدة أنظمة إحداثيات أخرى، كل منها يخدم أغراضًا محددة:

مساحة النص

يتم وضع النص في نظام إحداثيات خاص به - مساحة النص. يتم إجراء التحويل من مساحة النص إلى مساحة المستخدم باستخدام مصفوفة نص مخصصة جنبًا إلى جنب مع إعدادات عرض نص مختلفة.

مساحة الجليف

يتم تعريف أحرف الخط (الجليفات) في مساحة الجليف. يتم تحويل هذه المساحة إلى مساحة النص عبر مصفوفة الخط. بالنسبة لمعظم الخطوط، يتم استخدام مقياس 1000 وحدة مساحة جليف = 1 وحدة مساحة نص. في بعض الخطوط، مثل خطوط النوع 3، يتم تعريف هذه المصفوفة بشكل صريح.

مساحة الصورة

يتم تعريف الصور النقطية في مساحة الصورة الخاصة بها. يتم دائمًا تحويل هذه المساحة تلقائيًا إلى مساحة المستخدم: تعتبر الصور لها عرض وارتفاع 1 وحدة، بغض النظر عن دقتها الفعلية. لعرض صورة بشكل صحيح، يتم تعيين مقياسها وموقعها عن طريق تعديل مصفوفة التحويل (التكبير، التدوير).

مساحة النموذج

النماذج (Form XObjects) هي أجزاء محتوى مستقلة يمكن تضمينها كعناصر رسومية. يتم تعريف كل نموذج في مساحة نموذج خاصة به، والتي يتم تحويلها بعد ذلك إلى مساحة المستخدم باستخدام مصفوفة نموذج.

الصورة 3. العلاقات بين مساحات الإحداثيات. مأخوذ من مواصفة ISO 32000-2:2020

مصفوفة التحويل

تتيح هذه المصفوفة عمليات مثل التكبير والتدوير والترجمة والانزلاق والانعكاس للكائنات على الصفحة. إنها مصفوفة ثنائية الأبعاد 3×3، ولكن في PDF يتم استخدام 6 معلمات عددية فقط: [a b c d e f]. تُطبق هذه المصفوفة على كل نقطة (x، y) من المساحة المحولة باستخدام الصيغ التالية: x’ = a * x + c * y + e
y’ = b * x + d * y + f

الصورة 4. معادلة تحويل الإحداثيات. مأخوذ من مواصفة ISO 32000-2:2020

صيغة تحويل الإحداثيات - مأخوذة من مواصفة ISO 32000-2:2020. اعتمادًا على قيم عناصر المصفوفة، يمكن تعريف أنواع مختلفة من التحويلات:

• الترجمة: [1 0 0 1 e f] - تنقل كائنًا بمقدار e وحدات على المحور X و f وحدات على المحور Y.
• التكبير: [a 0 0 d 0 0] - يكبر كائنًا بمقدار a مرات على X و d مرات على Y.
• التدوير: [cos(θ) sin(θ) -sin(θ) cos(θ) 0 0] - يدور كائنًا بزاوية θ (بالراديان).
• الانزلاق: على X [1 0 c 1 0 0]، على Y [1 b 0 1 0 0].
• الانعكاس: عبر المحور X [1 0 0 -1 0 0]، عبر المحور Y [-1 0 0 1 0 0]

مثال على تعيين مصفوفة تحويل:

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
var matrix = new Aspose.Pdf.Matrix(new double[]{a, b, c, d, e, f});
page.Contents.Add(new Aspose.Pdf.Operators.ConcatenateMatrix(matrix));

في المثال 1، يمكنك أن ترى أن محاولة عرض النص عند إحداثيات الزاوية للصفحة تؤدي إلى ظهور النص عند الأصل فقط. يقع باقي النص خارج المنطقة المرئية ويتم قصه.

.NET Core 3.1

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static string CoordinatesExample1()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_Text();
    string outputFilePath = dataDir + "coordinates1.pdf";
    
    // Create new document
    using (var document = new Aspose.Pdf.Document())
    {
        // Get particular page
        var page = document.Pages.Add();
    
        // Create TextBuilder object
        var textBuilder = new Aspose.Pdf.Text.TextBuilder(page);
    
        DrawText("Low left", 0, 0, textBuilder);
        DrawText("Low right", (int)page.CropBox.URX, 0, textBuilder);
        DrawText("Upper left", 0, (int)page.CropBox.URY, textBuilder);
        DrawText("Upper right", (int)page.CropBox.URX, (int)page.CropBox.URY, textBuilder);
    
        // Save PDF document
        document.Save(outputFilePath);
    }

    return outputFilePath;
}

private static void DrawText(string text, int x, int y, TextBuilder textBuilder)
{
    // Create text fragment
    var textFragment = new Aspose.Pdf.Text.TextFragment(text);
    textFragment.Position = new Aspose.Pdf.Text.Position(x, y);

    // Set text properties
    textFragment.TextState.FontSize = 12;
    textFragment.TextState.Font = Aspose.Pdf.Text.FontRepository.FindFont("TimesNewRoman");

    // Append the text fragment to the PDF page
    textBuilder.AppendText(textFragment);
}

.NET 8

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static string CoordinatesExample1()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_Text();
    string outputFilePath = dataDir + "coordinates1.pdf";
    
    // Create new document
    using var document = new Aspose.Pdf.Document();
    
    // Get particular page
    var page = document.Pages.Add();

    // Create TextBuilder object
    var textBuilder = new Aspose.Pdf.Text.TextBuilder(page);

    DrawText("Low left", 0, 0, textBuilder);
    DrawText("Low right", (int)page.CropBox.URX, 0, textBuilder);
    DrawText("Upper left", 0, (int)page.CropBox.URY, textBuilder);
    DrawText("Upper right", (int)page.CropBox.URX, (int)page.CropBox.URY, textBuilder);

    // Save PDF document
    document.Save(outputFilePath);    

    return outputFilePath;
}

private static void DrawText(string text, int x, int y, TextBuilder textBuilder)
{
    // Create text fragment
    var textFragment = new Aspose.Pdf.Text.TextFragment(text);
    textFragment.Position = new Aspose.Pdf.Text.Position(x, y);

    // Set text properties
    textFragment.TextState.FontSize = 12;
    textFragment.TextState.Font = Aspose.Pdf.Text.FontRepository.FindFont("TimesNewRoman");

    // Append the text fragment to the PDF page
    textBuilder.AppendText(textFragment);
}

الصورة 5. نتيجة تنفيذ المثال 1.

في المثال 2، نقوم بتكبير نظام الإحداثيات ونقله إلى مركز الصفحة.

.NET Core 3.1

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void Example2()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_Text();

    string sourcePdf = Example1();

    // Open document
    using (var document = new Aspose.Pdf.Document(sourcePdf))
    {
        Page page = document.Pages[1];
		
        // Get the page's dimensions
        double pageWidth = page.CropBox.Width;
        double pageHeight = page.CropBox.Height;

        // Set the scale factor
        double scale = 0.5;

        // Calculate the offset
        double offsetX = (pageWidth - pageWidth * scale) / 2;
        double offsetY = (pageHeight - pageHeight * scale) / 2;
		
        // Get the page's contents
        var contents = page.Contents;

        // Add the current graphical state to the content's beginning
        contents.Insert(1, new Aspose.Pdf.Operators.GSave());
        // Scale and move the coordinate system to fit the content in the center of the page
        contents.Insert(2,
            new Aspose.Pdf.Operators.ConcatenateMatrix(scale, 0, 0, scale, offsetX, offsetY));
	   
        contents.Add(new Aspose.Pdf.Operators.GRestore());

        // Save PDF document
        document.Save(dataDir + "coordinates2.pdf");
      }
}

.NET 8

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void Example2()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_Text();

    string sourcePdf = Example1();

    // Open document
    using var document = new Aspose.Pdf.Document(sourcePdf);
    
    Page page = document.Pages[1];
    
    // Get the page's dimensions
    double pageWidth = page.CropBox.Width;
    double pageHeight = page.CropBox.Height;

    // Set the scale factor
    double scale = 0.5;

    // Calculate the offset
    double offsetX = (pageWidth - pageWidth * scale) / 2;
    double offsetY = (pageHeight - pageHeight * scale) / 2;
    
    // Get the page's contents
    var contents = page.Contents;

    // Add the current graphical state to the content's beginning
    contents.Insert(1, new Aspose.Pdf.Operators.GSave());
    // Scale and move the coordinate system to fit the content in the center of the page
    contents.Insert(2,
        new Aspose.Pdf.Operators.ConcatenateMatrix(scale, 0, 0, scale, offsetX, offsetY));
   
    contents.Add(new Aspose.Pdf.Operators.GRestore());

    // Save PDF document
    document.Save(dataDir + "coordinates2.pdf");
      
}

الصورة 6. نتيجة تنفيذ المثال 2.

فهم أنظمة الإحداثيات والموضع في Aspose.PDF

عند العمل مع Aspose.PDF، من المهم فهم الفروق بين الكائنات المستخدمة للموضع وأنظمة الإحداثيات الخاصة بها. فيما يلي شرح مفصل للكائنات الرئيسية (TextFragment، TextStamp، FloatingBox، Rectangle) وحالات استخدامها، مع مزاياها وعيوبها.

TextFragment

نظام الإحداثيات: موضع مطلق (أصل السفلي الأيسر). الوصف: يسمح لك كلاس TextFragment بإضافة نص إلى موضع محدد على الصفحة باستخدام إحداثيات مطلقة. المزايا:

• بسيط وفعال لإضافة نص في مواضع دقيقة.
• عملية خفيفة مقارنة بـ TextStamp. العيوب:
• لا يدعم التحويلات المتقدمة مثل التدوير أو التكبير. حالة الاستخدام: استخدمه عندما تحتاج إلى إضافة نص في موضع محدد على الصفحة دون تعقيد إضافي.

.NET Core 3.1

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void AddTextFragmentWithPosition()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_Text();
    // Create PDF document
    using (var document = new Aspose.Pdf.Document())
    {
        //Add the page
        var page = document.Pages.Add();
        //Create TextFragment object 
        var textFragment = new Aspose.Pdf.Text.TextFragment("Hello, World!");
        //Set absolute positions
        textFragment.Position = new Aspose.Pdf.Text.Position(0, 200);
        //Adding TextFragment to page
        page.Paragraphs.Add(textFragment);
        // Save PDF document
        document.Save(dataDir + "AddTextFragmentWithPosition.pdf");
    }
}

.NET 8

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void AddTextFragmentWithPosition()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_Text();
    // Create PDF document
    using var document = new Aspose.Pdf.Document();
    //Add the page
    var page = document.Pages.Add();
    //Create TextFragment object 
    var textFragment = new Aspose.Pdf.Text.TextFragment("Hello, World!");
    //Set absolute positions
    textFragment.Position = new Aspose.Pdf.Text.Position(0, 200);
    //Adding TextFragment to page
    page.Paragraphs.Add(textFragment);
    // Save PDF document
    document.Save(dataDir + "AddTextFragmentWithPosition.pdf");
}

TextStamp

نظام الإحداثيات: موضع مطلق (أصل السفلي الأيسر). الوصف: يضيف كلاس TextStamp النص كختم إلى الصفحة. داخليًا، ينشئ نموذجًا في موارد الصفحة، مما يجعله عملية أكثر تعقيدًا من TextFragment. المزايا:

• يدعم التحويلات المتقدمة مثل التدوير والتكبير والشفافية.
• مثالي لإضافة علامات مائية أو نص متكرر. العيوب:
• أكثر استهلاكًا للموارد مقارنة بـ TextFragment.
• أكثر تعقيدًا قليلاً في التكوين. حالة الاستخدام: استخدمه لإضافة علامات مائية أو ترويسات أو تذييلات حيث تكون التحويلات أو الاستخدام المتكرر مطلوبًا.

.NET Core 3.1

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void AddTextStamp()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_Text();
    // Create PDF document
    using (var document = new Aspose.Pdf.Document())
    {
        //Add the page
        var page = document.Pages.Add();
        //Create TextStamp object 
        var textStamp = new Aspose.Pdf.TextStamp("Hello, TextStamp!");
        //Set absolute positions
        textStamp.XIndent = 0; 
        textStamp.YIndent = 200;
        //Adding TextStamp to page
        page.AddStamp(textStamp);
        // Save PDF document
        document.Save(dataDir + "AddTextStamp.pdf");
    }
}

.NET 8

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void AddTextStamp()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_Text();
    // Create PDF document
    using var document = new Aspose.Pdf.Document();
    //Add the page
    var page = document.Pages.Add();
    //Create TextStamp object 
    var textStamp = new Aspose.Pdf.TextStamp("Hello, TextStamp!");
    //Set absolute positions
    textStamp.XIndent = 0; 
    textStamp.YIndent = 200;
    //Adding TextStamp to page
    page.AddStamp(textStamp);
    // Save PDF document
    document.Save(dataDir + "AddTextStamp");
}

FloatingBox

نظام الإحداثيات: موضع نسبي (استنادًا إلى هوامش الصفحة). الوصف: كلاس FloatingBox هو حاوية يمكن أن تحتوي على نص أو عناصر أخرى. يتم تعريف موضعه بالنسبة لهوامش الصفحة. المزايا:

• سهل وضع العناصر بالنسبة لتخطيط الصفحة.
• يدعم تغيير الحجم الديناميكي والتفاف المحتوى. العيوب:
• غير مناسب للموضع الدقيق، بكسل مثالي.
• يتطلب تعديلات إضافية لتخطيطات معقدة. حالة الاستخدام: استخدمه لإنشاء تخطيطات حيث يحتاج المحتوى إلى التدفق ديناميكيًا، مثل الترويسات أو التذييلات أو الشريط الجانبي.

.NET Core 3.1

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void AddFloatingBox()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_Text();
    // Create PDF document
    using (var document = new Aspose.Pdf.Document())
    {
        //Add the page
        var page = document.Pages.Add();
        //Create FloatingBox object 
        var floatingBox = new Aspose.Pdf.FloatingBox(200, 100); 
        //Positioning relative to page margin
        floatingBox.Left = 50; 
        floatingBox.Top = 50;
        floatingBox.Paragraphs.Add(new Aspose.Pdf.Text.TextFragment("Hello FloatingBox!"));
        //Adding FloatingBox to page
        page.Paragraphs.Add(floatingBox);
        // Save PDF document
        document.Save(dataDir + "AddFloatingBox.pdf");
    }
}

.NET 8

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void AddFloatingBox()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_Text();
    // Create PDF document
    using var document = new Aspose.Pdf.Document();
    //Add the page
    var page = document.Pages.Add();
    //Create FloatingBox object 
    var floatingBox = new Aspose.Pdf.FloatingBox(200, 100); 
    //Positioning relative to page margin
    floatingBox.Left = 50; 
    floatingBox.Top = 50;
    floatingBox.Paragraphs.Add(new Aspose.Pdf.Text.TextFragment("Hello, FloatingBox!"));
    //Adding FloatingBox to page
    page.Paragraphs.Add(floatingBox);
    // Save PDF document
    document.Save(dataDir + "AddFloatingBox.pdf");
}

Rectangle

نظام الإحداثيات: موضع مطلق (أصل السفلي الأيسر). الوصف: يُستخدم كلاس Rectangle لرسم مناطق أو أشكال على الصفحة. يمكن أيضًا استخدامه مع TextFragmentAbsorber للبحث عن نص داخل منطقة مستطيلة محددة. المزايا:

• مفيد لرسم عناصر رسومية مثل الإطارات أو التمييزات.
• يمكن دمجه مع عناصر أخرى مثل النص أو الصور. العيوب:
• محدود بالأشكال المستطيلة.
• يتطلب خطوات إضافية للتكامل مع محتوى آخر. حالة الاستخدام: استخدمه لرسم إطارات حول العناصر أو تمييز المناطق على الصفحة. استخدمه مع TextFragmentAbsorber للبحث عن نص داخل منطقة محددة.

.NET Core 3.1

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void DrawRectangle()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_Text();
    // Create PDF document
    using (var document = new Aspose.Pdf.Document())
    {
        //Add the page
        var page = document.Pages.Add();
        //Save graphicState
        page.Contents.Add(new Aspose.Pdf.Operators.GSave());
        //Colorize rectangle
        var colorStroke = new Aspose.Pdf.Operators.SetRGBColorStroke(0.7, 0, 0);
        page.Contents.Add(colorStroke);
        //Create and add Rectangle on page
        var rectangle = new Aspose.Pdf.Rectangle(100, 100, 200, 150);
        page.Contents.Add(
            new Aspose.Pdf.Operators.Re(rectangle.LLX,
                rectangle.LLY,
                rectangle.Width,
                rectangle.Height));
        //Close path
        page.Contents.Add(new Aspose.Pdf.Operators.ClosePathStroke());
        //Restore graphic state
        page.Contents.Add(new Aspose.Pdf.Operators.GRestore());
        // Save PDF document
        document.Save(dataDir + "DrawRectangle.pdf");
    }
}

.NET 8

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void DrawRectangle()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_Text();
    // Create PDF document
    using var document = new Aspose.Pdf.Document();
    //Add the page
    var page = document.Pages.Add();
    //Save graphicState
    page.Contents.Add(new Aspose.Pdf.Operators.GSave());
    //Colorize rectangle
    var colorStroke = new Aspose.Pdf.Operators.SetRGBColorStroke(0.7, 0, 0);
    page.Contents.Add(colorStroke);
    //Create and add Rectangle on page
    var rectangle = new Aspose.Pdf.Rectangle(100, 100, 200, 150);
    page.Contents.Add(
        new Aspose.Pdf.Operators.Re(rectangle.LLX,
            rectangle.LLY,
            rectangle.Width,
            rectangle.Height));
    //Close path
    page.Contents.Add(new Aspose.Pdf.Operators.ClosePathStroke());
    //Restore graphic state
    page.Contents.Add(new Aspose.Pdf.Operators.GRestore());
    // Save PDF document
    document.Save(dataDir + "DrawRectangle");
}