Primitives

Primitives

Це керівництво охоплює невеликі, практично незмінні типи значень, які передають геометричні та колірні дані через решту API: 2D та 3D точки, прямокутники, матриці перетворень і колірні значення. Зазвичай ви не імпортуєте їх безпосередньо за назвою у простих робочих процесах — вони з’являються як типи властивостей у об’єктах вищого рівня, таких як анотації, розміщення зображень і 3D-перегляди — проте розуміння їхньої структури полегшує читання та створення властивостей цих об’єктів.

Точки: Point і Point3D

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

Rectangles

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

Матриці перетворень: Matrix і Matrix3D

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

Matrix3D — це 3D-еквівалент: блок обертання/масштабування 3x3 (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