دليل Grasshopper Python 3: الوصول إلى البيانات وتلميحات الأنواع والمخرجات

يستند هذا الدليل إلى شرح البرمجة النصية باستخدام Python في Grasshopper ضمن وثائق مطوري Rhino، والمحدّث في 29 سبتمبر 2026. يمكن إضافة مكوّن Python 3 أو IronPython 2 Script داخل Grasshopper، كما يمكن اختيار Python 3 من قائمة اللغة في مكوّن Script العام. تركّز الخطوات التالية على إعداد مدخلات المكوّن والوصول إلى البيانات ومخرجاته على نحو صحيح قبل إنشاء الهندسة. وتشير الوثائق بوضوح إلى أن بعض الخيارات تعتمد على إصدار Rhino؛ فعلى سبيل المثال، يتوفر خيار جعل معلمة الإدخال مطلوبة بدءاً من Rhino 8.14.

1. أضف مكوّن Script وسمّه

أضف مكوّن Python 3 Script من لوحة Script ضمن علامة التبويب Maths في لوحة Grasshopper. أو أضف مكوّن Script العام واختر Python 3 من قائمة اللغة. يؤدي النقر المزدوج على المكوّن إلى فتح محرر السكربت، ويعرض شريط الحالة في المحرر إصدار لغة Python المستخدم.

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

2. أنشئ أول سكربت باستخدام المدخلات والمخرجات

يأتي مكوّن Script افتراضياً بمدخلين هما x وy، ومخرجين هما out وa. ويمكن حذف المعلمات التي لا تحتاج إليها. تظهر عناصر التحكم لإضافة المدخلات والمخرجات أو إزالتها عند تكبير العرض بما يكفي على المكوّن. كما يمكن إزالة جميع المعلمات من أحد الجانبين؛ وسيعرض المكوّن ذلك الجانب بطريقة مختلفة.

في أبسط تجربة، اجمع عددين وأسنِد الناتج إلى المخرج a:

a = x + y

في Script-Mode، يعرّف المكوّن متغيرات الإدخال قبل تشغيل السكربت، وتُنقل القيم المسندة إلى متغيرات الإخراج إلى مخارج المكوّن. في هذا المثال، ينبغي توصيل قيم متوافقة بمدخلي x وy. إذا كانت المدخلات فارغة، فقد تكون قيمها None، وسيؤدي جمع هاتين القيمتين إلى خطأ أثناء التشغيل. ولأن Python ليست لغة آمنة الأنواع، فقد تتسبب العمليات غير المتوافقة في مشكلات عند تشغيل السكربت.

3. اختر نوع الإدخال وطريقة الوصول إلى البيانات

يتيح تحديد Type Hint بالنقر بزر الفأرة الأيمن على معلمة الإدخال تحويل البيانات الواردة إلى المكوّن قبل تشغيل السكربت. وفي المثال الوارد في الوثائق، تُحوّل قيمتا Line إلى قيم عددية باستخدام تلميح النوع float، ثم يجمع السكربت بينهما. تتوفر خيارات Type Hint لكل من معلمات الإدخال والإخراج. وينبغي التحقق من البيانات الموصولة للتأكد من أن نتيجة التحويل هي المتوقعة.

يحدد خيار Parameter Access في قائمة المعلمة نطاق البيانات التي سيتعامل معها السكربت:

مع الوصول Item، تظهر القيمة العددية في Python كقيمة واحدة؛ أما مع List فتظهر قيم الفرع على هيئة قائمة. وفي وضع Tree، يمكن الوصول إلى شجرة بيانات Grasshopper. كما قد يساعد تلميح النوع على تحديد نوع العناصر ضمن بنية DataTree عامة. وقبل اختيار طريقة الوصول، حدّد ما إذا كان السكربت سيعالج عنصراً واحداً أم قائمة أم الشجرة بأكملها.

4. أدر المخرجات ومتطلبات الإدخال

تلتقط المعلمة out النص الناتج عن استدعاءات print() في السكربت. وفي السلوك الافتراضي، يتحول كل سطر إلى عنصر إخراج منفصل. وعند تفعيل خيار Avoid Grafting Output Lines، تُمرر الأسطر المطبوعة كعنصر واحد. إذا لم يكتب السكربت أي شيء إلى وحدة التحكم، فيمكن تعطيل معلمة out من خلال خيار Standard Output/Error Parameter في قائمة السياق للمكوّن.

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

تكون مدخلات السكربت اختيارية في البداية. وإذا كان لا بد من توفير بيانات لأحد المدخلات، فيمكن استخدام خيار Required في قائمة النقر بزر الفأرة الأيمن لمعلمة الإدخال. وتذكر الوثائق الرسمية أن هذا الخيار متاح بدءاً من Rhino 8.14. ومن المفيد تحديد المدخلات المطلوبة، ولا سيما قبل نشر السكربت، لتقليل احتمال تشغيله ببيانات ناقصة.

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

تساعد هذه الإعدادات المعماريين ومصممي الديكور الداخلي وفرق التصور على تحويل خطوات النمذجة المتكررة إلى تعريف Grasshopper أوضح. فعلى سبيل المثال، يسهّل توضيح البيانات التي يتوقعها السكربت عبر أسماء المعلمات، إلى جانب تحديد نوع الإدخال، تسليم التعريف بين أعضاء الفريق. كما يحدد اختيار Item أو List أو Tree ما إذا كانت العملية ستُطبّق على عناصر منفردة أم على مجموعة بيانات.

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

أخطاء شائعة

• إغفال المدخلات الفارغة وإجراء عمليات على قيم None: ينبغي التحقق من أن المدخلات موصولة وأن أنواعها مطابقة لما هو متوقع.

• عدم اختيار طريقة الوصول إلى المعلمات بما يتناسب مع احتياجات السكربت: يوفر Item وList وTree بنى بيانات مختلفة.

• ترك معلمة out غير المستخدمة مفعّلة: يمكن تعطيلها إذا لم تكن مخرجات print() مطلوبة.

• استخدام أسماء غير واضحة للمعلمات: فهذا يجعل الغرض من المدخلات والمخرجات ملتبساً، ولا سيما في التعريفات المشتركة.