Координатная система

В PDF-документе и при работе с библиотекой Aspose.PDF координатная система начинается из нижнего левого угла страницы. Точка (0,0) соответствует нижнему левому углу. Это означает, что при размещении изображений, текста или других объектов важно помнить, что ось Y увеличивается вверх, в отличие от некоторых других координатных систем. Каждая страница имеет свою собственную координатную систему. Координаты указываются в независимых от платформы единицах. Спецификация PDF утверждает, что PDF работает с несколькими координатными пространствами.

Пространство устройства

Каждое выходное устройство — будь то дисплей, принтер и т. д. — использует свою собственную координатную систему для отображения изображений. Эта система называется пространством устройства. Начало (точка 0,0) может находиться в разных позициях в зависимости от устройства. Кроме того, ориентация координатных осей может варьироваться: вертикальная ось Y может увеличиваться либо снизу вверх, либо сверху вниз. Разрешения устройств также различаются. Дисплеи часто имеют разрешение 72 или 96 пикселей на дюйм, в то время как принтеры могут иметь 300, 600 или даже более высокие точки на дюйм. Некоторые устройства могут также иметь разные разрешения по горизонтальной и вертикальной осям. Если графические элементы указаны непосредственно в координатах пространства устройства, результат становится зависимым от характеристик конкретного устройства. Это может привести к искажению отображения: один и тот же объект может выглядеть по-разному на экране и в печати. Например, линия длиной 8 дюймов, указанная в координатах дисплея с разрешением 72 ppi, займет менее одного дюйма при печати на принтере с разрешением 600 dpi.

Пользовательское пространство

Чтобы избежать таких проблем, PDF использует независимую от устройства координатную систему (пользовательское пространство), которая обеспечивает согласованное отображение графики независимо от выходного устройства. Во время отображения страницы содержимое преобразуется из пользовательского пространства в пространство устройства с учетом специфических особенностей выходного устройства. Каждая страница в документе имеет свою собственную систему координат пользовательского пространства. Длина одной единицы по обеим осям равна 1/72 дюйма. Вы можете изменить единицы измерения, установив UserUnit, который по умолчанию равен 1. Это значение можно указать с помощью свойства UserUnit объекта страницы. UserUnit действует как множитель к 1/72 дюйма.

Преобразование из пользовательского пространства в пространство устройства определяется матрицей текущего преобразования (CTM).

Матрица преобразования координатного пространства. Взято из спецификации ISO 32000-2:2020

Изображение 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");
}

Расширенные функции