Système de coordonnées

Dans un document PDF et lors de l’utilisation de la bibliothèque Aspose.PDF, le système de coordonnées commence à partir du coin inférieur gauche de la page. Le point (0,0) correspond au coin inférieur gauche. Cela signifie que lors du placement d’images, de texte ou d’autres objets, il est important de se rappeler que l’axe Y augmente vers le haut, contrairement à certains autres systèmes de coordonnées. Chaque page a son propre système de coordonnées. Les coordonnées sont spécifiées en unités indépendantes de la plateforme. La spécification PDF indique que le PDF fonctionne avec plusieurs espaces de coordonnées.

Espace de dispositif

Chaque dispositif de sortie — qu’il s’agisse d’un écran, d’une imprimante, etc. — utilise son propre système de coordonnées pour rendre les images. Ce système est appelé espace de dispositif. L’origine (point 0,0) peut être située à différentes positions selon le dispositif. De plus, l’orientation des axes de coordonnées peut varier : l’axe Y vertical peut augmenter soit de bas en haut, soit de haut en bas. Les résolutions des dispositifs varient également. Les écrans ont souvent une résolution de 72 ou 96 pixels par pouce, tandis que les imprimantes peuvent avoir 300, 600, voire des points par pouce encore plus élevés. Certains dispositifs peuvent également avoir des résolutions différentes le long des axes horizontal et vertical. Si des éléments graphiques sont spécifiés directement en coordonnées d’espace de dispositif, le résultat devient dépendant des caractéristiques du dispositif particulier. Cela peut entraîner un rendu déformé : le même objet peut apparaître différemment à l’écran et à l’impression. Par exemple, une ligne de 8 pouces de long, spécifiée en coordonnées d’affichage avec une résolution de 72 ppi, occuperait moins d’un pouce lorsqu’elle est imprimée sur une imprimante de 600 dpi.

Espace utilisateur

Pour éviter de tels problèmes, le PDF utilise un système de coordonnées indépendant du dispositif (espace utilisateur) qui garantit un rendu graphique cohérent, quel que soit le dispositif de sortie. Lors du rendu de la page, le contenu est transformé de l’espace utilisateur à l’espace de dispositif, en tenant compte des caractéristiques spécifiques du dispositif de sortie. Chaque page du document a son propre système de coordonnées d’espace utilisateur. La longueur d’une unité le long des deux axes est égale à 1/72 pouce. Vous pouvez changer les unités de mesure en définissant le UserUnit, qui par défaut est égal à 1. Cette valeur peut être spécifiée à l’aide de la propriété UserUnit de l’objet page. Le UserUnit agit comme un multiplicateur de 1/72 pouce.

La transformation de l’espace utilisateur à l’espace de dispositif est définie par la Matrice de Transformation Courante (CTM).

Image 1. Transformation de la matrice de l’espace de coordonnées. Tiré de la spécification ISO 32000-2:2020

Si vous créez du contenu de page en utilisant des opérateurs PDF, vous pouvez modifier la CTM (Matrice de Transformation Courante) en utilisant l’opérateur Aspose.Pdf.ConcatenateMatrix, qui concatène la matrice actuelle avec celle que vous fournissez. Cela vous permet d’effectuer des rotations, des translations et des mises à l’échelle du contenu rendu.

Image 2. Transformation vers l’espace de dispositif. Tiré de la spécification ISO 32000-2:2020

En plus de l’espace utilisateur et de l’espace de dispositif, le PDF utilise plusieurs autres systèmes de coordonnées, chacun servant des objectifs spécifiques :

Espace de texte

Le texte est positionné dans son propre système de coordonnées — espace de texte. La transformation de l’espace de texte à l’espace utilisateur est effectuée à l’aide d’une matrice de texte dédiée ainsi que de divers paramètres de rendu de texte.

Espace de glyphe

Les caractères de police (glyphes) sont définis dans l’espace de glyphe. Cet espace est transformé en espace de texte via la matrice de police. Pour la plupart des polices, une échelle de 1000 unités d’espace de glyphe = 1 unité d’espace de texte est utilisée. Dans certaines polices, telles que les polices de type 3, cette matrice est explicitement définie.

Espace d’image

Les images raster sont définies dans leur propre espace d’image. Cet espace est toujours automatiquement transformé en espace utilisateur : les images sont considérées comme ayant une largeur et une hauteur de 1 unité, quelle que soit leur résolution réelle. Pour afficher correctement une image, son échelle et sa position sont définies en modifiant la matrice de transformation (mise à l’échelle, rotation).

Espace de formulaire

Les formulaires (Form XObjects) sont des fragments de contenu indépendants qui peuvent être intégrés en tant qu’éléments graphiques. Chaque formulaire est défini dans son propre espace de formulaire, qui est ensuite transformé en espace utilisateur à l’aide d’une matrice de formulaire.

Image 3. Relations entre les espaces de coordonnées. Tiré de la spécification ISO 32000-2:2020

Matrice de transformation

