Sistema de coordenadas

Em um documento PDF e ao trabalhar com a biblioteca Aspose.PDF, o sistema de coordenadas começa no canto inferior esquerdo da página. O ponto (0,0) corresponde ao canto inferior esquerdo. Isso significa que, ao posicionar imagens, texto ou outros objetos, é importante lembrar que o eixo Y aumenta para cima, ao contrário de alguns outros sistemas de coordenadas. Cada página tem seu próprio sistema de coordenadas. As coordenadas são especificadas em unidades independentes de plataforma. A especificação PDF afirma que o PDF opera com múltiplos espaços de coordenadas.

Espaço do Dispositivo

Cada dispositivo de saída — seja um display, impressora, etc. — usa seu próprio sistema de coordenadas para renderizar imagens. Esse sistema é chamado de espaço do dispositivo. A origem (ponto 0,0) pode estar localizada em diferentes posições, dependendo do dispositivo. Além disso, a orientação dos eixos de coordenadas pode variar: o eixo Y vertical pode aumentar de baixo para cima ou de cima para baixo. As resoluções dos dispositivos também variam. Displays geralmente têm uma resolução de 72 ou 96 pixels por polegada, enquanto impressoras podem ter 300, 600 ou até mais pontos por polegada. Alguns dispositivos também podem ter resoluções diferentes ao longo dos eixos horizontal e vertical. Se elementos gráficos forem especificados diretamente em coordenadas de espaço do dispositivo, o resultado se torna dependente das características do dispositivo em particular. Isso pode levar a uma renderização distorcida: o mesmo objeto pode aparecer de maneira diferente na tela e na impressão. Por exemplo, uma linha de 8 polegadas de comprimento, especificada em coordenadas de display com uma resolução de 72 ppi, ocuparia menos de uma polegada quando impressa em uma impressora de 600 dpi.

Espaço do Usuário

Para evitar tais problemas, o PDF usa um sistema de coordenadas independente de dispositivo (espaço do usuário) que garante uma renderização gráfica consistente, independentemente do dispositivo de saída. Durante a renderização da página, o conteúdo é transformado do espaço do usuário para o espaço do dispositivo, levando em conta as características específicas do dispositivo de saída. Cada página no documento tem seu próprio sistema de coordenadas de espaço do usuário. O comprimento de uma unidade ao longo de ambos os eixos é igual a 1/72 polegada. Você pode alterar as unidades de medida definindo o UserUnit, que por padrão é igual a 1. Esse valor pode ser especificado usando a propriedade UserUnit do objeto da página. O UserUnit atua como um multiplicador para 1/72 polegada.

A transformação do espaço do usuário para o espaço do dispositivo é definida pela Matriz de Transformação Atual (CTM).

Imagem 1. Transformação da matriz do espaço de coordenadas. Retirado da especificação ISO 32000-2:2020

Se você estiver criando conteúdo de página usando operadores PDF, pode modificar a CTM (Matriz de Transformação Atual) usando o operador Aspose.Pdf.ConcatenateMatrix, que concatena a matriz atual com a que você fornece. Isso permite que você realize rotação, tradução e escalonamento do conteúdo renderizado.

Imagem 2. Transformação para o espaço do dispositivo. Retirado da especificação ISO 32000-2:2020

Além do espaço do usuário e do espaço do dispositivo, o PDF usa vários outros sistemas de coordenadas, cada um servindo a propósitos específicos:

Espaço de Texto

O texto é posicionado em seu próprio sistema de coordenadas — espaço de texto. A transformação do espaço de texto para o espaço do usuário é realizada usando uma matriz de texto dedicada, juntamente com várias configurações de renderização de texto.

Espaço de Glifos

Os caracteres de fonte (glifos) são definidos no espaço de glifos. Esse espaço é transformado em espaço de texto através da matriz de fonte. Para a maioria das fontes, uma escala de 1000 unidades de espaço de glifos = 1 unidade de espaço de texto é usada. Em algumas fontes, como fontes do Tipo 3, essa matriz é explicitamente definida.

Espaço de Imagem

Imagens rasterizadas são definidas em seu próprio espaço de imagem. Esse espaço é sempre automaticamente transformado em espaço do usuário: as imagens são consideradas como tendo uma largura e altura de 1 unidade, independentemente de sua resolução real. Para exibir corretamente uma imagem, sua escala e posição são definidas modificando a matriz de transformação (escalonamento, rotação).

Espaço de Formulário

Formulários (Form XObjects) são fragmentos de conteúdo independentes que podem ser incorporados como elementos gráficos. Cada formulário é definido em seu próprio espaço de formulário, que é então transformado em espaço do usuário usando uma matriz de formulário.

Imagem 3. Relações entre espaços de coordenadas. Retirado da especificação ISO 32000-2:2020

Matriz de Transformação

