Primitives

Primitives

Hướng dẫn này bao phủ các kiểu giá trị nhỏ, thực tế không thay đổi, truyền dữ liệu hình học và màu sắc qua phần còn lại của API: các điểm 2D và 3D, hình chữ nhật, ma trận biến đổi và các giá trị màu. Bạn thường không nhập trực tiếp chúng theo tên trong các quy trình làm việc đơn giản — chúng xuất hiện dưới dạng kiểu thuộc tính trên các đối tượng cấp cao hơn như chú thích, vị trí hình ảnh và chế độ xem 3D — nhưng việc hiểu cấu trúc của chúng giúp các thuộc tính của các đối tượng đó dễ đọc và xây dựng.

Các điểm: Point và Point3D

Point là một tọa độ 2D đơn giản với các thuộc tính float x và y. Point3D là phiên bản 3D của nó, được tạo thành như Point3D(x, y, z) và cung cấp các thuộc tính float x, y, và z. Point là kiểu được sử dụng cho GradientAxialShading.start / end; các phép biến đổi dựa trên Matrix3D và các chế độ xem 3D hoạt động trong cùng không gian tọa độ mà Point3D mô tả.

Rectangles

Rectangle(x, y, width, height) mô tả vị trí và kích thước, và thêm nữa cung cấp các thuộc tính float tính toán được left, bottom, và right cùng với x, y, width, và height. Rectangle là kiểu phía sau PDF3DAnnotation.rect, vì vậy giới hạn trên trang của một chú thích 3D được đọc và thiết lập thông qua cùng một hình dạng như bất kỳ hình chữ nhật nào khác trong API.

Ma trận biến đổi: Matrix và Matrix3D

Matrix chứa một phép biến đổi affine 2D dưới dạng sáu thành phần float — a, b, c, d, e, f — và cung cấp hai phương thức: translate(x, y) để áp dụng một phép dịch tại chỗ, và multiply(other) để ghép nó với một Matrix khác, trả về Matrix kết quả.

Matrix3D là phiên bản 3D tương đương: một khối quay/thu phóng 3x3 (m11 đến m33) cộng với thành phần dịch dx, dy, dz, được khởi tạo không đối số (Matrix3D()) và được điền bằng cách đặt các thuộc tính của nó. PDF3DView.ctm có kiểu là Matrix3D | None — ma trận biến đổi hiện tại cho một góc nhìn 3D đã lưu.

Mẹo và Thực hành tốt nhất

• Khởi tạo Rectangle, Point và Point3D bằng các đối số vị trí theo thứ tự được ghi trong tài liệu (x, y[, z] / x, y, width, height) — các kiểu này chấp nhận các float thuần, không phải đối số chỉ có từ khóa.
• Sử dụng Matrix.multiply() để ghép các phép biến đổi thay vì tự tay kết hợp sáu thành phần a–f.
• Khi kiểu của một thuộc tính là tùy chọn (ví dụ PDF3DAnnotation.background_color: Color | None hoặc PDF3DView.ctm: Matrix3D | None), hãy kiểm tra None trước khi đọc các thuộc tính lồng nhau của nó.
• Chỉ sử dụng GradientAxialShading khi bạn cần một gradient tuyến tính hai màu làm không gian màu mẫu; đối với màu đơn phẳng, hãy dùng Color trực tiếp.
• Các thuộc tính left, bottom và right của Rectangle được suy ra từ x, y và width/height — coi chúng như một góc nhìn tiện lợi của cùng một hình chữ nhật thay vì trạng thái độc lập.

Các vấn đề thường gặp

FAQ

Tôi có cần nhập Point, Rectangle hoặc Matrix trực tiếp trong việc sử dụng bình thường không?

Thường không — bạn sẽ gặp chúng chủ yếu như kiểu của một thuộc tính (như PDF3DAnnotation.rect hoặc PDF3DView.ctm) hơn là tự tạo chúng từ đầu, mặc dù không có gì ngăn cản việc tạo chúng trực tiếp khi bạn cần một giá trị độc lập.

Sự khác nhau giữa Color và ColorPrimitive là gì?

Color chứa dữ liệu kênh kiểu RGB cộng với một pattern_color_space tùy chọn cho các gradient. ColorPrimitive là một kiểu nhỏ hơn nhiều, chỉ hiển thị một giá trị transparency.

Làm thế nào để tôi kết hợp hai phép biến đổi bằng Matrix?

Gọi matrix_a.multiply(matrix_b), nó sẽ trả về Matrix đã được kết hợp. Sử dụng translate(x, y) cho một phép dịch đơn giản mà không cần xây dựng phép nhân ma trận đầy đủ.

Matrix3D có được sử dụng ở bất kỳ nơi nào ngoài các chú thích 3D không?

Trong cụm này, Matrix3D xuất hiện như kiểu của PDF3DView.ctm — ma trận biến đổi hiện tại liên kết với một chế độ xem 3D đã lưu.

Tóm tắt API Reference

Xem thêm

• Aspose.PDF for Python — Enterprise Documentation