Primitives
Primitives
هذا الدليل يغطي الأنواع القيمية الصغيرة، التي تكون غير قابلة للتغيير عمليًا، والتي تنقل بيانات الهندسة واللون عبر بقية الـ API: نقاط ثنائية وثلاثية الأبعاد، مستطيلات، مصفوفات التحويل، وقيم اللون. عادةً لن تقوم باستيراد هذه مباشرةً بالاسم في سير عمل بسيط — فهي تظهر كأنواع خصائص على الكائنات ذات المستوى الأعلى مثل التعليقات التوضيحية، مواضع الصور، والعروض الثلاثية الأبعاد — لكن معرفة شكلها تجعل خصائص تلك الكائنات سهلة القراءة والبناء.
النقاط: Point و Point3D
Point هو إحداثي ثنائي الأبعاد بسيط يحتوي على خاصيتي float x و y. Point3D هو نظيره ثلاثي الأبعاد، يُنشأ كـ Point3D(x, y, z) ويعرض خاصيات float x و y و z. Point هو النوع المستخدم لـ GradientAxialShading.start / end; التحويلات القائمة على Matrix3D والعروض الثلاثية الأبعاد تعمل في نفس مساحة الإحداثيات التي يصفها Point3D.
Rectangles
Rectangle(x, y, width, height) يصف موضعًا وحجمًا، ويُظهر أيضًا خصائص float محسوبة left و bottom و right إلى جانب x و y و width و height. Rectangle هو النوع وراء PDF3DAnnotation.rect، لذا يتم قراءة وتعيين حدود التعليق التوضيحي الثلاثي الأبعاد على الصفحة عبر نفس الشكل كما أي مستطيل آخر في الـ API.
مصفوفات التحويل: Matrix و Matrix3D
Matrix يحتوي على تحويل إقليدي ثنائي الأبعاد مكوّن من ستة مكوّنات عائمة — 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 — مصفوفة التحويل الحالية لعرض ثلاثي الأبعاد محفوظ.
نصائح وأفضل الممارسات
- قم بإنشاء
RectangleوPointوPoint3Dباستخدام معاملات موضعية وفق الترتيب الموثّق (x, y[, z]/x, y, width, height) — هذه الأنواع تقبل أعدادًا عائمة عادية، وليس معاملات كلمة-مفتاح فقط. - استخدم
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 خصائص عائمة) |
Point3D | إحداثيات ثلاثية الأبعاد (x, y, z خصائص float) |
Rectangle | الموضع والحجم (x, y, width, height, بالإضافة إلى القيم المحسوبة left, bottom, right) |
Matrix | 2D affine transform (a–f مكوّنات)؛ translate / multiply طرق |
Matrix3D | 3D transform matrix (m11–m33 كتلة دوران/تحجيم، dx/dy/dz إزاحة) |
Color | قيمة اللون مع تعبئة متدرجة اختيارية pattern_color_space |
ColorPrimitive | عنصر لوني بسيط يعرض transparency |
GradientAxialShading | تدرج محوري (خطّي) بين قيمتين Color على طول نقطتي النهاية Point |
