Aspose.PDF FOSS
Developer Guide
Primitives

Primitives

Primitives

Tato příručka se zabývá malými, v praxi neměnnými typy hodnot, které přenášejí geometrická a barevná data skrze zbytek API: 2D a 3D body, obdélníky, transformační matice a barevné hodnoty. V jednoduchých pracovních postupech je obvykle nebudete importovat přímo podle názvu—objevují se jako typy vlastností na vyšších objektech, jako jsou anotace, umístění obrázků a 3D pohledy—ale znalost jejich struktury usnadní čtení a vytváření vlastností těchto objektů.

Body: Point a Point3D

Point je jednoduchá 2D souřadnice s vlastnostmi typu float x a y. Point3D je její 3D protějšek, vytvořený jako Point3D(x, y, z) a vystavující vlastnosti typu float x, y a z. Point je typ používaný pro GradientAxialShading.start / end; transformace založené na Matrix3D a 3D pohledy operují ve stejném souřadnicovém prostoru, který popisuje Point3D.

Rectangles

Rectangle(x, y, width, height) popisuje pozici a velikost a navíc poskytuje vypočtené float vlastnosti left, bottom a right spolu s x, y, width a height. Rectangle je typ stojící za PDF3DAnnotation.rect, takže ohraničení 3D anotace na stránce se čte a nastavuje pomocí stejného tvaru jako jakýkoli jiný obdélník v API.

Transformace matice: Matrix a Matrix3D

Matrix obsahuje 2D afinní transformaci jako šest komponent typu float — a, b, c, d, e, f — a poskytuje dvě metody: translate(x, y) pro aplikaci translace přímo, a multiply(other) pro složení s jiným Matrix, vracející výsledný Matrix.

Matrix3D je 3D protějšek: 3×3 blok rotace/škálování (m11 až m33) plus překladová komponenta dx, dy, dz, vytvořený bez argumentů (Matrix3D()) a naplněný nastavením jeho vlastností. PDF3DView.ctm má typ Matrix3D | None — aktuální transformační matice pro uložený 3D pohled.

Tipy a osvědčené postupy

  • Vytvořte Rectangle, Point a Point3D pomocí pozičních argumentů v dokumentovaném pořadí (x, y[, z] / x, y, width, height) — tyto typy přijímají obyčejné floaty, nikoli pouze argumenty pojmenované klíčovým slovem.
  • Použijte Matrix.multiply() ke skládání transformací místo ručního kombinování šesti komponent a–f.
  • Když je typ vlastnosti volitelný (například PDF3DAnnotation.background_color: Color | None nebo PDF3DView.ctm: Matrix3D | None), zkontrolujte None před čtením vnořených vlastností.
  • Použijte GradientAxialShading jen tehdy, když potřebujete dvoubarevný lineární gradient jako prostor vzorových barev; pro plochou, jednobarevnou oblast použijte Color přímo.
  • Vlastnosti left, bottom a right objektu Rectangle jsou odvozeny z x, y a width/height — považujte je za pohodlný pohled na stejný obdélník, nikoli za nezávislý stav.

Běžné problémy

ProblémPříčinaOprava
Souřadnice obdélníku nebo bodu se jeví jako prohozené nebo nesprávně škálovanéPoziční argumenty předány v nesprávném pořadí do Rectangle(x, y, width, height) nebo Point3D(x, y, z)Zkontrolujte pořadí argumentů podle signatury konstruktoru – u těchto typů není vynucováno používání pouze klíčových argumentů
AttributeError při čtení vlastnosti barvy nebo maticeVlastnost přistupována na hodnotě None z volitelného pole (např. background_color, ctm)Zkontrolujte, že hodnota není None, než přistoupíte k vnořeným vlastnostem
Gradient se vykresluje jako jedna plochá barvaGradientAxialShading.start a end Point hodnoty jsou identické nebo si velmi blížíUjistěte se, že start a end označují dva vizuálně odlišné body podél zamýšlené osy gradientu

FAQ

Potřebuji v běžném použití importovat Point, Rectangle nebo Matrix přímo?

Obvykle ne — nejčastěji na ně narazíte jako na typ vlastnosti (například PDF3DAnnotation.rect nebo PDF3DView.ctm) spíše než že byste je vytvářeli od nuly, ačkoliv nic nebrání jejich přímému vytvoření, pokud potřebujete samostatnou hodnotu.

Jaký je rozdíl mezi Color a ColorPrimitive?

Color obsahuje kanálová data ve stylu RGB a volitelně pattern_color_space pro gradientní výplně. ColorPrimitive je mnohem menší typ, který vystavuje pouze hodnotu transparency.

Jak spojím dva transformy pomocí Matrix?

Zavolejte matrix_a.multiply(matrix_b), který vrací složený Matrix. Použijte translate(x, y) pro jednoduchý posun bez nutnosti vytvářet úplnou maticovou násobení.

Používá se Matrix3D někde mimo 3D anotace?

V tomto klastru se Matrix3D objevuje jako typ PDF3DView.ctm — aktuální transformační matice spojená s uloženým 3D pohledem.

API Reference Shrnutí

Třída/metodaPopis:
Point2D souřadnice (x, y float vlastnosti)
Point3D3D souřadnice (x, y, z float vlastnosti)
RectanglePozice a velikost (x, y, width, height, plus vypočítané left, bottom, right)
Matrix2D afinní transformace (a–f komponenty); translate / multiply metody
Matrix3D3D transformační matice (m11–m33 blok rotace/škálování, dx/dy/dz translace)
ColorHodnota barvy s volitelným pattern_color_space gradientním výplní
ColorPrimitiveMinimální barevná primitiva vystavující transparency
GradientAxialShadingAxiální (lineární) gradient mezi dvěma hodnotami Color podél dvou koncových bodů Point

Viz také:

 Čeština