Как работать с графикой PDF в C++

Aspose.PDF FOSS for C++ включает небольшую векторную графику API для рисования произвольных форм непосредственно на странице PDF — отдельно от растровых устройств библиотеки (BmpDevice, JpegDevice, TiffDevice), которые преобразуют существующее содержимое страницы в изображения. Это руководство проходит процесс создания контейнера Graph, добавления в него форм Circle, Ellipse и Line, стилизации этих форм с помощью GraphInfo и размещения готового Graph на странице. Библиотека добавляется в проект через CMake.

Пошаговое руководство

add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

#include <aspose/pdf/document.hpp>
#include <iostream>

int main() {
    Aspose::Pdf::Document doc;
    std::cout << "Linked OK — pages: " << doc.Pages().Count() << "\n";
}

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/drawing/graph.hpp>
#include <aspose/pdf/drawing/circle.hpp>
#include <aspose/pdf/drawing/ellipse.hpp>
#include <aspose/pdf/drawing/line.hpp>
#include <aspose/pdf/graph_info.hpp>
#include <aspose/pdf/border_info.hpp>
#include <aspose/pdf/color.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Drawing;

Document doc;
Page page = doc.Pages().Add();

auto graph = std::make_shared<Graph>();
graph->Left(50.0);
graph->Top(50.0);
graph->Width(400.0);
graph->Height(400.0);

page.Paragraphs().Add(graph);

auto circle = std::make_unique<Circle>();
circle->PosX(150.0);
circle->PosY(150.0);
circle->Radius(75.0);
graph->Shapes().push_back(std::move(circle));

auto ellipse = std::make_unique<Ellipse>();
ellipse->Left(20.0);
ellipse->Bottom(20.0);
ellipse->Width(120.0);
ellipse->Height(60.0);
graph->Shapes().push_back(std::move(ellipse));

bool circleFits = circle->CheckBounds(graph->Width(), graph->Height());

auto line = std::make_unique<Line>();
line->PositionArray({0.0f, 0.0f, 400.0f, 400.0f});
graph->Shapes().push_back(std::move(line));

GraphInfo stroke;
stroke.LineWidth(2.0f);
stroke.Color(Color::FromRgb(1.0, 0.0, 0.0));
stroke.FillColor(Color::FromRgb(1.0, 0.9, 0.9));

BorderInfo border{BorderSide::All, 1.5f, Color::Black()};
border.RoundedBorderRadius(6.0);
graph->Border(border);

doc.Save("graphics.pdf");

Распространённые проблемы и их решения

Фигура, которую я построил, никогда не появляется на странице

Создание Circle, Ellipse или Line самостоятельно не оказывает эффекта, пока он не будет добавлен к вектору, возвращаемому Graph в его Shapes(), и этот Graph не будет добавлен на страницу через Page.Paragraphs().Add(). Требуются все три шага — создание, добавление, добавление Graph на страницу.

Фигуры отрисовываются в неверном положении

Graph.Left() и Graph.Top() позиционируют контейнер на странице; свойства фигуры (Circle.PosX()/PosY(), Ellipse.Left()/Bottom(), координаты Line.PositionArray()) описывают геометрию внутри этого контейнера. Проверьте как размещение контейнера, так и собственные координаты фигуры, если вывод выглядит смещённым.

CheckBounds returns false unexpectedly

CheckBounds(containerWidth, containerHeight) проверяет собственную геометрию фигуры относительно переданных размеров — обычно это Width()/Height() принадлежащего Graph, а не полная медиабокc страницы. Передача неверных размеров приводит к ложному отрицательному результату, даже если фигура фактически помещается внутри Graph.

A Line не появляется, или появляется как одна точка

PositionArray() требует как минимум две пары (x, y) — четыре значения float — чтобы описать видимый сегмент. Более короткий вектор не образует линию.

Confusing Circle with AnnotationType::Circle or CircleAnnotation

Библиотека также имеет отдельный API для аннотаций PDF, где AnnotationType::Circle и CircleAnnotation представляют аннотации в виде кругов. Класс Circle, рассмотренный в этом руководстве, не связан с этим — он находится в Aspose::Pdf::Drawing и рисует непосредственно в содержимое страницы, а не добавляет объект аннотации.

Часто задаваемые вопросы

В чём разница между GraphInfo и BorderInfo?

GraphInfo задаёт стиль отдельного штриха — ширину линии, цвет, цвет заливки и шаблон штриха — и используется как для отдельных фигур (через Shape.GraphInfo()), так и для каждого ребра внутри BorderInfo. BorderInfo объединяет четыре значения GraphInfo (Left(), Right(), Top(), Bottom()) плюс RoundedBorderRadius(), чтобы описать собственную рамку границы контейнера Graph.

Могу ли я залить форму сплошным цветом?

Да. GraphInfo.FillColor() задаёт цвет заливки, используемый при рисовании формы через её владеющий Graph.

Сохраняет ли Circle ограничивающий прямоугольник, как делает Ellipse?

Нет. Circle раскрывает PosX(), PosY() и Radius(); Ellipse раскрывает Left(), Bottom(), Width() и Height(). Они не имеют общей геометрической репрезентации, кроме абстрактного базового Shape и стиля GraphInfo.

Можно ли один Graph содержать более одной формы?

Да. Graph.Shapes() возвращает полную коллекцию объектов Shape, размещённых внутри этого Graph — круги, эллипсы и линии могут быть добавлены в один и тот же контейнер.

Это то же самое, что отрисовка страницы в изображение?

Нет. BmpDevice, JpegDevice и TiffDevice растеризуют существующее содержимое страницы в форматы изображений. Graph, Shape, Circle, Ellipse и Line создают новую векторную геометрию непосредственно в PDF-контенте во время создания или редактирования документа.

См. также:

• Руководство разработчика
• Руководство по установке
• Рисование векторной графики на странице PDF (Блог)
• API Reference
• Репозиторий GitHub
• Aspose.PDF for C++ — Enterprise Knowledge Base