Sistem koordinat

Dalam dokumen PDF dan saat bekerja dengan pustaka Aspose.PDF, sistem koordinat dimulai dari sudut kiri bawah halaman. Titik (0,0) sesuai dengan sudut kiri bawah. Ini berarti bahwa saat menempatkan gambar, teks, atau objek lainnya, penting untuk diingat bahwa sumbu Y meningkat ke atas, tidak seperti di beberapa sistem koordinat lainnya. Setiap halaman memiliki sistem koordinatnya sendiri. Koordinat ditentukan dalam unit yang independen dari platform. Spesifikasi PDF menyatakan bahwa PDF beroperasi dengan beberapa ruang koordinat.

Ruang Perangkat

Setiap perangkat keluaran — apakah tampilan, printer, dll. menggunakan sistem koordinatnya sendiri untuk merender gambar. Sistem ini disebut ruang perangkat. Titik asal (titik 0,0) dapat terletak di posisi yang berbeda tergantung pada perangkat. Selain itu, orientasi sumbu koordinat dapat bervariasi: sumbu Y vertikal dapat meningkat baik dari bawah ke atas atau dari atas ke bawah. Resolusi perangkat juga bervariasi. Tampilan sering memiliki resolusi 72 atau 96 piksel per inci, sedangkan printer mungkin memiliki 300, 600, atau bahkan lebih tinggi titik per inci. Beberapa perangkat juga mungkin memiliki resolusi yang berbeda di sepanjang sumbu horizontal dan vertikal. Jika elemen grafis ditentukan langsung dalam koordinat ruang perangkat, hasilnya menjadi tergantung pada karakteristik perangkat tertentu. Ini dapat menyebabkan rendering yang terdistorsi: objek yang sama mungkin muncul berbeda di layar dan dalam cetakan. Sebagai contoh, garis sepanjang 8 inci, yang ditentukan dalam koordinat tampilan dengan resolusi 72 ppi, akan menempati kurang dari satu inci saat dicetak pada printer 600 dpi.

Ruang Pengguna

Untuk menghindari masalah tersebut, PDF menggunakan sistem koordinat yang independen dari perangkat (ruang pengguna) yang memastikan rendering grafis yang konsisten terlepas dari perangkat keluaran. Selama rendering halaman, konten diubah dari ruang pengguna ke ruang perangkat, dengan mempertimbangkan fitur spesifik dari perangkat keluaran. Setiap halaman dalam dokumen memiliki sistem koordinat ruang pengguna sendiri. Panjang satu unit di sepanjang kedua sumbu sama dengan 1/72 inci. Anda dapat mengubah unit pengukuran dengan mengatur UserUnit, yang secara default sama dengan 1. Nilai ini dapat ditentukan menggunakan properti UserUnit dari objek halaman. UserUnit bertindak sebagai pengali untuk 1/72 inci.

Transformasi dari ruang pengguna ke ruang perangkat didefinisikan oleh Matriks Transformasi Saat Ini (CTM).

Gambar 1. Transformasi matriks ruang koordinat. Diambil dari spesifikasi ISO 32000-2:2020

Jika Anda membuat konten halaman menggunakan operator PDF, Anda dapat memodifikasi CTM (Matriks Transformasi Saat Ini) menggunakan operator Aspose.Pdf.ConcatenateMatrix, yang menggabungkan matriks saat ini dengan yang Anda berikan. Ini memungkinkan Anda untuk melakukan rotasi, translasi, dan skala konten yang dirender.

Gambar 2. Transformasi ke ruang perangkat. Diambil dari spesifikasi ISO 32000-2:2020

Selain ruang pengguna dan ruang perangkat, PDF menggunakan beberapa sistem koordinat lainnya, masing-masing melayani tujuan tertentu:

Ruang Teks

Teks diposisikan dalam sistem koordinatnya sendiri—ruang teks. Transformasi dari ruang teks ke ruang pengguna dilakukan menggunakan matriks teks khusus bersama dengan berbagai pengaturan rendering teks.

Ruang Glyph

Karakter font (glyph) didefinisikan dalam ruang glyph. Ruang ini diubah menjadi ruang teks melalui matriks font. Untuk sebagian besar font, skala 1000 unit ruang glyph = 1 unit ruang teks digunakan. Dalam beberapa font, seperti font Tipe 3, matriks ini didefinisikan secara eksplisit.

Ruang Gambar

Gambar raster didefinisikan dalam ruang gambar mereka sendiri. Ruang ini selalu secara otomatis diubah menjadi ruang pengguna: gambar dianggap memiliki lebar dan tinggi 1 unit, terlepas dari resolusi aktual mereka. Untuk menampilkan gambar dengan benar, skala dan posisinya diatur dengan memodifikasi matriks transformasi (skala, rotasi).

Ruang Form

Formulir (Form XObjects) adalah fragmen konten independen yang dapat disematkan sebagai elemen grafis. Setiap formulir didefinisikan dalam ruang formulirnya sendiri, yang kemudian diubah menjadi ruang pengguna menggunakan matriks formulir.

Gambar 3. Hubungan antara ruang koordinat. Diambil dari spesifikasi ISO 32000-2:2020

Matriks Transformasi

