Primitives

Primitives

本指南涵盖了在实践中保持不可变的小型值类型，这些类型在整个 API 中携带几何和颜色数据：二维和三维点、矩形、变换矩阵以及颜色值。 在简单的工作流中，您通常不会直接按名称导入这些类型——它们会作为属性类型出现在更高级别的对象上，如注释、图像放置和三维视图——但了解它们的结构可以让这些对象的属性更易于读取和构造。

点：Point 和 Point3D

Point 是一个普通的二维坐标，具有 x 和 y 浮点属性。 Point3D 是它的三维对应体，构造为 Point3D(x, y, z)，并公开 x、y 和 z 浮点属性。 Point 是用于 GradientAxialShading.start / end 的类型；基于 Matrix3D 的变换和三维视图在 Point3D 所描述的相同坐标空间中运行。

Rectangles

Rectangle(x, y, width, height) 描述位置和尺寸，并额外公开计算得到的 left、bottom、right 浮点属性，以及 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 视图的当前变换矩阵。

提示与最佳实践

• 按照文档中的顺序（x, y[, z] / x, y, width, height）使用位置参数构造 Rectangle、Point 和 Point3D——这些类型接受普通的 float，而不是仅限关键字的参数。
• 使用 Matrix.multiply() 来组合变换，而不是手动合并六个 a–f 组件。
• 当属性的类型是可选的（例如 PDF3DAnnotation.background_color: Color | None 或 PDF3DView.ctm: Matrix3D | None）时，在读取其嵌套属性之前先检查 None。
• 仅在需要将两色线性渐变用作图案颜色空间时才使用 GradientAxialShading；若只需要单一平面颜色，请直接使用 Color。
• Rectangle 的 left、bottom 和 right 属性来源于 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