Primitives
Primitives
Ez az útmutató a kis, gyakorlati értelemben immutábilis értéktípusokat fed le, amelyek geometriai és színadatokat hordoznak a API további részein: 2D és 3D pontok, téglalapok, transzformációs mátrixok és színértékek. Általában nem importálod ezeket közvetlenül név szerint egyszerű munkafolyamatokban – a magasabb szintű objektumok, például annotációk, képelhelyezések és 3D nézetek tulajdonság típusaiként jelennek meg – de a szerkezetük ismerete megkönnyíti ezeknek az objektumoknak a tulajdonságainak olvasását és létrehozását.
Pontok: Point és Point3D
Point egy egyszerű 2D koordináta, amely x és y float tulajdonsággal rendelkezik. Point3D ennek 3D megfelelője, amelyet Point3D(x, y, z)ként állítanak elő, és x, y és z float tulajdonságokat tesz elérhetővé. Point a GradientAxialShading.start / end számára használt típus; a Matrix3D-alapú transzformációk és 3D nézetek ugyanabban a koordináta térben működnek, amelyet a Point3D leír.
Rectangles
Rectangle(x, y, width, height) egy pozíciót és méretet ír le, és további számított left, bottom és right float tulajdonságokat tesz elérhetővé a x, y, width és height mellett. Rectangle a PDF3DAnnotation.rect mögötti típus, így egy 3D annotáció oldalbeli határai ugyanazon alakzaton keresztül olvashatók és állíthatók, mint bármely más téglalap a API-ban.
Transzformációs mátrixok: Matrix és Matrix3D
Matrix egy 2D affín transzformációt tárol hat float komponensként — a, b, c, d, e, f — és két metódust biztosít: translate(x, y) a transzláció helyben történő alkalmazásához, valamint multiply(other) egy másik Matrix-vel való összekapcsoláshoz, amely a kapott Matrix-t adja vissza.
Matrix3D a 3D megfelelője: egy 3x3-os forgatás/méretezés blokk (m11-től m33-ig) plus egy dx, dy, dz transzlációs komponens, amely argumentumok nélkül jön létre (Matrix3D()) és a tulajdonságainak beállításával töltődik fel. PDF3DView.ctm típusa Matrix3D | None — a mentett 3D nézet aktuális transzformációs mátrixa.
Tippek és bevált gyakorlatok
- Hozd létre a(z)
Rectangle,PointésPoint3Dobjektumokat pozíciós argumentumokkal a dokumentált sorrendben (x, y[, z]/x, y, width, height) — ezek a típusok egyszerű float értékeket várnak, nem csak kulcsszó-argumentumokat. - Használd a(z)
Matrix.multiply()-t a transzformációk összekapcsolásához ahelyett, hogy kézzel kombinálnád a hata–fkomponenst. - Ha egy tulajdonság típusa opcionális (például
PDF3DAnnotation.background_color: Color | NonevagyPDF3DView.ctm: Matrix3D | None), ellenőrizd a(z)Nonemeglétét, mielőtt beolvasnád a benne lévő belső tulajdonságokat. - Használd a(z)
GradientAxialShading-t csak akkor, ha két színű lineáris gradientre van szükséged mint mintázat színteret; egy egyenletes, egyetlen színhez használd közvetlenül a(z)Color-t. - A(z)
Rectangleleft,bottomésrighttulajdonságai a(z)x,yéswidth/height-ből származnak — kezeld őket ugyanannak a téglalapnak a kényelmi nézeteként, nem független állapotként.
Gyakori problémák
| Probléma | Ok | Javítás |
|---|---|---|
| A téglalap vagy pont koordinátái felcserélődnek vagy helytelenül skálázódnak | A pozicionális argumentumok rossz sorrendben lettek átadva a Rectangle(x, y, width, height) vagy Point3D(x, y, z) számára | Ellenőrizze újra az argumentumok sorrendjét a konstruktor aláírásával szemben — ezeknél a típusoknál nincs kulcsszó-csak kötelező érvényesítés |
AttributeError szín- vagy mátrix tulajdonság olvasásakor | Tulajdonság elérése egy None értéken egy opcionális mezőből (például background_color, ctm) | Ellenőrizze, hogy az érték nem None, mielőtt a beágyazott tulajdonságokhoz hozzáférne |
| A gradiens egyetlen lapos színként jelenik meg | GradientAxialShading.start és end Point értékei azonosak vagy nagyon közel vannak egymáshoz | Győződjön meg arról, hogy start és end a kívánt gradiens tengely mentén két vizuálisan különálló pontot jelölnek |
FAQ
Szükséges-e közvetlenül importálni a Point, Rectangle vagy Matrix osztályokat a normál használat során?
Általában nem — ezeket leggyakrabban egy tulajdonság típusként (például PDF3DAnnotation.rect vagy PDF3DView.ctm) találod, nem pedig a semmiből történő létrehozásuk során, bár semmi sem akadályozza, hogy közvetlenül létrehozd őket, ha önálló értékre van szükséged.
Mi a különbség a Color és a ColorPrimitive között?
Color RGB-stílusú csatorna adatokat tartalmaz, plusz egy opcionális pattern_color_space a színátmenetes kitöltésekhez. ColorPrimitive egy sokkal kisebb típus, amely csak egy transparency értéket tesz elérhetővé.
Hogyan kombinálhatok két transzformációt a Matrix-szel?
Hívd meg a matrix_a.multiply(matrix_b) függvényt, amely visszaadja az összefűzött Matrix-t. Használd a translate(x, y)-t egy egyszerű eltoláshoz, anélkül hogy teljes mátrixszorzást kellene felépítened.
A Matrix3D-t használják valahol a 3D annotációkon kívül?
Ennek a klaszternak a keretében a Matrix3D a PDF3DView.ctm típusaként jelenik meg — a mentett 3D nézethez kapcsolódó aktuális transzformációs mátrix.
API Reference összefoglaló
| Osztály/Módszer | Leírás |
|---|---|
Point | 2D koordináta (x, y lebegőpontos tulajdonságok) |
Point3D | 3D koordináta (x, y, z float tulajdonságok) |
Rectangle | Pozíció és méret (x, y, width, height, plusz számított left, bottom, right) |
Matrix | 2D affín transzformáció (a–f komponens); translate / multiply módszer |
Matrix3D | 3D transzformációs mátrix (m11–m33 forgatás/skálázás blokk, dx/dy/dz eltolás) |
Color | Színérték opcionális pattern_color_space színátmenetes kitöltéssel |
ColorPrimitive | Minimális színprimitív, amely transparency-t tartalmaz |
GradientAxialShading | Axiális (lineáris) színátmenet két Color érték között két Point végpont mentén |
