Primitives

Primitives

Это руководство охватывает небольшие, практически неизменяемые типы значений, которые несут геометрические и цветовые данные через остальную часть API: 2D и 3D точки, прямоугольники, матрицы преобразований и цветовые значения. Обычно вы не будете импортировать их напрямую по имени в простых рабочих процессах — они появляются как типы свойств в объектах более высокого уровня, таких как аннотации, размещения изображений и 3D-виды — но знание их структуры упрощает чтение и создание свойств этих объектов.

Точки: Point и Point3D

Point — это простая 2D-координата с плавающими свойствами x и y. Point3D — её 3D-аналог, создаваемый как Point3D(x, y, z) и предоставляющий плавающие свойства x, y и z. Point — тип, используемый для GradientAxialShading.start / end; преобразования на основе Matrix3D и 3D-виды работают в том же координатном пространстве, которое описывает Point3D.

Rectangles

Rectangle(x, y, width, height) описывает позицию и размер, а также дополнительно предоставляет вычисляемые плавающие свойства left, bottom и right вместе с x, y, width и height. Rectangle — тип, лежащий в основе PDF3DAnnotation.rect, поэтому границы 3D-аннотации на странице читаются и задаются через ту же форму, что и любой другой прямоугольник в API.

Матрицы преобразований: Matrix и Matrix3D

Matrix хранит 2D аффинное преобразование в виде шести компонентов с плавающей точкой — a, b, c, d, e, f — и предоставляет два метода: translate(x, y) для применения трансляции на месте и multiply(other) для композиции с другим Matrix, возвращая полученный Matrix.

Matrix3D — 3D-аналог: блок вращения/масштабирования 3×3 (m11-m33) плюс компонент трансляции dx, dy, dz, создаваемый без аргументов (Matrix3D()) и заполняемый путем установки его свойств. PDF3DView.ctm имеет тип Matrix3D | None — текущая матрица преобразования сохранённого 3D-вида.

Советы и лучшие практики

• Создавайте Rectangle, Point и Point3D с позиционными аргументами в задокументированном порядке (x, y[, z] / x, y, width, height) — эти типы принимают обычные float-значения, а не только именованные аргументы.
• Используйте Matrix.multiply() для композиции преобразований, а не вручную объединяйте шесть компонентов a–f.
• Когда тип свойства является необязательным (например, PDF3DAnnotation.background_color: Color | None или PDF3DView.ctm: Matrix3D | None), проверяйте наличие None, прежде чем считывать вложенные свойства.
• Обращайтесь к GradientAxialShading только когда нужен двухцветный линейный градиент в качестве цветового пространства шаблона; для плоского одноцветного решения используйте Color напрямую.
• Свойства left, bottom и right объекта Rectangle выводятся из x, y и width/height — рассматривайте их как удобный вид одного и того же прямоугольника, а не как независимое состояние.

Общие проблемы

FAQ

Нужен ли мне прямой импорт Point, Rectangle или Matrix при обычном использовании?

Обычно нет — вы чаще всего встретите их в качестве типа свойства (например, PDF3DAnnotation.rect или PDF3DView.ctm), а не будете создавать их с нуля, хотя ничто не мешает создавать их напрямую, когда нужен отдельный объект.

В чём разница между Color и ColorPrimitive?

Color содержит данные каналов в стиле RGB плюс необязательный pattern_color_space для градиентных заливок. ColorPrimitive — гораздо более маленький тип, который раскрывает только значение transparency.

Как объединить два преобразования с помощью Matrix?

Вызовите matrix_a.multiply(matrix_b), который возвращает составной Matrix. Используйте translate(x, y) для простого сдвига без построения полного умножения матриц.

Используется ли Matrix3D где-либо за пределами 3D-аннотаций?

Внутри этого кластера Matrix3D отображается как тип PDF3DView.ctm — текущая матрица преобразования, связанная с сохранённым 3D-видом.

API Reference Сводка

См. также:

• Aspose.PDF for Python — Enterprise Documentation