Primitives

Primitives

Panduan ini mencakup tipe nilai kecil yang secara praktik tidak dapat diubah yang membawa data geometri dan warna melalui sisa API: titik 2D dan 3D, persegi panjang, matriks transformasi, dan nilai warna. Anda biasanya tidak akan mengimpor tipe ini secara langsung dengan nama dalam alur kerja sederhana — mereka muncul sebagai tipe properti pada objek tingkat-tinggi seperti anotasi, penempatan gambar, dan tampilan 3D — tetapi mengetahui bentuknya membuat properti objek tersebut mudah dibaca dan dibangun.

Titik: Point dan Point3D

Point adalah koordinat 2D sederhana dengan properti float x dan y. Point3D adalah padanannya dalam 3D, dibangun sebagai Point3D(x, y, z) dan menampilkan properti float x, y, dan z. Point adalah tipe yang digunakan untuk GradientAxialShading.start / end; transformasi berbasis Matrix3D dan tampilan 3D beroperasi dalam ruang koordinat yang sama yang dijelaskan oleh Point3D.

Rectangles

Rectangle(x, y, width, height) menggambarkan posisi dan ukuran, serta menampilkan properti float terhitung left, bottom, dan right bersama dengan x, y, width, dan height. Rectangle adalah tipe di balik PDF3DAnnotation.rect, sehingga batas pada halaman untuk anotasi 3D dibaca dan diatur melalui bentuk yang sama seperti persegi panjang lainnya dalam API.

Matriks Transformasi: Matrix dan Matrix3D

Matrix menyimpan transformasi afine 2D sebagai enam komponen float — a, b, c, d, e, f — dan menyediakan dua metode: translate(x, y) untuk menerapkan translasi secara in-place, dan multiply(other) untuk menggabungkannya dengan Matrix lain, mengembalikan Matrix yang dihasilkan.

Matrix3D adalah padanan 3D: blok rotasi/skala 3x3 (m11 sampai m33) ditambah komponen translasi dx, dy, dz, dibangun tanpa argumen (Matrix3D()) dan diisi dengan menyetel propertinya. PDF3DView.ctm bertipe Matrix3D | None — matriks transformasi saat ini untuk tampilan 3D yang disimpan.

Tips dan Praktik Terbaik

• Bangun Rectangle, Point, dan Point3D dengan argumen posisional dalam urutan yang didokumentasikan (x, y[, z] / x, y, width, height) — tipe-tipe ini menerima float biasa, bukan argumen hanya kata kunci.
• Gunakan Matrix.multiply() untuk menggabungkan transformasi daripada menggabungkan secara manual enam komponen a–f dengan tangan.
• Ketika tipe properti bersifat opsional (misalnya PDF3DAnnotation.background_color: Color | None atau PDF3DView.ctm: Matrix3D | None), periksa None sebelum membaca properti bersarang di dalamnya.
• Gunakan GradientAxialShading hanya ketika Anda membutuhkan gradien linier dua warna sebagai ruang warna pola; untuk warna tunggal datar gunakan Color secara langsung.
• Properti left, bottom, dan right milik Rectangle diturunkan dari x, y, dan width/height — anggap mereka sebagai tampilan nyaman dari persegi panjang yang sama, bukan status yang independen.

Masalah Umum

FAQ

Apakah saya perlu mengimpor Point, Rectangle, atau Matrix secara langsung dalam penggunaan normal?

Biasanya tidak — Anda paling sering akan menemui ini sebagai tipe properti (seperti PDF3DAnnotation.rect atau PDF3DView.ctm) daripada membuatnya dari awal, meskipun tidak ada yang menghalangi pembuatan langsung ketika Anda memerlukan nilai mandiri.

Apa perbedaan antara Color dan ColorPrimitive?

Color membawa data saluran bergaya RGB ditambah pattern_color_space opsional untuk isian gradien. ColorPrimitive adalah tipe yang jauh lebih kecil yang hanya menampilkan nilai transparency.

Bagaimana cara menggabungkan dua transformasi dengan Matrix?

Panggil matrix_a.multiply(matrix_b), yang mengembalikan Matrix yang telah digabungkan. Gunakan translate(x, y) untuk translasi sederhana tanpa membangun perkalian matriks penuh.

Apakah Matrix3D digunakan di mana pun di luar anotasi 3D?

Dalam klaster ini, Matrix3D muncul sebagai tipe PDF3DView.ctm — matriks transformasi saat ini yang terkait dengan tampilan 3D yang disimpan.

API Reference Ringkasan

Lihat Juga

• Aspose.PDF for Python — Enterprise Documentation