Matriks ini memungkinkan operasi seperti skala, rotasi, translasi, shearing, dan refleksi objek di halaman. Ini adalah matriks dua dimensi 3×3, tetapi dalam PDF hanya 6 parameter numerik yang digunakan: [a b c d e f]. Matriks ini diterapkan pada setiap titik (x, y) dari ruang yang ditransformasikan menggunakan rumus berikut: x’ = a * x + c * y + e
y’ = b * x + d * y + f

Gambar 4. Persamaan transformasi koordinat. Diambil dari spesifikasi ISO 32000-2:2020

Formula transformasi koordinat — diambil dari spesifikasi ISO 32000-2:2020. Bergantung pada nilai elemen matriks, berbagai jenis transformasi dapat didefinisikan:

• Translasi: [1 0 0 1 e f] — memindahkan objek sejauh e unit di sepanjang sumbu X dan f unit di sepanjang sumbu Y.
• Skala: [a 0 0 d 0 0] — menskalakan objek sejauh a kali di sepanjang X dan d kali di sepanjang Y.
• Rotasi: [cos(θ) sin(θ) -sin(θ) cos(θ) 0 0] — memutar objek dengan sudut θ (dalam radian).
• Shearing: Sepanjang X [1 0 c 1 0 0], Sepanjang Y [1 b 0 1 0 0].
• Refleksi: Melalui sumbu X [1 0 0 -1 0 0], Melalui sumbu Y [-1 0 0 1 0 0]

Contoh pengaturan matriks transformasi:

// 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));

Dalam Contoh 1, Anda dapat melihat bahwa mencoba merender teks di koordinat sudut halaman hanya menghasilkan teks di titik asal yang terlihat. Sisa teks jatuh di luar area yang terlihat dan terpotong.

.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);
}

Gambar 5. Hasil dari eksekusi contoh 1.

Dalam Contoh 2, kita menskalakan sistem koordinat dan menggesernya ke tengah halaman.

.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");
      
}

Gambar 6. Hasil dari eksekusi contoh 2.

Memahami Sistem Koordinat dan Penempatan di Aspose.PDF

Saat bekerja dengan Aspose.PDF, penting untuk memahami perbedaan antara objek yang digunakan untuk penempatan dan sistem koordinat masing-masing. Di bawah ini adalah penjelasan rinci tentang objek kunci (TextFragment, TextStamp, FloatingBox, Rectangle) dan kasus penggunaannya, bersama dengan pro dan kontra mereka.

TextFragment

Sistem Koordinat: Penempatan absolut (asal kiri bawah). Deskripsi: Kelas TextFragment memungkinkan Anda menambahkan teks ke posisi tertentu di halaman menggunakan koordinat absolut. Pro:

• Sederhana dan efisien untuk menambahkan teks di posisi yang tepat.
• Operasi ringan dibandingkan dengan TextStamp. Kontra:
• Tidak mendukung transformasi lanjutan seperti rotasi atau skala. Kasus Penggunaan: Gunakan saat Anda perlu menambahkan teks di posisi tertentu di halaman tanpa kompleksitas tambahan.

.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

Sistem Koordinat: Penempatan absolut (asal kiri bawah). Deskripsi: Kelas TextStamp menambahkan teks sebagai cap ke halaman. Secara internal, ia membuat formulir dalam sumber daya halaman, menjadikannya operasi yang lebih kompleks dibandingkan dengan TextFragment. Pro:

• Mendukung transformasi lanjutan seperti rotasi, skala, dan opasitas.
• Ideal untuk menambahkan watermark atau teks yang diulang. Kontra:
• Lebih banyak memakan sumber daya dibandingkan dengan TextFragment. Sedikit lebih kompleks untuk dikonfigurasi. Kasus Penggunaan: Gunakan untuk menambahkan watermark, header, atau footer di mana transformasi atau penggunaan berulang diperlukan.

.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

Sistem Koordinat: Penempatan relatif (berdasarkan margin halaman). Deskripsi: Kelas FloatingBox adalah wadah yang dapat menampung teks atau elemen lainnya. Posisi ditentukan relatif terhadap margin halaman. Pro:

• Mudah untuk memposisikan elemen relatif terhadap tata letak halaman.
• Mendukung pengubahan ukuran dinamis dan pembungkusan konten. Kontra:
• Tidak cocok untuk penempatan yang tepat, pixel-perfect.
• Memerlukan penyesuaian tambahan untuk tata letak yang kompleks. Kasus Penggunaan: Gunakan untuk membuat tata letak di mana konten perlu mengalir secara dinamis, seperti header, footer, atau sidebar.

.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

Sistem Koordinat: Penempatan absolut (asal kiri bawah). Deskripsi: Kelas Rectangle digunakan untuk menggambar area atau bentuk di halaman. Ini juga dapat digunakan dengan TextFragmentAbsorber untuk mencari teks dalam area persegi panjang tertentu. Pro:

• Berguna untuk menggambar elemen grafis seperti bingkai atau sorotan.
• Dapat digabungkan dengan elemen lain seperti teks atau gambar. Kontra:
• Terbatas pada bentuk persegi panjang. Memerlukan langkah tambahan untuk mengintegrasikan dengan konten lain. Kasus Penggunaan: Gunakan untuk menggambar bingkai di sekitar elemen atau menyoroti area di halaman. Gunakan dengan TextFragmentAbsorber untuk mencari teks dalam area tertentu.

.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");
}