Primitives

Primitives

Acest ghid acoperă tipurile de valori mici, practic imuabile, care transportă date de geometrie și culoare prin restul API: puncte 2D și 3D, dreptunghiuri, matrici de transformare și valori de culoare. De obicei nu veți importa aceste tipuri direct prin nume în fluxuri de lucru simple — apar ca tipuri de proprietate pe obiecte de nivel superior, cum ar fi adnotări, plasări de imagini și vizualizări 3D — dar cunoașterea formei lor face ca proprietățile acelor obiecte să fie ușor de citit și de construit.

Puncte: Point și Point3D

Point este o coordonată 2D simplă cu proprietăți float x și y. Point3D este omologul său 3D, construit ca Point3D(x, y, z) și expune proprietăți float x, y și z. Point este tipul utilizat pentru GradientAxialShading.start / end; transformările bazate pe Matrix3D și vizualizările 3D operează în același spațiu de coordonate pe care Point3D îl descrie.

Rectangles

Rectangle(x, y, width, height) descrie o poziție și dimensiune și, în plus, expune proprietăți float calculate left, bottom și right alături de x, y, width și height. Rectangle este tipul din spatele PDF3DAnnotation.rect, astfel încât limitele pe pagină ale unei adnotări 3D sunt citite și setate prin aceeași formă ca orice alt dreptunghi din API.

Matrici de transformare: Matrix și Matrix3D

Matrix conține o transformare afine 2D ca șase componente float — a, b, c, d, e, f — și oferă două metode: translate(x, y) pentru a aplica o translație în loc, și multiply(other) pentru a o compune cu un alt Matrix, returnând Matrix rezultat.

Matrix3D este omologul 3D: un bloc de rotație/scalare 3x3 (m11 până la m33) plus o componentă de translație dx, dy, dz, construit fără argumente (Matrix3D()) și populat prin setarea proprietăților sale. PDF3DView.ctm are tipul Matrix3D | None — matricea de transformare curentă pentru o vizualizare 3D salvată.

Sfaturi și bune practici

• Construiți Rectangle, Point și Point3D cu argumente poziționale în ordinea documentată (x, y[, z] / x, y, width, height) — aceste tipuri acceptă float-uri simple, nu argumente doar pe cuvânt cheie.
• Folosiți Matrix.multiply() pentru a compune transformările în loc să combinați manual cele șase componente a–f.
• Când tipul unei proprietăți este opțional (de exemplu PDF3DAnnotation.background_color: Color | None sau PDF3DView.ctm: Matrix3D | None), verificați None înainte de a citi proprietățile încorporate ale acesteia.
• Apelați la GradientAxialShading doar când aveți nevoie de un gradient liniar cu două culori ca spațiu de culoare de tip model; pentru o singură culoare uniformă folosiți direct Color.
• Proprietățile left, bottom și right ale lui Rectangle sunt derivate din x, y și width/height — tratați-le ca pe o vedere convenabilă a aceluiași dreptunghi, nu ca stare independentă.

Probleme comune

FAQ

Trebuie să import Point, Rectangle sau Matrix direct în utilizarea normală?

De obicei nu — le veți întâlni cel mai adesea ca tipul unei proprietăți (cum ar fi PDF3DAnnotation.rect sau PDF3DView.ctm) mai degrabă decât să le construiți de la zero, deși nimic nu împiedică construirea lor directă când aveți nevoie de o valoare independentă.

Care este diferența dintre Color și ColorPrimitive?

Color conține date de canal în stil RGB plus un pattern_color_space opțional pentru umpleri de gradient. ColorPrimitive este un tip mult mai mic care expune doar o valoare transparency.

Cum combin două transformări cu Matrix?

Apelați matrix_a.multiply(matrix_b), care returnează Matrix compus. Utilizați translate(x, y) pentru o translație simplă fără a construi o multiplicare completă a matricei.

Este Matrix3D utilizat în altă parte în afara adnotărilor 3D?

În cadrul acestui grup, Matrix3D apare ca tipul lui PDF3DView.ctm — matricea de transformare curentă asociată cu o vizualizare 3D salvată.

API Reference Rezumat

Vezi și:

• Aspose.PDF for Python — Enterprise Documentation