باختصار
- يعيد Sketchup.active_model كائن Model الذي يُستخدم في عمليات API على النموذج المفتوح.
- يعيد Model.entities سياق الرسم الجذري، بينما يعيد Model.active_entities محتوى المجموعة أو المكوّن المفتوح.
- استخدام Selection#each للتكرار على عناصر التحديد أكثر كفاءة من استدعائها واحدًا تلو الآخر باستخدام الفهرس.
- قد تشترك نُسخ المكوّنات في التعريف نفسه؛ ويمكن استخدام make_unique لجعل نسخة واحدة مختلفة فقط.
يوفّر SketchUp Ruby API نقطة انطلاق لفحص عناصر الرسم في نموذج SketchUp المفتوح وتغييرها. وتشرح الفئات Model وEntities وSelection وComponentInstance في وثائق API الرسمية الأساليب الأساسية للعمل مع النموذج والهندسة والتحديد والمكوّنات. يركّز هذا الدليل على إعداد خطوات أتمتة صغيرة يسهل التحقق منها باستخدام الأساليب الموضحة في الوثائق. وتُذكر SketchUp 6.0 بوصفها الإصدار الأساسي للفئات، في حين أُضيفت بعض الأساليب في إصدارات أحدث؛ لذا ينبغي التحقق أيضًا من ملاحظات الإصدار الخاصة بالأسلوب المستخدم.
1. ابدأ بالنموذج النشط
عند العمل باستخدام API، احصل أولًا على كائن النموذج المفتوح. تعيد Sketchup.active_model النموذج الذي يعمل عليه المستخدم في الوقت الحالي. ومن خلال كائن Model، يمكن الوصول إلى عناصر الرسم والمواد وتعريفات المكوّنات والتحديد. ويتيح هذا النهج الحصول على مراجع للمجموعات المطلوبة في بداية العمل، بدلًا من البحث عن النموذج مرارًا في كل عملية.
model = Sketchup.active_model
entities = model.entities
materials = model.materials
definitions = model.definitions
selection = model.selectionمن المهم هنا التمييز بين model.entities وmodel.active_entities. تحتوي الأولى على عناصر المستوى الجذري للنموذج. إذا فتح المستخدم مجموعة أو مكوّنًا لتحريره، تعيد active_entities عناصر السياق الجاري العمل عليه؛ وإذا لم يكن هناك سياق تحرير مفتوح، فستعيد النتيجة نفسها التي تعيدها entities. لذلك، إذا كان المطلوب هو التعامل مع المحتوى الذي يحرره المستخدم حاليًا، لا المستوى الأعلى من النموذج، فينبغي اختيار المجموعة المناسبة.
2. افحص التحديد بكفاءة وأمان
يمثّل model.selection عناصر الرسم المحددة حاليًا. ويُعد التكرار باستخدام each للوصول إلى كل عنصر في التحديد أكثر كفاءة من استدعاء الفهارس بالتتابع. كما ينبغي عدم افتراض أن ترتيب التحديد يعكس ترتيب اختيار المستخدم للعناصر: فالوثائق تنص بوضوح على أن ترتيب العناصر غير محدد.
selection = Sketchup.active_model.selection
puts "Seçili öğe sayısı: #{selection.length}"
selection.each do |element|
puts element.typename
endإذا كانت العملية تتعلق بعنصر واحد فقط، فيمكن استخدام first؛ وتعيد هذه الطريقة nil إذا كان التحديد فارغًا. تُستخدم empty? للتحقق مما إذا كان هناك تحديد، بينما تتحقق single_object? مما إذا كان بالإمكان اعتبار التحديد كائنًا واحدًا. ويمكن استخدام include? للتحقق مما إذا كان عنصر ما محددًا.
قد يؤدي حذف عناصر من المجموعة نفسها أثناء التكرار على التحديد إلى تغيير حجم المجموعة وفهارسها، ما قد يتسبب في تخطي بعض العناصر. والنهج الآمن الذي توصي به الوثائق هو نسخ العناصر المراد حذفها إلى مصفوفة أولًا، ثم إجراء العملية على هذه النسخة. كذلك، لا يُعد الوصول باستخدام الفهرس، مثل selection[0]، خيارًا فعالًا لفحص كل عنصر. ويمكن استخدام الأسلوبين remove وclear لإزالة عنصر من التحديد أو إفراغ مجموعة التحديد.
3. أنشئ الهندسة في سياق الرسم الصحيح
تُضاف العناصر الجديدة، مثل الخطوط أو الأوجه، إلى مجموعة Entities المختارة. فمثلًا، تنشئ add_line حافة بين نقطتين، وتضيف add_face وجهًا، بينما تنشئ add_group مجموعة جديدة. ينبغي استخدام model.entities للعمل على المستوى الجذري، وmodel.active_entities للعمل ضمن سياق مجموعة أو مكوّن مفتوح. وبهذا تُضاف الهندسة الناتجة إلى القسم المقصود من النموذج.
إذا كانت العملية تتألف من عدة تغييرات في النموذج، تساعد آلية العمليات في SketchUp على تسجيل التغييرات كعملية واحدة قابلة للتراجع. تبدأ start_operation عملية جديدة، وتُكملها commit_operation؛ وفي حال حدوث خطأ، يمكن لـabort_operation إلغاء العملية التي بدأت. استخدم هذه الأساليب لإدارة التغييرات الصغيرة المستقلة ضمن سير عمل أتمتة واحد ومتسق.
model = Sketchup.active_model
model.start_operation("Çizgi ekle")
begin
model.active_entities.add_line([0, 0, 0], [500, 500, 0])
model.commit_operation
rescue
model.abort_operation
raise
endتشير الوثائق إلى أن abort_operation يُستدعى عادةً في قسم معالجة الأخطاء. لكنها تحذّر من استخدام هذه الطريقة مع العمليات الشفافة (transparent): إذ قد يؤدي إلغاء مثل هذه العملية إلى إلغاء العملية السابقة المرتبطة بها أيضًا. لذا، إذا كانت الأتمتة تعمل باستخدام عمليات شفافة، فينبغي معالجة الأخطاء على نحو منفصل.
إذا كان إنشاء عدد كبير من عناصر الهندسة مطلوبًا، فيمكن أيضًا النظر في Entities#build. وتعرّف وثيقة API هذه الطريقة بأنها وسيلة لإنشاء EntitiesBuilder المصمم لبناء الهندسة على دفعات مع مراعاة الأداء. لكن لا ينبغي استنتاج تحسن محدد في السرعة أو ملاءمة الطريقة لكل مهمة بما يتجاوز ما توضحه الوثائق.
4. افصل نُسخ المكوّنات عن تعريفها
يشير ComponentInstance إلى تعريف المكوّن وإلى التحويل الذي يحدد موضعه داخل النموذج. ويتيح هذا الهيكل استخدام التعريف نفسه في النموذج على هيئة عدة نُسخ. فمثلًا، يمكن الحصول على تعريف نسخة باستخدام definition، أو فحص تحويل موضعها باستخدام transformation، أو ربطها بتعريف آخر باستخدام definition=.
يمكن استخدام make_unique عندما يلزم تحرير نسخة واحدة فقط بصورة مستقلة عن النسخ الأخرى: إذ تنشئ هذه الطريقة تعريف مكوّن لا تستخدمه أي نسخة أخرى، خاصًا بالنسخة المعنية. ينبغي تحديد ما إذا كان التعديل سيُطبّق على جميع النسخ المشتركة أم على النسخة المحددة فقط مسبقًا. وإلا فقد تختلف نتيجة النموذج عن نطاق التغيير المقصود. وترد أيضًا في الوثائق الطريقة explode التي تحوّل المكوّن إلى عناصر رسم منفصلة؛ لكن لا ينبغي استخدامها في مسارات العمل التي تتطلب بقاءه كنسخة مكوّن.
الاستخدام في سير عمل العمارة والتصور
تشكل هذه الأساليب أساسًا للمعماريين ومصممي الديكور الداخلي ومطوري إضافات SketchUp الراغبين في أتمتة فحوصات النماذج المتكررة أو التعديلات الهندسية. فمثلًا، يمكن فحص العناصر في سياق التحرير النشط، أو تقييم الكائنات المحددة دفعة واحدة، أو إنشاء هندسة متكررة ضمن عملية واحدة. وتتوقف فائدة هذا النهج على تحديد القسم الذي تعمل فيه الأتمتة من النموذج، والنسخ التي سيؤثر فيها تغيير المكوّن، بوضوح.
لا تحدد الوثائق متطلبات خاصة للأجهزة أو شروط ترخيص لأساليب API هذه؛ لذا لا ينبغي افتراض وجود متطلبات في هذه الجوانب. وقبل التنفيذ، ينبغي التحقق من ملاحظات الأساليب الخاصة بإصدار SketchUp المستخدم، ولا سيما الوظائف التي تحمل وسم إصدار أحدث. وإذا كان الأمر يتعلق بإنشاء هندسة على دفعات في نماذج كبيرة، فينبغي عند تقييم Entities#build التخطيط أيضًا لكيفية إدارة سير العمل الحالي باستخدام عمليات قابلة للتراجع.
أخطاء شائعة
استخدام
model.entitiesفي جميع الحالات: عند تحرير مجموعة أو مكوّن مفتوح، قد يكونactive_entitiesهو السياق الصحيح.افتراض أن ترتيب التحديد هو ترتيب نقر المستخدم: توضح وثائق API أن هذا الترتيب غير مضمون.
حذف عناصر من المجموعة نفسها أثناء التكرار باستخدام
each: يُجنّب أخذ نسخة أولًا باستخدامto_aخطر تخطي العناصر.تجاهل مشاركة التعريف عند تحرير نسخة مكوّن: إذا كان المطلوب فصل نسخة واحدة فقط، فينبغي التفكير في استخدام
make_unique.إلغاء عملية شفافة باستخدام
abort_operation: تحذّر الوثائق من أن ذلك قد يؤدي أيضًا إلى إلغاء العملية السابقة المرتبطة بها.
المصادر
3 مصادرلا نعيد نشر نصوص المصادر؛ الاقتباسات القصيرة مشار إليها، وما تبقى ملخص وتعليق من إعدادنا.
بالنسبة إلى مكاتب العمارة والتصور الصغيرة في تركيا، تكمن القيمة العملية لهذا الـAPI في إمكانية تحويل فحوصات النماذج والتعديلات المتكررة إلى سير عمل مؤتمت. ومن شأن إدارة التحديد وسياق التحرير النشط وتعريفات المكوّنات على نحو صحيح أن تقلل الخطوات اليدوية، وأن تحدّ أيضًا من مخاطر التغييرات غير المتوقعة في النموذج.
ما يحدد كلفة البدء هنا ليس اقتناء أجهزة جديدة بقدر ما هو الإلمام بـRuby API ومدى توافقه مع سير عمل الإضافات الحالي؛ فالمصادر لا تحدد متطلبات بعينها للأجهزة أو الترخيص. ومن المناسب أن تختبر المكاتب أولًا، على نموذج صغير، إمكانية التراجع عن العمليات، وكيفية مشاركة نُسخ المكوّنات للتعريفات، ومدى ملاءمة الأساليب لإصدار SketchUp الذي تستخدمه.
الأسئلة الشائعة
كيف يمكن الوصول إلى النموذج النشط في SketchUp Ruby API؟
يتيح `Sketchup.active_model` الوصول إلى النموذج المفتوح. ومن خلال كائن النموذج، يمكن الوصول إلى مجموعات مثل الهندسة والتحديد والمواد وتعريفات المكوّنات.
ما الفرق بين entities وactive_entities في SketchUp Ruby API؟
تعيد `entities` عناصر المستوى الجذري للنموذج. أما `active_entities` فتعيد عناصر سياق تحرير مجموعة أو مكوّن مفتوح؛ وإذا لم يكن هناك سياق كهذا، فستكون النتيجة مماثلة لما تعيده `entities`.
كيف يمكن فصل نسخة مكوّن في SketchUp عن النسخ الأخرى؟
تنشئ `ComponentInstance#make_unique` تعريف مكوّن لا تشاركه أي نسخة أخرى، خاصًا بتلك النسخة. وبذلك يمكن تطبيق التغييرات على النسخة التي جرى فصلها فقط.



