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 یک تبدیل افین دو بعدی را به‌صورت شش مؤلفهٔ شناور نگهداری می‌کند — a، b، c، d، e، f — و دو متد فراهم می‌آورد: translate(x, y) برای اعمال یک ترجمه به‌صورت در-جا، و multiply(other) برای ترکیب آن با یک Matrix دیگر، که Matrix حاصل را برمی‌گرداند.
Matrix3D معادل سه‌بعدی است: یک بلوک چرخش/مقیاس ۳×۳ (m11 تا m33) به‌علاوهٔ مؤلفهٔ ترجمهٔ dx، dy، dz، که بدون آرگومان ساخته می‌شود (Matrix3D()) و با تنظیم خصوصیاتش پر می‌شود. PDF3DView.ctm به‌صورت Matrix3D | None تایپ شده است — ماتریس تبدیل فعلی برای یک نمای سه‌بعدی ذخیره‌شده.
نکات و بهترین روش‌ها
- با آرگومان‌های موقعیتی و به ترتیب مستند شده (
x, y[, z]/x, y, width, height)،Rectangle،PointوPoint3Dرا بسازید — این انواع فقط مقادیر شناور ساده می‌پذیرند، نه آرگومان‌های فقط-کلیدواژه‌ای. - به‌جای ترکیب دستی شش مؤلفهٔ
a–f، ازMatrix.multiply()برای ترکیب تبدیل‌ها استفاده کنید. - وقتی نوع یک ویژگی اختیاری است (به عنوان مثال
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 | مختصات 3بعدی (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 |
