Primitives
Primitives
מדריך זה מכסה את סוגי הערכים הקטנים, שאינם משתנים בפועל, שנושאים נתוני גאומטריה וצבע דרך שאר ה-API: נקודות דו-ממדיות ותלת-ממדיות, ריבועים, מטריצות שינוי, וערכי צבע. בדרך כלל לא תייבאו אותם ישירות לפי שם בעבודות פשוטות — הם מופיעים כסוגי תכונה באובייקטים ברמה גבוהה יותר כגון אנוטציות, מיקומי תמונות, ותצוגות תלת-ממד — אך הכרת המבנה שלהם עושה את קריאת ותצורת התכונות של האובייקטים האלה לקלה.
נקודות: Point ו-Point3D
Point הוא קואורדינטה דו-ממדית פשוטה עם תכונות ציפה x ו-y. Point3D הוא המקבילה התלת-ממדית שלו, נבנה כ-Point3D(x, y, z) ומחשוף את תכונות הציפה x, y ו-z. Point הוא הסוג המשמש עבור GradientAxialShading.start / end; טרנספורמים מבוססי Matrix3D ותצוגות תלת-ממד פועלות באותו מרחב קואורדינטות שה-Point3D מתאר.
Rectangles
Rectangle(x, y, width, height) מתאר מיקום וגודל, ובנוסף חושף תכונות ציפה מחושבות left, bottom ו-right לצד x, y, width ו-height. Rectangle הוא הסוג שמאחורי PDF3DAnnotation.rect, ולכן גבולות העמוד של אנוטציית תלת-ממד נקראים ונקבעים באמצעות אותה צורה כמו כל מלבן אחר ב-API.
מטריצות שינוי: Matrix ו-Matrix3D
Matrix מחזיק טרנספורם אפיני דו-ממדי כשישה רכיבי float — a, b, c, d, e, f — ומספק שני מתודות: translate(x, y) ליישום תרגום במקום, ו-multiply(other) להרכבה עם Matrix אחר, ומחזיר את ה-Matrix שנוצר.
Matrix3D הוא המקביל בתלת-מימד: בלוק סיבוב/הרחבה בגודל 3x3 (m11 עד m33) בתוספת רכיב תרגום dx, dy, dz, נבנה ללא ארגומנטים (Matrix3D()) ומתמלא על ידי הגדרת המאפיינים שלו. PDF3DView.ctm מוגדר כ-Matrix3D | None — מטריצת ה-טרנספורם הנוכחית לתצוגת 3D שמורה.
טיפים ושיטות עבודה מומלצות
- בנה את
Rectangle,Pointו-Point3Dעם ארגומנטים מיקומיים לפי הסדר המתועד (x, y[, z]/x, y, width, height) — סוגים אלו מקבלים ערכי float רגילים, ולא ארגומנטים של מילות מפתח בלבד. - השתמש ב-
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) | בדוק שוב את סדר הארגומנטים מול חתימת הבונה — לסוגים אלה אין אכיפה של ארגומנטים רק במילות מפתח |
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 משמשה במקום כלשהו מחוץ להערות תלת-ממד?
בתוך האשכול הזה, Matrix3D מופיעה כסוג של PDF3DView.ctm — מטריצת ההמרה הנוכחית המשוייכת לתצוגה תלת-ממדית שמורה.
API Reference סיכום
| מחלקה/מתודה | תיאור |
|---|---|
Point | קואורדינטת דו-ממד (x, y תכונות float) |
Point3D | קואורדינטת 3D (x, y, z תכונות float) |
Rectangle | מיקום וגודל (x, y, width, height, בתוספת left, bottom, right מחושבים) |
Matrix | טרנספורמציה אפינית דו-ממדית (a–f רכיבים); שיטות translate / multiply |
Matrix3D | מטריצת טרנספורם תלת-ממדית (m11–m33 בלוק סיבוב/קנה מידה, תרגום dx/dy/dz) |
Color | ערך צבע עם מילוי גרדיאנט pattern_color_space אופציונלי |
ColorPrimitive | פרימיטיב צבע מינימלי שמחשף transparency |
GradientAxialShading | גרדיאנט צירי (קווי) בין שני ערכי Color לאורך שני קצות Point |
