Primitives

Primitives

This guide covers the small, immutable-in-practice value types that carry geometry and color data through the rest of the API: 2D and 3D points, rectangles, transformation matrices, and color values. You will not usually import these directly by name in simple workflows — they show up as property types on higher-level objects such as annotations, image placements, and 3D views — but knowing their shape makes those objects’ properties easy to read and construct.

Points: Point and Point3D

Point is a plain 2D coordinate with x and y float properties. Point3D is its 3D counterpart, constructed as Point3D(x, y, z) and exposing x, y, and z float properties. Point is the type used for GradientAxialShading.start / end; Matrix3D-based transforms and 3D views operate in the same coordinate space that Point3D describes.

Rectangles

Rectangle(x, y, width, height) describes a position and size, and additionally exposes computed left, bottom, and right float properties alongside x, y, width, and height. Rectangle is the type behind PDF3DAnnotation.rect, so a 3D annotation’s on-page bounds are read and set through the same shape as any other rectangle in the API.

Transformation Matrices: Matrix and Matrix3D

Matrix holds a 2D affine transform as six float components — a, b, c, d, e, f — and provides two methods: translate(x, y) to apply a translation in place, and multiply(other) to compose it with another Matrix, returning the resulting Matrix.

Matrix3D is the 3D counterpart: a 3x3 rotation/scale block (m11 through m33) plus a dx, dy, dz translation component, constructed with no arguments (Matrix3D()) and populated by setting its properties. PDF3DView.ctm is typed as Matrix3D | None — the current transformation matrix for a saved 3D view.

Color Primitives: Color, ColorPrimitive, and GradientAxialShading

Three small types carry color and transparency data:

• Color(pattern_color_space, r, g, b) — a color value with a pattern_color_space property (typed GradientAxialShading | None) for pattern-based fills, and an r float property for its red channel.
• ColorPrimitive() — a minimal color primitive exposing a single transparency: int property.
• GradientAxialShading(start_color, end_color, start, end) — describes an axial (linear) gradient between two colors: start_color and end_color are Color properties, and start / end are Point properties marking the gradient’s axis endpoints.

These three types compose: a Color can reference a GradientAxialShading as its pattern color space, and that shading in turn is defined using two more Color values and two Point values. PDF3DAnnotation.background_color is typed Color | None, so 3D annotation backgrounds are set using the same Color type described here.

Tips and Best Practices

• Construct Rectangle, Point, and Point3D with positional arguments in the documented order (x, y[, z] / x, y, width, height) — these types take plain floats, not keyword-only arguments.
• Use Matrix.multiply() to compose transforms rather than manually combining the six a–f components by hand.
• When a property’s type is optional (for example PDF3DAnnotation.background_color: Color | None or PDF3DView.ctm: Matrix3D | None), check for None before reading nested properties on it.
• Reach for GradientAxialShading only when you need a two-color linear gradient as a pattern color space; for a flat, single color use Color directly.
• Rectangle’s left, bottom, and right properties are derived from x, y, and width/height — treat them as a convenience view of the same rectangle rather than independent state.

Common Issues

FAQ

Do I need to import Point, Rectangle, or Matrix directly in normal usage?

Usually not — you will most often encounter these as the type of a property (like PDF3DAnnotation.rect or PDF3DView.ctm) rather than constructing them from scratch, though nothing prevents constructing them directly when you need a standalone value.

What is the difference between Color and ColorPrimitive?

Color carries RGB-style channel data plus an optional pattern_color_space for gradient fills. ColorPrimitive is a much smaller type that exposes only a transparency value.

How do I combine two transforms with Matrix?

Call matrix_a.multiply(matrix_b), which returns the composed Matrix. Use translate(x, y) for a simple translation without building a full matrix multiplication.

Is Matrix3D used anywhere outside of 3D annotations?

Within this cluster, Matrix3D appears as the type of PDF3DView.ctm — the current transformation matrix associated with a saved 3D view.

API Reference Summary

See Also

• Aspose.PDF — Enterprise Documentation