دليل Blender Python API: أتمتة كائنات المشهد والمشغّلات

ما الذي ستتعلمه في هذا الدليل؟

تتيح Python API في Blender تعريف بعض العمليات التي تُجرى على المشهد برمجيًا وإعادة تنفيذها. في هذا الدليل، ستتعرف على كيفية إنشاء كتلة بيانات للضوء وكائن يستخدمها، وكيفية ربط الكائن بمجموعة العرض النشطة وتحديد موقعه. سنتناول أيضًا استدعاء المشغّلات عبر bpy.ops، واستخدام poll() قبل الاستدعاء، وتقييم الحالة التي يعيدها المشغّل.

تستند الأمثلة إلى الشروحات الواردة في وثائق Blender الرسمية. والهدف ليس تقديم نظام جاهز للأتمتة المعمارية، بل شرح المكونات الأساسية للنصوص البرمجية التي تنفذ عمليات على المشهد. قبل استخدام مقاطع الشيفرة في ملفاتك، تحقّق مما ستغيّره وجرّبها في مشهد اختباري صغير.

المتطلبات وملاحظات الإصدار

تتطلب هذه الأمثلة العمل باستخدام Python API في Blender. ولأن الوثائق لا تحدد رقمًا لإصدار معين من Blender، فلا يمكن ذكر رقم دقيق هنا لضمان التوافق. عند تشغيل الشيفرة، راجع وثائق API الخاصة بتثبيت Blender الذي تستخدمه. ولا توضّح المصادر وجود متطلبات لحساب أو رسوم أو مواصفات خاصة للأجهزة.

تستخدم الشيفرات الوحدة bpy. وتستند أسماء API والمعاملات الظاهرة في الأمثلة إلى الاستخدامات الواردة في وثائق Blender الرسمية. وقد تعتمد المشغّلات خصوصًا على السياق الذي تُشغّل فيه، لا على معاملاتها وحدها. لذلك، تحقّق من الكائن النشط في المشهد وشروط العملية المعنية قبل استدعاء أي مشغّل.

خطوة بخطوة: إضافة كائن ضوء إلى المشهد

يوضح المثال التالي تسلسل إنشاء الضوء الوارد في وثائق Blender الرسمية. تُجهّز كتلة بيانات الضوء والكائن الموجود في المشهد كلٌّ على حدة، ثم يُضاف الكائن إلى مجموعة طبقة العرض النشطة.

import bpy
view_layer = bpy.context.view_layer
# Create new light data-block.
light_data = bpy.data.lights.new(name="New Light", type='POINT')
# Create new object with our light data-block.
light_object = bpy.data.objects.new(name="New Light", object_data=light_data)
# Link light object to the active collection of current view layer,
# so it'll appear in the current scene.
view_layer.active_layer_collection.collection.objects.link(light_object)
# Place light to a specified location.
light_object.location = (5.0, 5.0, 5.0)
# And finally select it and make it active.
light_object.select_set(True)
view_layer.objects.active = light_object

في البداية، تُستخرج طبقة العرض النشطة باستخدام bpy.context.view_layer. وفي الأسطر التالية، تُنشأ كتلة بيانات لضوء من نوع POINT، ثم يُنشأ كائن يستخدم هذه البيانات. بعد ربط الكائن بالمجموعة النشطة، يُحدّد موقعه؛ وأخيرًا، يُختار ويُعيّن ككائن نشط. الإحداثيات الواردة هنا مأخوذة من المثال في الوثائق، ولا تعني أنها موضع موصى به لمساحة داخلية أو مشهد معماري بعينه.

من المفيد أثناء اتباع هذه الخطوات التمييز بين إنشاء كتلة البيانات وإضافة الكائن إلى المشهد. ربط الكائن بمجموعة هو الخطوة المستخدمة في المثال ليظهر في المشهد الحالي. أما اختيار الكائن وتعيينه ككائن نشط في نهاية الشيفرة، فيحددان الكائن الذي سترتبط به العمليات اللاحقة.

استدعاء المشغّلات والتحقق من إمكانية تشغيلها

وفقًا لوثائق Blender، تُستخدم bpy.ops لاستدعاء المشغّلات المكتوبة بـ C++ أو Python أو بصيغة ماكرو. وتُمرر خصائص المشغّل عبر الكلمات المفتاحية، أي المعاملات المسماة. على سبيل المثال، يمرر الاستدعاء التالي خاصيتين إلى المشغّل mesh.subdivide:

import bpy
bpy.ops.mesh.subdivide(number_cuts=3, smoothness=0.5)

لا يعني هذا الاستدعاء أن المشغّل سيعمل بالشروط نفسها في كل مشهد. فقد يؤدي استدعاؤه في سياق غير مناسب إلى حدوث RuntimeError. ومن الأساليب التي توصي بها الوثائق استخدام poll() للتحقق من الظروف الحالية قبل تشغيل المشغّل. ومثال تغيير الوضع هو:

import bpy
if bpy.ops.object.mode_set.poll():
    bpy.ops.object.mode_set(mode='EDIT')

