Primitives

Primitives

Ce guide couvre les petits types de valeur, immuables en pratique, qui transportent les données de géométrie et de couleur à travers le reste du API: points 2D et 3D, rectangles, matrices de transformation et valeurs de couleur. Vous n’importerez généralement pas ces types directement par leur nom dans les flux de travail simples — ils apparaissent comme types de propriétés sur des objets de niveau supérieur tels que les annotations, les placements d’images et les vues 3D — mais connaître leur forme facilite la lecture et la construction des propriétés de ces objets.

Points: Point et Point3D

Point est une coordonnée 2D simple avec les propriétés flottantes x et y. Point3D est son homologue 3D, construit en tant que Point3D(x, y, z) et exposant les propriétés flottantes x, y et z. Point est le type utilisé pour GradientAxialShading.start / end; les transformations basées sur Matrix3D et les vues 3D fonctionnent dans le même espace de coordonnées que décrit Point3D.

Rectangles

Rectangle(x, y, width, height) décrit une position et une taille, et expose également les propriétés flottantes calculées left, bottom et right ainsi que x, y, width et height. Rectangle est le type derrière PDF3DAnnotation.rect, de sorte que les limites sur la page d’une annotation 3D sont lues et définies via la même forme que tout autre rectangle dans le API.

Matrices de transformation: Matrix et Matrix3D

Matrix contient une transformation affine 2D sous forme de six composantes flottantes — a, b, c, d, e, f — et fournit deux méthodes: translate(x, y) pour appliquer une translation en place, et multiply(other) pour la composer avec un autre Matrix, renvoyant le Matrix résultant.

Matrix3D est la contrepartie 3D: un bloc de rotation/échelle 3×3 (m11 à m33) plus un composant de translation dx, dy, dz, construit sans arguments (Matrix3D()) et rempli en définissant ses propriétés. PDF3DView.ctm est typé comme Matrix3D | None — la matrice de transformation actuelle pour une vue 3D enregistrée.

Conseils et bonnes pratiques

• Construit Rectangle, Point et Point3D avec des arguments positionnels dans l’ordre documenté (x, y[, z] / x, y, width, height) — ces types acceptent des flottants simples, pas d’arguments uniquement nommés.
• Utilise Matrix.multiply() pour composer les transformations plutôt que de combiner manuellement à la main les six composantes a–f.
• Lorsque le type d’une propriété est optionnel (par exemple PDF3DAnnotation.background_color: Color | None ou PDF3DView.ctm: Matrix3D | None), vérifie la présence de None avant de lire les propriétés imbriquées.
• Utilise GradientAxialShading uniquement lorsque tu as besoin d’un dégradé linéaire bicolore comme espace couleur de motif; pour une couleur plate et unique, utilise directement Color.
• Les propriétés left, bottom et right de Rectangle sont dérivées de x, y et width/height — considère-les comme une vue pratique du même rectangle plutôt que comme un état indépendant.

Problèmes courants

FAQ

Dois-je importer directement Point, Rectangle ou Matrix dans une utilisation normale?

Habituellement non— vous les rencontrerez le plus souvent comme type d’une propriété (comme PDF3DAnnotation.rect ou PDF3DView.ctm) plutôt que de les construire à partir de zéro, bien que rien n’empêche de les construire directement lorsque vous avez besoin d’une valeur autonome.

Quelle est la différence entre Color et ColorPrimitive?

Color contient des données de canal de type RVB ainsi qu’un pattern_color_space optionnel pour les remplissages en dégradé. ColorPrimitive est un type beaucoup plus petit qui n’expose qu’une valeur transparency.

Comment combiner deux transformations avec Matrix?

Appelez matrix_a.multiply(matrix_b), qui renvoie le Matrix composé. Utilisez translate(x, y) pour une simple translation sans construire une multiplication de matrice complète.

Matrix3D est-il utilisé ailleurs que dans les annotations 3D ?

Dans ce groupe, Matrix3D apparaît comme le type de PDF3DView.ctm — la matrice de transformation actuelle associée à une vue 3D enregistrée.

API Reference Résumé

Voir aussi

• Aspose.PDF for Python — Enterprise Documentation