أتمتة النماذج باستخدام SketchUp Ruby API: دليل المكوّنات والهندسة

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

1. الوصول إلى محتوى النموذج من السياق المناسب

تبدأ عملية الأتمتة بالحصول على كائن النموذج المفتوح عبر Sketchup.active_model. ومن خلال كائن النموذج يمكن الوصول إلى الهندسة على المستوى الجذري وتعريفات المكوّنات والمواد ومجموعة التحديد، وغيرها. ويساعد ذلك على تحديد موضع البيانات التي ستُجرى عليها العمليات داخل النموذج.

model = Sketchup.active_model
entities = model.entities
definitions = model.definitions
materials = model.materials
selection = model.selection

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

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

2. التمييز بين تعريف المكوّن ونسخته

في مكوّنات SketchUp، التعريف والنسخة ليسا الشيء نفسه. يحدد ComponentDefinition العناصر التي يتكون منها المكوّن، بينما يمثّل ComponentInstance موضع هذا التعريف وتحويله داخل النموذج. ويمكن إنشاء أكثر من نسخة من التعريف نفسه. وتنعكس التعديلات على التعريف على النسخ التي تستخدمه.

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

instance = model.entities[0]
definition = instance.definition
puts definition.name

يفترض هذا المثال أن العنصر الأول نسخة مكوّن. وفي إضافة فعلية، ينبغي التحقق من نوع كل عنصر في المجموعة والتعامل مع احتمال عدم وجود نتيجة. ويمكن استخدام الطريقتين count_instances وcount_used_instances عبر تعريف المكوّن لإحصاء مرات استخدامه: الأولى تحسب النسخ المختلفة، والثانية تحسب إجمالي النسخ التي تستخدم هذا التعريف في النموذج.

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

3. التعامل بكفاءة مع مجموعات الهندسة

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

model.entities.each do |entity|
  puts entity.typename
end

عند الحاجة إلى الوصول عبر فهرس محدد، يمكن استخدام entities[index]؛ لكن الفهرس الصالح يتراوح من صفر إلى طول المجموعة ناقص واحد، وقد تُرجع الطريقة nil إذا تعذّر العثور على العنصر. لذا من المهم التحقق من هذه النتيجة في العمليات المرتبطة بفهرس يحدده المستخدم.

تتوفر طرائق مثل add_line لإنشاء خط، وadd_circle لإنشاء دائرة، وadd_face لإنشاء سطح. ولإنشاء عدد كبير من عناصر الهندسة مع مراعاة الأداء، تنشئ الطريقة Entities#build كائن EntitiesBuilder. وتعرّف الوثائق هذه الطريقة بأنها مخصصة لإنشاء الهندسة على دفعات، لكنها لا تحدد مقدارًا معينًا لزيادة السرعة أو متطلبات عتادية. لذلك ينبغي قياس فائدتها على الهندسة وسير عمل الإضافة في المشروع الفعلي.

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

model.start_operation("Model düzenlemesi")
begin
  # Geometri işlemlerini burada yürütün.
  model.commit_operation
rescue
  model.abort_operation
  raise
end

4. الاستخدام في سير عمل العمارة والتصور

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

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

أخطاء شائعة

• استخدام مجموعتي entities وactive_entities كما لو كانتا تعملان ضمن النطاق نفسه.

• إغفال أن التعديلات على التعريف المشترك ستنعكس على نسخ المكوّن.

• تجاهل احتمال عدم العثور على العنصر المطلوب عبر الفهرس، وأن تكون النتيجة nil.

• عدم إدارة خطوة الإغلاق المناسبة بعد بدء العملية: commit_operation عند نجاح التنفيذ، والإجراء المناسب عند حدوث خطأ.

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