Primitives

Primitives

Questa guida copre i piccoli tipi di valore, immutabili nella pratica, che trasportano dati di geometria e colore attraverso il resto del API: punti 2D e 3D, rettangoli, matrici di trasformazione e valori di colore. Di solito non importerai questi direttamente per nome nei flussi di lavoro semplici — compaiono come tipi di proprietà su oggetti di livello superiore come annotazioni, posizionamenti di immagini e viste 3D — ma conoscere la loro struttura rende le proprietà di quegli oggetti facili da leggere e costruire.

Punti: Point e Point3D

Point è una semplice coordinata 2D con le proprietà float x e y. Point3D è la sua controparte 3D, costruita come Point3D(x, y, z) ed espone le proprietà float x, y e z. Point è il tipo usato per GradientAxialShading.start / end; le trasformazioni basate su Matrix3D e le viste 3D operano nello stesso spazio di coordinate che descrive Point3D.

Rectangles

Rectangle(x, y, width, height) descrive una posizione e una dimensione, e inoltre espone le proprietà float calcolate left, bottom e right insieme a x, y, width e height. Rectangle è il tipo alla base di PDF3DAnnotation.rect, così i limiti sulla pagina di un’annotazione 3D sono letti e impostati tramite la stessa forma di qualsiasi altro rettangolo nel API.

Matrici di trasformazione: Matrix e Matrix3D

Matrix contiene una trasformazione affine 2D come sei componenti float — a, b, c, d, e, f — e fornisce due metodi: translate(x, y) per applicare una traslazione in loco, e multiply(other) per comporla con un altro Matrix, restituendo il Matrix risultante.

Matrix3D è la controparte 3D: un blocco di rotazione/scalatura 3x3 (m11 fino a m33) più una componente di traduzione dx, dy, dz, costruito senza argomenti (Matrix3D()) e popolato impostando le sue proprietà. PDF3DView.ctm è tipizzato come Matrix3D | None — la matrice di trasformazione corrente per una vista 3D salvata.

Suggerimenti e migliori pratiche

• Costruisci Rectangle, Point e Point3D con argomenti posizionali nell’ordine documentato (x, y[, z] / x, y, width, height) — questi tipi accettano float semplici, non argomenti solo keyword.
• Usa Matrix.multiply() per comporre le trasformazioni invece di combinare manualmente i sei componenti a–f a mano.
• Quando il tipo di una proprietà è opzionale (ad esempio PDF3DAnnotation.background_color: Color | None o PDF3DView.ctm: Matrix3D | None), verifica la presenza di None prima di leggere le proprietà annidate su di essa.
• Ricorri a GradientAxialShading solo quando ti serve un gradiente lineare a due colori come spazio colore del pattern; per un colore piatto e unico usa direttamente Color.
• Le proprietà left, bottom e right di Rectangle sono derivate da x, y e width/height — considerale come una vista di comodità dello stesso rettangolo piuttosto che uno stato indipendente.

Problemi comuni

FAQ

Devo importare Point, Rectangle o Matrix direttamente nell’uso normale?

Di solito no — li incontrerai più spesso come tipo di una proprietà (come PDF3DAnnotation.rect o PDF3DView.ctm) piuttosto che costruirli da zero, anche se nulla impedisce di costruirli direttamente quando ti serve un valore autonomo.

Qual è la differenza tra Color e ColorPrimitive?

Color contiene dati di canale in stile RGB più un opzionale pattern_color_space per i riempimenti a gradiente. ColorPrimitive è un tipo molto più piccolo che espone solo un valore transparency.

Come posso combinare due trasformazioni con Matrix?

Chiama matrix_a.multiply(matrix_b), che restituisce il Matrix composito. Usa translate(x, y) per una semplice traslazione senza costruire una moltiplicazione completa di matrici.

Matrix3D è usato da qualche parte al di fuori delle annotazioni 3D?

All’interno di questo cluster, Matrix3D appare come il tipo di PDF3DView.ctm — la matrice di trasformazione corrente associata a una vista 3D salvata.

API Reference Riepilogo

Vedi anche

• Aspose.PDF for Python — Enterprise Documentation