عندما تكون نتيجة poll() إيجابية، يُستدعى مشغّل تغيير الوضع. ويساعد هذا الفحص على تحديد ما إذا كان بالإمكان تشغيل المشغّل في السياق الحالي، لكن لا ينبغي اعتباره ضمانًا لإزالة جميع احتمالات الخطأ. وتشير الوثائق أيضًا إلى أنه قد يحدث RuntimeError بعد انتهاء المشغّل إذا وُجدت تقارير أخطاء.

ينبغي كذلك الانتباه إلى القيمة التي تعيدها المشغّلات. فهي تعيد مجموعة حالات، بدلًا من قيمة نتيجة واحدة بالشكل المعتاد. وتذكر الوثائق أن FINISHED وCANCELLED من الحالات الشائعة. وقد تشير CANCELLED إلى إلغاء العملية وعدم إجراء أي تغييرات. لذلك، من الأفضل في النص البرمجي تقييم الحالة المعادة، بدلًا من افتراض نجاح العملية لمجرد تنفيذ سطر المشغّل.

تغيير السياق وتأثيره في سير العمل المعماري

تشرح الوثائق استخدام temp_override لتغيير السياق الذي يراه المشغّل. ويمكن بهذه الطريقة جعل المشغّل يعمل على بيانات محددة بدلًا من البيانات المحددة أو النشطة تلقائيًا. وقد تشمل عناصر السياق، على سبيل المثال، الكائن النشط أو الكائنات المحددة. وتشير المصادر إلى ضرورة تفضيل نهج يستند إلى نسخة من السياق الحالي؛ وإلا فسيكون عليك العثور على المعلومات التي يحتاج إليها المشغّل بشكل منفصل.

المهم هنا ألا تنشئ سياقًا مؤقتًا بتغيير متغير واحد فقط، ثم تغفل عن المتطلبات الأخرى. عند استخدام temp_override، راعِ معًا عناصر السياق التي قد يحتاج إليها المشغّل. فالانطلاق من السياق الحالي يوفر بداية أكثر ضبطًا من محاولة جمع البيانات المطلوبة من الصفر.

توضح أساسيات API هذه للمعماريين ومصممي الديكور الداخلي وفناني التصيير كيفية وصف العمليات المتكررة في المشهد برمجيًا. ويساعد فصل خطوات إنشاء الكائن وربطه بمجموعة وتحديد موقعه على متابعة ما يغيّره النص البرمجي. لكن المصادر لا تدّعي أن هذه الأمثلة تؤتمت سير عمل معماريًا بعينه أو تحسّن الأداء.

عند استخدام النصوص البرمجية في المكتب أو في بيئة تعليمية، تحقّق من المجموعة المستهدفة والكائن النشط، وجرّب التعديلات على بيانات المشهد أولًا في نسخة من الملف. وإذا كان الفريق يستخدم إصدارات مختلفة من Blender، فتحقّق من الشيفرة على كل تثبيت على حدة. وبما أن الوثائق لا تحدد متطلبات دقيقة للأجهزة أو الرسوم أو توافق الإصدارات، فمن الأفضل اختبارها في التثبيت المتاح بدلًا من افتراض شروط غير مذكورة.

الأخطاء الشائعة والخطوات التالية

أول خطأ هو افتراض أن استدعاءات bpy.ops تعمل بمعزل عن السياق. تحقّق من البيانات النشطة قبل استخدام المشغّل، واستخدم poll() عند ملاءمته للتحقق من إمكانية استدعائه. والخطأ الثاني هو الاعتقاد بأن الاستدعاء سينجح في كل الحالات. افحص الحالات المعادة مثل FINISHED وCANCELLED، وخذ في الحسبان أن تقارير الأخطاء قد تؤدي إلى RuntimeError.

عند إنشاء كائن، اتبع خطوات إعداد كتلة البيانات، وإنشاء الكائن، وربطه بمجموعة، وتحديد موقعه، ثم تفعيله. بهذه الطريقة، يسهل تحديد المرحلة التي حدثت فيها المشكلة عندما لا تظهر النتيجة المتوقعة. وعند الانتقال إلى مشغّل جديد، راجع معاملاته وشروحات السياق في وثائق API الرسمية، ثم تحقّق من النتائج في مشهد اختباري صغير.

في المرحلة التالية، يمكنك مراجعة أمثلة temp_override واختبار كيفية تمرير عناصر السياق. وقبل استخدام هذه الطريقة، حدّد معلومات السياق التي يحتاج إليها المشغّل. كما أن تشغيل النصوص البرمجية التي تُجري تغييرات واسعة على المشهد في نسخة من الملف قبل تجربتها في ملف المشروع الفعلي يوفّر طريقة أكثر ضبطًا لمراجعة النتائج.

المصدر والترخيص

أُعد هذا الدليل بتكييف الشروحات والأمثلة الواردة في وثائق Blender الخاصة بـ bpy.ops وbpy.types.Object إلى اللغة التركية. وكلا المصدرين مرخص بموجب CC BY-SA 4.0.