Essa matriz permite operações como escalonamento, rotação, tradução, cisalhamento e reflexão de objetos na página. É uma matriz bidimensional 3×3, mas no PDF apenas 6 parâmetros numéricos são usados: [a b c d e f]. Essa matriz é aplicada a cada ponto (x, y) do espaço transformado usando as seguintes fórmulas: x’ = a * x + c * y + e
y’ = b * x + d * y + f

Imagem 4. Equação de transformação de coordenadas. Retirado da especificação ISO 32000-2:2020

Fórmula de transformação de coordenadas — retirada da especificação ISO 32000-2:2020. Dependendo dos valores dos elementos da matriz, diferentes tipos de transformações podem ser definidos:

• Tradução: [1 0 0 1 e f] — move um objeto por e unidades ao longo do eixo X e f unidades ao longo do eixo Y.
• Escalonamento: [a 0 0 d 0 0] — escala um objeto por a vezes ao longo de X e d vezes ao longo de Y.
• Rotação: [cos(θ) sin(θ) -sin(θ) cos(θ) 0 0] — rotaciona um objeto por um ângulo θ (em radianos).
• Cisalhamento: Ao longo de X [1 0 c 1 0 0], Ao longo de Y [1 b 0 1 0 0].
• Reflexão: Através do eixo X [1 0 0 -1 0 0], Através do eixo Y [-1 0 0 1 0 0]

Exemplo de configuração de uma matriz de transformação:

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

No Exemplo 1, você pode ver que tentar renderizar texto nas coordenadas do canto da página resulta em apenas o texto na origem sendo visível. O restante do texto fica fora da área visível e é cortado.

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

Imagem 5. O resultado da execução do exemplo 1.

No Exemplo 2, escalonamos o sistema de coordenadas e o deslocamos para o centro da página.

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

Imagem 6. O resultado da execução do exemplo 2.

Compreendendo Sistemas de Coordenadas e Posicionamento em Aspose.PDF

Ao trabalhar com Aspose.PDF, é importante entender as diferenças entre os objetos usados para posicionamento e seus respectivos sistemas de coordenadas. Abaixo está uma explicação detalhada dos principais objetos (TextFragment, TextStamp, FloatingBox, Rectangle) e seus casos de uso, juntamente com seus prós e contras.

TextFragment

Sistema de Coordenadas: Posicionamento absoluto (origem no canto inferior esquerdo). Descrição: A classe TextFragment permite adicionar texto a uma posição específica na página usando coordenadas absolutas. Prós:

• Simples e eficiente para adicionar texto em posições precisas.
• Operação leve em comparação com TextStamp. Contras:
• Não suporta transformações avançadas como rotação ou escalonamento. Caso de Uso: Use quando precisar adicionar texto em uma posição específica na página sem complexidade adicional.

.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

Sistema de Coordenadas: Posicionamento absoluto (origem no canto inferior esquerdo). Descrição: A classe TextStamp adiciona texto como um carimbo à página. Internamente, ela cria um formulário nos recursos da página, tornando-a uma operação mais complexa do que o TextFragment. Prós:

• Suporta transformações avançadas como rotação, escalonamento e opacidade.
• Ideal para adicionar marcas d’água ou texto repetido. Contras:
• Mais intensiva em recursos em comparação com o TextFragment.
• Um pouco mais complexa de configurar. Caso de Uso: Use para adicionar marcas d’água, cabeçalhos ou rodapés onde transformações ou uso repetido são necessários.

.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

Sistema de Coordenadas: Posicionamento relativo (baseado nas margens da página). Descrição: A classe FloatingBox é um contêiner que pode conter texto ou outros elementos. Sua posição é definida em relação às margens da página. Prós:

• Fácil de posicionar elementos em relação ao layout da página.
• Suporta redimensionamento dinâmico e quebra de conteúdo. Contras:
• Não é adequada para posicionamento preciso e perfeito em pixels.
• Requer ajustes adicionais para layouts complexos. Caso de Uso: Use para criar layouts onde o conteúdo precisa fluir dinamicamente, como cabeçalhos, rodapés ou barras laterais.

.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

Sistema de Coordenadas: Posicionamento absoluto (origem no canto inferior esquerdo). Descrição: A classe Rectangle é usada para desenhar áreas ou formas na página. Também pode ser usada com o TextFragmentAbsorber para buscar texto dentro de uma área retangular específica. Prós:

• Útil para desenhar elementos gráficos como quadros ou destaques.
• Pode ser combinada com outros elementos como texto ou imagens. Contras:
• Limitada a formas retangulares.
• Requer etapas adicionais para se integrar com outros conteúdos. Caso de Uso: Use para desenhar quadros ao redor de elementos ou destacar áreas na página. Use com TextFragmentAbsorber para buscar texto dentro de uma área específica.

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