Primitives
Primitives
คำแนะนำนี้ครอบคลุมประเภทค่าขนาดเล็กที่โดยปฏิบัติแล้วเป็นค่าคงที่ซึ่งบรรจุข้อมูลเรขาคณิตและสีผ่านส่วนที่เหลือของ API: จุด 2 มิติและ 3 มิติ, สี่เหลี่ยมผืนผ้า, เมทริกซ์การแปลง, และค่สี คุณมักจะไม่ได้นำเข้าประเภทเหล่านี้โดยตรงตามชื่อในกระบวนการทำงานแบบง่าย — พวกมันปรากฏเป็นประเภทของคุณสมบัติบนวัตถุระดับสูงเช่น annotation, การวางภาพ, และมุมมอง 3 มิติ — แต่การเข้าใจรูปร่างของพวกมันทำให้การอ่านและสร้างคุณสมบัติวัตถุเหล่านั้นง่ายขึ้น.
จุด: Point และ Point3D
Point คือพิกัด 2D ธรรมดาที่มีคุณสมบัติ float x และ y. Point3D เป็นรุ่น 3D ของมัน, สร้างขึ้นเป็น Point3D(x, y, z) และเปิดเผยคุณสมบัติ float x, y, และ z. Point คือประเภทที่ใช้สำหรับ GradientAxialShading.start / end; การแปลงที่อิง Matrix3D และมุมมอง 3D ทำงานในพื้นที่พิกัดเดียวกันที่ Point3D อธิบาย.
Rectangles
Rectangle(x, y, width, height) อธิบายตำแหน่งและขนาด, และยังเปิดเผยคุณสมบัติ float ที่คำนวณได้ left, bottom, และ right ร่วมกับ x, y, width, และ height. Rectangle คือประเภทที่อยู่เบื้องหลัง PDF3DAnnotation.rect, ดังนั้นขอบเขตบนหน้า ของ annotation 3D จะถูกอ่านและตั้งค่าโดยใช้รูปแบบเดียวกับสี่เหลี่ยมอื่นใดใน API.
เมทริกซ์การแปลง: Matrix และ Matrix3D
Matrix เก็บการแปลงเชิง Affine 2 มิติเป็นหกส่วนประกอบแบบ float — a, b, c, d, e, f — และให้สองเมธอด: translate(x, y) เพื่อทำการแปลตำแหน่งในที่เดียว, และ multiply(other) เพื่อผสานกับ Matrix อีกอันหนึ่ง, ส่งกลับ Matrix ที่ได้.
Matrix3D คือเวอร์ชัน 3 มิติที่สอดคล้องกัน: บล็อกการหมุน/สเกล 3x3 (m11 ถึง m33) พร้อมส่วนประกอบการแปลตำแหน่ง dx, dy, dz, สร้างโดยไม่มีอาร์กิวเมนต์ (Matrix3D()) และเติมค่าด้วยการตั้งค่าคุณสมบัติของมัน. PDF3DView.ctm มีประเภทเป็น Matrix3D | None — เมทริกซ์การแปลงปัจจุบันสำหรับมุมมอง 3D ที่บันทึกไว้.
เคล็ดลับและแนวปฏิบัติที่ดีที่สุด
- สร้าง
Rectangle,PointและPoint3Dด้วยอาร์กิวเมนต์ตำแหน่งตามลำดับที่ระบุในเอกสาร (x, y[, z]/x, y, width, height) — ชนิดเหล่านี้รับค่า float ธรรมดา ไม่ใช่อาร์กิวเมนต์แบบ keyword-only. - ใช้
Matrix.multiply()เพื่อผสานการแปลงแทนการรวมส่วนประกอบหกส่วนa–fด้วยตนเอง. - เมื่อชนิดของคุณสมบัตินั้นเป็นทางเลือก (เช่น
PDF3DAnnotation.background_color: Color | NoneหรือPDF3DView.ctm: Matrix3D | None) ให้ตรวจสอบNoneก่อนที่จะอ่านคุณสมบัติที่ซ้อนอยู่ภายใน. - ใช้
GradientAxialShadingเท่านั้นเมื่อคุณต้องการไล่สีเชิงเส้นสองสีเป็นพื้นที่สีของแพทเทิร์น; สำหรับสีเดียวแบบแบน ให้ใช้Colorโดยตรง. - คุณสมบัติ
left,bottomและrightของRectangleได้มาจากx,yและwidth/height— ให้ถือว่าพวกมันเป็นมุมมองสะดวกของสี่เหลี่ยมเดียวกัน ไม่ใช่สถานะอิสระ.
ปัญหาทั่วไป
| ปัญหา | สาเหตุ | วิธีแก้ไข |
|---|---|---|
| พิกัดของสี่เหลี่ยมหรือจุดปรากฏสลับกันหรือมีการปรับขนาดไม่ถูกต้อง | อาร์กิวเมนต์ตำแหน่งถูกส่งในลำดับที่ผิดไปยัง Rectangle(x, y, width, height) หรือ Point3D(x, y, z) | ตรวจสอบลำดับอาร์กิวเมนต์อีกครั้งกับลายเซ็นของคอนสตรัคเตอร์ — ชนิดเหล่านี้ไม่มีการบังคับใช้ keyword-only |
AttributeError ขณะอ่านคุณสมบัติสีหรือเมทริกซ์ | คุณสมบัติถูกเข้าถึงบนค่า None จากฟิลด์ที่เป็นตัวเลือก (เช่น background_color, ctm) | ตรวจสอบว่าค่าไม่ได้เป็น None ก่อนเข้าถึงคุณสมบัติที่ซ้อนกัน |
| ไล่สีแสดงผลเป็นสีเดียวแบนราบ | GradientAxialShading.start และ end Point มีค่าเดียวกันหรือใกล้เคียงกันมาก | ตรวจสอบให้แน่ใจว่า start และ end ระบุตำแหน่งสองจุดที่มองเห็นได้แตกต่างกันตามแกนไล่สีที่ต้องการ |
FAQ
ฉันต้องนำเข้า Point, Rectangle หรือ Matrix โดยตรงในการใช้งานปกติหรือไม่?
โดยปกติไม่ใช่ — คุณมักจะพบสิ่งเหล่านี้เป็นประเภทของคุณสมบัติ (เช่น PDF3DAnnotation.rect หรือ PDF3DView.ctm) มากกว่าการสร้างจากศูนย์ แม้ว่าจะไม่มีอะไรขัดขวางการสร้างโดยตรงเมื่อคุณต้องการค่าแบบแยกอิสระ.
ความแตกต่างระหว่าง Color กับ ColorPrimitive คืออะไร?
Color มีข้อมูลช่องแบบ RGB พร้อมกับ pattern_color_space แบบเลือกสำหรับการเติมไล่สี. ColorPrimitive เป็นประเภทที่เล็กกว่ามากซึ่งเปิดเผยค่า transparency เพียงอย่างเดียว.
ฉันจะรวมการแปลงสองแบบด้วย Matrix อย่างไร?
เรียก matrix_a.multiply(matrix_b), ซึ่งจะคืนค่า Matrix ที่ประกอบกัน. ใช้ translate(x, y) สำหรับการแปลที่ง่ายโดยไม่ต้องสร้างการคูณเมทริกซ์เต็มรูปแบบ.
Matrix3D ถูกใช้ที่ไหนบ้างนอกเหนือจากการทำ annotation 3D?
ภายในคลัสเตอร์นี้, Matrix3D ปรากฏเป็นประเภทของ PDF3DView.ctm — เมทริกซ์การแปลงปัจจุบันที่เชื่อมโยงกับมุมมอง 3D ที่บันทึกไว้.
API Reference สรุป
| คลาส/เมธอด | คำอธิบาย |
|---|---|
Point | พิกัด 2 มิติ (x, y คุณสมบัติ float) |
Point3D | พิกัด 3 มิติ (x, y, z คุณสมบัติ float) |
Rectangle | ตำแหน่งและขนาด (x, y, width, height, พร้อมค่าที่คำนวณ left, bottom, right) |
Matrix | การแปลงเชิง affine 2 มิติ (a–f ส่วนประกอบ); วิธี translate / multiply |
Matrix3D | เมทริกซ์การแปลง 3 มิติ (m11–m33 บล็อกการหมุน/สเกล, การแปล dx/dy/dz) |
Color | ค่สีพร้อมการเติมไล่ระดับ pattern_color_space แบบเลือกได้ |
ColorPrimitive | โครงสร้างสีขั้นพื้นฐานที่เปิดเผย transparency |
GradientAxialShading | ไล่ระดับเชิงแกน (เชิงเส้น) ระหว่างสองค่า Color ตามสองจุดปลาย Point |