Cette matrice permet des opérations telles que la mise à l’échelle, la rotation, la translation, le cisaillement et la réflexion des objets sur la page. C’est une matrice bidimensionnelle 3×3, mais dans le PDF, seuls 6 paramètres numériques sont utilisés : [a b c d e f]. Cette matrice est appliquée à chaque point (x, y) de l’espace transformé à l’aide des formules suivantes : x’ = a * x + c * y + e
y’ = b * x + d * y + f

Image 4. Équation de transformation des coordonnées. Tiré de la spécification ISO 32000-2:2020

Formule de transformation des coordonnées — tirée de la spécification ISO 32000-2:2020. Selon les valeurs des éléments de la matrice, différents types de transformations peuvent être définis :

• Translation : [1 0 0 1 e f] — déplace un objet de e unités le long de l’axe X et de f unités le long de l’axe Y.
• Mise à l’échelle : [a 0 0 d 0 0] — met à l’échelle un objet de a fois le long de X et de d fois le long de Y.
• Rotation : [cos(θ) sin(θ) -sin(θ) cos(θ) 0 0] — fait tourner un objet d’un angle θ (en radians).
• Cisaillement : Le long de X [1 0 c 1 0 0], Le long de Y [1 b 0 1 0 0].
• Réflexion : À travers l’axe X [1 0 0 -1 0 0], À travers l’axe Y [-1 0 0 1 0 0]

Exemple de définition d’une matrice de transformation :

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

Dans l’Exemple 1, vous pouvez voir qu’essayer de rendre du texte aux coordonnées des coins de la page ne rend visible que le texte à l’origine. Le reste du texte tombe en dehors de la zone visible et est coupé.

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

Image 5. Le résultat de l’exécution de l’exemple 1.

Dans l’Exemple 2, nous mettons à l’échelle le système de coordonnées et le déplaçons vers le centre de la page.

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

Image 6. Le résultat de l’exécution de l’exemple 2.

Comprendre les systèmes de coordonnées et le positionnement dans Aspose.PDF

Lors de l’utilisation d’Aspose.PDF, il est important de comprendre les différences entre les objets utilisés pour le positionnement et leurs systèmes de coordonnées respectifs. Voici une explication détaillée des objets clés (TextFragment, TextStamp, FloatingBox, Rectangle) et de leurs cas d’utilisation, ainsi que leurs avantages et inconvénients.

TextFragment

Système de coordonnées : Positionnement absolu (origine en bas à gauche). Description : La classe TextFragment vous permet d’ajouter du texte à une position spécifique sur la page en utilisant des coordonnées absolues. Avantages :

• Simple et efficace pour ajouter du texte à des positions précises.
• Opération légère par rapport à TextStamp. Inconvénients :
• Ne prend pas en charge les transformations avancées comme la rotation ou la mise à l’échelle. Cas d’utilisation : Utilisez lorsque vous devez ajouter du texte à une position spécifique sur la page sans complexité supplémentaire.

.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

Système de coordonnées : Positionnement absolu (origine en bas à gauche). Description : La classe TextStamp ajoute du texte en tant que tampon à la page. En interne, elle crée un formulaire dans les ressources de la page, ce qui en fait une opération plus complexe que TextFragment. Avantages :

• Prend en charge des transformations avancées comme la rotation, la mise à l’échelle et l’opacité.
• Idéal pour ajouter des filigranes ou du texte répété. Inconvénients :
• Plus gourmand en ressources par rapport à TextFragment. Légèrement plus complexe à configurer. Cas d’utilisation : Utilisez pour ajouter des filigranes, des en-têtes ou des pieds de page où des transformations ou une utilisation répétée sont nécessaires.

.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

Système de coordonnées : Positionnement relatif (basé sur les marges de la page). Description : La classe FloatingBox est un conteneur qui peut contenir du texte ou d’autres éléments. Sa position est définie par rapport aux marges de la page. Avantages :

• Facile à positionner des éléments par rapport à la mise en page de la page.
• Prend en charge le redimensionnement dynamique et le retour à la ligne du contenu. Inconvénients :
• Pas adapté pour un placement précis, pixel par pixel.
• Nécessite des ajustements supplémentaires pour des mises en page complexes. Cas d’utilisation : Utilisez pour créer des mises en page où le contenu doit s’écouler dynamiquement, comme des en-têtes, des pieds de page ou des barres latérales.

.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

Système de coordonnées : Positionnement absolu (origine en bas à gauche). Description : La classe Rectangle est utilisée pour dessiner des zones ou des formes sur la page. Elle peut également être utilisée avec le TextFragmentAbsorber pour rechercher du texte dans une zone rectangulaire spécifique. Avantages :

• Utile pour dessiner des éléments graphiques comme des cadres ou des surlignages.
• Peut être combiné avec d’autres éléments comme du texte ou des images. Inconvénients :
• Limité aux formes rectangulaires. Nécessite des étapes supplémentaires pour s’intégrer à d’autres contenus. Cas d’utilisation : Utilisez pour dessiner des cadres autour des éléments ou pour surligner des zones sur la page. Utilisez avec TextFragmentAbsorber pour rechercher du texte dans une zone spécifique.

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