Primitives

Primitives

Dieser Leitfaden behandelt die kleinen, praktisch unveränderlichen Wertetypen, die Geometrie- und Farbdaten durch den Rest des API transportieren: 2D- und 3D-Punkte, Rechtecke, Transformationsmatrizen und Farbwerte. In einfachen Workflows importieren Sie diese normalerweise nicht direkt per Name — sie erscheinen als Eigenschaftstypen bei höherwertigen Objekten wie Anmerkungen, Bildplatzierungen und 3D-Ansichten — aber das Verständnis ihrer Struktur erleichtert das Lesen und Erzeugen der Eigenschaften dieser Objekte.

Punkte: Point und Point3D

Point ist eine einfache 2D-Koordinate mit den Float-Eigenschaften x und y. Point3D ist das 3D-Pendant, konstruiert als Point3D(x, y, z) und stellt die Float-Eigenschaften x, y und z bereit. Point ist der Typ, der für GradientAxialShading.start / end verwendet wird; Matrix3D-basierte Transformationen und 3D-Ansichten arbeiten im selben Koordinatenraum, den Point3D beschreibt.

Rectangles

Rectangle(x, y, width, height) beschreibt eine Position und Größe und stellt zusätzlich die berechneten Float-Eigenschaften left, bottom und right neben x, y, width und height bereit. Rectangle ist der Typ hinter PDF3DAnnotation.rect, sodass die Seitenränder einer 3D-Annotation über dieselbe Form wie jedes andere Rechteck im API gelesen und gesetzt werden.

Transformationsmatrizen: Matrix und Matrix3D

Matrix enthält eine 2D-Affine-Transformation als sechs Float-Komponenten — a, b, c, d, e, f — und stellt zwei Methoden bereit: translate(x, y), um eine Translation vor Ort anzuwenden, und multiply(other), um sie mit einer anderen Matrix zu kombinieren, wobei das resultierende Matrix zurückgegeben wird.

Matrix3D ist das 3D-Pendant: ein 3x3 Dreh-/Skalierungsblock (m11 bis m33) plus einer dx, dy, dz Übersetzungskomponente, erstellt ohne Argumente (Matrix3D()) und gefüllt durch Setzen ihrer Eigenschaften. PDF3DView.ctm ist vom Typ Matrix3D | None — die aktuelle Transformationsmatrix für eine gespeicherte 3D-Ansicht.

Tipps und bewährte Verfahren

• Erstelle Rectangle, Point und Point3D mit Positionsargumenten in der dokumentierten Reihenfolge (x, y[, z] / x, y, width, height) — diese Typen akzeptieren reine Floats, keine ausschließlich benannten Argumente.
• Verwende Matrix.multiply(), um Transformationen zu kombinieren, anstatt die sechs a–f Komponenten manuell zusammenzufügen.
• Wenn der Typ einer Eigenschaft optional ist (zum Beispiel PDF3DAnnotation.background_color: Color | None oder PDF3DView.ctm: Matrix3D | None), prüfe auf None, bevor du verschachtelte Eigenschaften daraus ausliest.
• Greife nur auf GradientAxialShading zurück, wenn du einen zweifarbigen linearen Verlauf als Muster-Farbraum benötigst; für eine flache, einfarbige Darstellung verwende direkt Color.
• Die Eigenschaften left, bottom und right von Rectangle leiten sich von x, y und width/height ab — betrachte sie als eine komfortable Ansicht desselben Rechtecks und nicht als unabhängigen Zustand.

Häufige Probleme

FAQ

Muss ich Point, Rectangle oder Matrix bei normaler Verwendung direkt importieren?

In der Regel nicht — Sie werden diese am häufigsten als Typ einer Eigenschaft (wie PDF3DAnnotation.rect oder PDF3DView.ctm) antreffen, statt sie von Grund auf neu zu erstellen, obwohl nichts dagegen spricht, sie direkt zu konstruieren, wenn Sie einen eigenständigen Wert benötigen.

Was ist der Unterschied zwischen Color und ColorPrimitive?

Color enthält RGB-artige Kanaldaten plus ein optionales pattern_color_space für Farbverläufe. ColorPrimitive ist ein viel kleinerer Typ, der nur einen transparency-Wert offenlegt.

Wie kombiniere ich zwei Transformationen mit Matrix?

Rufen Sie matrix_a.multiply(matrix_b) auf, das die zusammengesetzte Matrix zurückgibt. Verwenden Sie translate(x, y) für eine einfache Verschiebung, ohne eine vollständige Matrixmultiplikation zu erstellen.

Wird Matrix3D irgendwo außerhalb von 3D-Anmerkungen verwendet?

Innerhalb dieses Clusters erscheint Matrix3D als Typ von PDF3DView.ctm — die aktuelle Transformationsmatrix, die mit einer gespeicherten 3D-Ansicht verbunden ist.

API Reference Zusammenfassung

Siehe auch

• Aspose.PDF for Python — Enterprise Documentation