Primitives

Primitives

Ten przewodnik obejmuje małe, w praktyce niezmiennicze typy wartości, które przenoszą dane geometryczne i kolorystyczne przez resztę API: punkty 2D i 3D, prostokąty, macierze transformacji oraz wartości kolorów. Zazwyczaj nie importujesz ich bezpośrednio po nazwie w prostych przepływach pracy — pojawiają się jako typy właściwości w obiektach wyższego poziomu, takich jak adnotacje, rozmieszczenia obrazów i widoki 3D — ale znajomość ich struktury ułatwia odczyt i konstruowanie właściwości tych obiektów.

Punkty: Point i Point3D

Point jest prostą współrzędną 2D z właściwościami zmiennoprzecinkowymi x i y. Point3D jest jej odpowiednikiem 3D, tworzonym jako Point3D(x, y, z) i udostępniającym właściwości zmiennoprzecinkowe x, y oraz z. Point jest typem używanym dla GradientAxialShading.start / end; transformacje oparte na Matrix3D i widoki 3D działają w tej samej przestrzeni współrzędnych, którą opisuje Point3D.

Rectangles

Rectangle(x, y, width, height) opisuje pozycję i rozmiar, a dodatkowo udostępnia wyliczone właściwości zmiennoprzecinkowe left, bottom i right oraz x, y, width i height. Rectangle jest typem stojącym za PDF3DAnnotation.rect, więc granice na stronie adnotacji 3D są odczytywane i ustawiane przy użyciu tego samego kształtu co każdy inny prostokąt w API.

Macierze transformacji: Matrix i Matrix3D

Matrix przechowuje dwuwymiarową transformację afiniczną jako sześć komponentów typu float — a, b, c, d, e, f — i udostępnia dwie metody: translate(x, y) do zastosowania translacji w miejscu oraz multiply(other) do połączenia jej z innym Matrix, zwracając wynikowy Matrix.

Matrix3D jest odpowiednikiem 3D: blok rotacji/skalowania 3x3 (m11 do m33) plus komponent translacji dx, dy, dz, tworzony bez argumentów (Matrix3D()) i wypełniany poprzez ustawianie jego właściwości. PDF3DView.ctm ma typ Matrix3D | None — aktualną macierz transformacji dla zapisanego widoku 3D.

Wskazówki i najlepsze praktyki

• Utwórz Rectangle, Point i Point3D przy użyciu argumentów pozycyjnych w udokumentowanej kolejności (x, y[, z] / x, y, width, height) — te typy przyjmują zwykłe liczby zmiennoprzecinkowe, a nie wyłącznie argumenty nazwane.
• Użyj Matrix.multiply() do składania transformacji zamiast ręcznego łączenia sześciu komponentów a–f.
• Gdy typ właściwości jest opcjonalny (na przykład PDF3DAnnotation.background_color: Color | None lub PDF3DView.ctm: Matrix3D | None), sprawdź None przed odczytaniem zagnieżdżonych właściwości.
• Używaj GradientAxialShading tylko wtedy, gdy potrzebujesz dwukolorowego gradientu liniowego jako przestrzeni kolorów wzoru; w przypadku płaskiego, jednolitego koloru użyj bezpośrednio Color.
• Właściwości left, bottom i right obiektu Rectangle są pochodne od x, y oraz width/height — traktuj je jako wygodny widok tego samego prostokąta, a nie jako niezależny stan.

Typowe problemy

FAQ

Czy muszę importować Point, Rectangle lub Matrix bezpośrednio w normalnym użyciu?

Zazwyczaj nie — najczęściej napotkasz je jako typ właściwości (np. PDF3DAnnotation.rect lub PDF3DView.ctm), a nie tworząc je od podstaw, choć nic nie stoi na przeszkodzie, aby tworzyć je bezpośrednio, gdy potrzebujesz odrębnej wartości.

Jaka jest różnica między Color a ColorPrimitive?

Color zawiera dane kanałów w stylu RGB oraz opcjonalny pattern_color_space do wypełnień gradientowych. ColorPrimitive jest znacznie mniejszym typem, który udostępnia tylko wartość transparency.

Jak połączyć dwa przekształcenia przy użyciu Matrix?

Wywołaj matrix_a.multiply(matrix_b), który zwraca złożony Matrix. Użyj translate(x, y) do prostego przemieszczenia bez budowania pełnego mnożenia macierzy.

Czy Matrix3D jest używany gdziekolwiek poza adnotacjami 3D?

W tym klastrze, Matrix3D pojawia się jako typ PDF3DView.ctm — bieżąca macierz przekształcenia powiązana z zapisaną widokiem 3D.

Podsumowanie API Reference

Zobacz także

• Aspose.PDF for Python — Enterprise Documentation