صايب موديلات 3D قابلة للتعديل من النص مع Procedura

شنو هي Procedura؟

Procedura هي pipeline agentic ديال النمذجة ثلاثية الأبعاد، كتحوّل prompt مكتوب لنموذج إجرائي قابل للتعديل. عوض ما تخرّج غير point cloud ولا triangle mesh، كتكتب برنامج parametric بـ OpenSCAD، والأجزاء المسماة ديالو مربوطة بواسطة mates مهيكلين حسب النوع. تقدر تشوف المصدر، تبدلو، وتعاود compile ليه.

النظام كيستعمل large language model مجمّد وما كيحتاج حتى تدريب متخصص فـ3D. التشغيل يقدر يبدا غير بالنص، ولا يعاود يبني صورة مرجعية موجودة، ولا يولّد مرجع باستعمال image model مكوّن بشكل مستقل.

Procedura تقدر حتى تعيّن مواد PBR لكل جزء باستعمال --paint، وتصدّر الأجسام المفصلية لـ OpenUSD وURDF باستعمال --motion و--motion-urdf.

أهم المزايا

• مخرجات إجرائية قابلة للتعديل: كتنتج source code ديال OpenSCAD وزيد عليه geometry مـcompiled.
• توليد جزء بجزء: كتخطط للجسم وكتبني المكوّنات المسماة ديالو بالتدريج.
• إعادة بناء من صورة مرجعية: كتقبل صورة موجودة باش تحسّن المطابقة بشكل كبير.
• تغذية راجعة ثلاثية الأبعاد: تقدر ترندر البناء الحالي قبل ما تولّد كل جزء جديد.
• نمذجة واعية بالتجميع: كتدعم خصائص الربط بحال pegs بنفس المقاس الاسمي، sockets، bolt patterns، وsnaps.
• تحسين تكراري: كتستعمل دورات ديال render، critique، patch، وgate باش تحسّن المسودة.
• المواد: مرحلة مبنية على الرؤية تقدر تعيّن اللون، metalness، وroughness لكل جزء.
• الحركة المفصلية: تقدر تخطط للحركة، وتصدّر ملفات OpenUSD وURDF، وتتحقق اختياريا من الفيزياء فـ NVIDIA Isaac Sim.
• تشغيلات قابلة للتتبع: كتحفظ prompts، الردود، tool calls، قرارات gate، renders الوسيطة، والتعديلات.
• Web Studio: كتوفّر واجهة فالمتصفح لتركيب التشغيلات وفحص artifacts ديالها.

المتطلبات والتثبيت

دير clone للمستودع وشغّل installer ديال dependencies:

git clone git@github.com:SpatiaOS/Procedura.git
cd Procedura
bash scripts/install-deps.sh

الـinstaller كيحضّر Bun 1.3 ولا أحدث، packages ديال المشروع، نسخة OpenSCAD كتدعم Manifold، Blender، وملف .env ابتدائي. افتراضيا، Bun كيتحط فـ ~/.bun، وOpenSCAD فـ ~/opt/openscad، وBlender فـ ~/opt/blender/.

السكريبت آمن تعاود تشغلو كثر من مرة. المكوّنات اللي خدامة من قبل كيبقاو بلا تغيير. استعمل modes الاختيارية ديالو باش تفحص dependencies، تتجاوز Blender، ولا تختار prefix آخر للتثبيت:

bash scripts/install-deps.sh --check
bash scripts/install-deps.sh --no-blender
PREFIX=/opt bash scripts/install-deps.sh

--check كيعطيك المتطلبات الناقصة بلا ما يثبت والو. --no-blender كيتجاوز تحميل Blender اللي الحجم ديالو تقريبا 350 MB، مع أن Blender ضروري لعدد من مزايا rendering وfeedback.

خاص OpenSCAD يدعم backend ديال Manifold. الحزم القديمة ديال بعض التوزيعات تقدر ترجع لـ CGAL وتولي أبطأ بمراتب كبيرة. Procedura كتفحص وجود --backend عند البداية، وعادة كترفض تستعمل build غير متوافق. عيّن PROCEDURA_ALLOW_CGAL_OPENSCAD=1 غير إلا كنت قابل بهاذ البطء عن قصد.

الـinstaller ما كيثبتش NVIDIA Isaac Sim. Isaac Sim مطلوب غير للتحقق من الفيزياء المرتبط بسيرورات الحركة؛ باقي Procedura خدام بلا بيه. والـinstaller حتى هو كيحافظ على أي ملف .env موجود من قبل.

ضبط Endpoint ديال LLM

Procedura ما فيها لا API keys لا backend مستضاف للاستدلال. حلّ ملف .env اللي تولّد، وزيد endpoint وkey:

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
PROCEDURA_MODEL=gpt-5.2

خاص الـendpoint يدعم POST {base}/chat/completions مع server-sent events. الاختيارات المتوافقة تقدر تشمل OpenAI API، OpenRouter، gateway ديال الشركة، ولا servers محلية مبنية على vLLM أو Ollama أو LM Studio.

اختيار النموذج هو string، يعني تقدر تستعمل أي model identifier كيتخدم من طرف الـendpoint المكوّن. الـpresets المعروفة بقوة وقواعد تحديد النموذج موثّقة فـ src/config/models.ts.

استعمل Native Gemini Transport

باش تستعمل Gemini عبر المسار الأصلي ديال GenAI، عيّن GEMINI_API_KEY وGEMINI_BASE_URL، ومن بعد زِد prefix gemini: لـ model identifier:

PROCEDURA_MODEL=gemini:gemini-3-pro-preview

هاد المسار كيتيح مزايا أصلية بحال thinkingConfig وthought parts من الدرجة الأولى.

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

Procedura ما كتعيطش لـ image API إلا إلا مكوّنتيه ولا طلبتيها بشكل صريح. باش تفعّل توليد الصور المرجعية، زِد image model:

PROCEDURA_IMAGE_MODEL=gpt-image-1

الـimage model كيعيد استعمال OPENAI_BASE_URL وOPENAI_API_KEY. بلا --image ولا image model مكوّن، التشغيلات كاتبقى غير بالنص وما كتسبّبش بصمت فمصاريف توليد الصور.

صايب أول نموذج ديالك

خاص تحدد مجلد المخرجات. عطيو بـ -o ولا --output، ومن بعد دخل prompt مكتوب:

bun run scripts/procedura.ts -o outputs/daybed \
  --prompt "a brutalist brass daybed with tapered legs"

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

باش تشوف جميع الخيارات المدعومة، شغّل:

bun run scripts/procedura.ts --help

حسّن الدقّة باستعمال صورة مرجعية

توفير صورة مرجعية هو أكبر تحسين فردي فالدقّة حدّدو المشروع. مرّر صورة عندك من قبل مع prompt وصفي:

bun run scripts/procedura.ts -o outputs/daybed \
  --image ref.png \
  --prompt "سرير نهاري من النحاس برجليه مدبّبين"

أو، ولّد الصورة المرجعية فهاد التشغيل بتسمية موديل الصور:

bun run scripts/procedura.ts -o outputs/daybed \
  --image-model gpt-image-1 \
  --prompt "سرير نهاري من النحاس برجليه مدبّبين"

إلى كانت الأوصاف طويلة وصعيب تحطّها بين علامات الاقتباس فـshell، سجّل الـprompt فملف:

bun run scripts/procedura.ts -o outputs/daybed \
  --prompt-file my_prompt.txt

شغّل pipeline كاملة ديال الجودة

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

export PROCEDURA_LLM_TIMEOUT_MS=1800000
export PROCEDURA_LLM_DEADLINE_MS=1800000

bun run scripts/procedura.ts -o outputs/gripper \
  --image gripper_ref.png \
  --3d-feedback \
  --assembly \
  --paint \
  --motion --motion-urdf \
  --max-steps 12 \
  --prompt "ملقط روبوتي متوازي بجوج صبيعات"

كل خيار عندو دور مستقل:

• --3d-feedback كيعطي للمولّد مشهد مرندَر ديال التركيب الحالي قبل ما ينشئ كل جزء. هادشي كيزيد دورة Blender وحدة لكل جزء.
• --assembly كيزيد واجهات تركيب حقيقية عوض الاعتماد غير على الهندسة المتداخلة.
• --paint كيستعمل نداء للرؤية باش يعيّن خصائص مواد PBR للأجزاء المسمّاة.
• --motion كيخطّط للحركة وكيصدّر بيانات OpenUSD.
• --motion-urdf كينشئ كذلك ملفات URDF وشبكات لكل وصلة.
• --max-steps 12 كيسمح بحد أقصى ديال 12 دورة للتحسين. كل دورة كتدير عمليات التصيير، والنقد، والترقيع، والبوابة، وكتستهلك جوج نداءات للـLLM.

النداءات الطويلة ديال التخطيط تقدر تعني باللي الـpipeline كتدير خدمة جوهرية. الـREADME كيوصي برفع المهلات عوض تقييد PROCEDURA_MAX_PARTS، حيث تحديد عدد الأجزاء كيبدّل جودة الموديل بالسرعة.

كمّل، عاود صايب المسودة، ولا تخطّى التحسين

Procedura تقدر تكمل دورة التحسين فمجلد إخراج موجود. حيد الـprompt وحدّد ميزانية جديدة للخطوات:

bun run scripts/procedura.ts -o outputs/daybed --max-steps 12

باش تحيد المسودة الموجودة وتعاود تنشئها، زِد --redo:

bun run scripts/procedura.ts -o outputs/daybed \
  --prompt "سرير نهاري من النحاس بطابع بروتالي" \
  --redo

استعمل --no-refine ملي بغيتي غير المسودة. Procedura كترقّي هاد المسودة لملفات الإخراج النهائية. فـworkflow القديم الموحّد، --one-shot كيدير نداء توليد واحد بلا مرحلة تخطيط وكيحتاج صورة مرجعية:

bun run scripts/procedura.ts -o outputs/daybed \
  --one-shot \
  --image ref.png \
  --prompt "سرير نهاري من النحاس بطابع بروتالي"

فهم مجلد الإخراج

التشغيل اللي كيكمل يقدر يحتوي على الآثار التالية:

• image.png: الصورة المرجعية الموفّرة أو المولّدة.
• plan.json: بنية الأجزاء المخطّط لها.
• _parts/NN_name/: آثار كل جزء للتوليد التدريجي.
• draft.scad وdraft.obj: المصدر الإجرائي الأولي والشبكة المجمّعة.
• final.scad وfinal.obj: الملفات النهائية المحسّنة.
• final_summary.txt: الحكم الختامي ومعلومات الربط اللي تْشحنات.
• preview_final/: تصيير Ambient Occlusion من Blender للشبكة النهائية.
• final_materials.json: اللون، والمعدنية، والخشونة لكل جزء، مولّدة بواسطة --paint.
• final_painted.scad وfinal_painted.obj وfinal_painted.mtl: أصول الموديل المصبوغ.
• preview_painted/: تصيير PBR بـCycles للموديل المصبوغ.
• motion/final_motion.usda: إخراج الحركة بصيغة OpenUSD.
• motion/urdf/ وmotion/links/: بيانات URDF وشبكات كل وصلة ملي كيكونو مطلوبين.
• _trajectory/procedura-id.jsonl: الـprompts، والأجوبة، ونداءات الأدوات، وقرارات البوابات.
• _refine_steps/step_NNN/: بيانات التصيير، والتشخيص، والتعديل، والتجميع لكل دورة تحسين.

كل ملف OBJ كيكتبو Procedura كيتطبّع لصندوق إحاطة بوحدة واحدة. تصدير STL اختياري ويمكن تفعيلو باستعمال --export-stl.

عاود شغّل المواد أو الحركة بشكل مستقل

التلوين والحركة كيخدمو على مجلد تشغيل مكتمل، لذلك تقدر تعاود أي مرحلة بموديل آخر أو من بعد فشل، بلا ما تعاود تولّد الهندسة:

bun run scripts/paint.ts RUN_DIRECTORY --model MODEL_KEY --refine-steps 2
bun run scripts/motion.ts RUN_DIRECTORY --model MODEL_KEY --urdf --no-validate

الخيار الاختياري --no-validate كيتخطّى التحقّق من الحركة. هادشي مفيد ملي كيكون Isaac Sim ما متاحش أو ملي كتحتاج غير ملفات الحركة المصدّرة.

عالِج مجموعة بيانات

إلى كانت عندك حالات متعددة، استعمل سكريبت الدفعة مع ملف prompts بصيغة JSON Lines:

bun run scripts/batch.ts \
  --prompts cases.jsonl --images \
  --incremental \
  --motion --validate --urdf \
  --max-steps 3 \
  --parallel 2 \
  --out-root outputs/batch_v1

الوركفلو ديال الورقة كيولّد الشكل والمفاصل مجموعين، ومن بعد كيدهن كل حالة كمّلات بوحدها. هاد الشي كيمنع فشل الدهان من أنه يفسد الهندسة اللي كمّلات:

bun run scripts/paint.ts outputs/batch_v1/CASE_ID

خلي التوازي قريب لجوج ملي كتستعمل --motion --validate، حيث بزاف ديال نسخ Isaac Sim خدامين بلا واجهة يقدرو يستهلكو ميموار ديال GPU كامل. دفعات التحسين بوحدها تقدر تتحمل تقريباً من 8 حتى لـ12 خدام، ولكن كل دورة كتشعل Blender، وبهذا الميموار يقدر يولي هو العامل المحدِّد قبل حدود معدل طلبات API.

قارن مخرجات التشغيل

Procedura فيها سيرفر محلي للنتائج باش تشوف التصييرات، الملفات المصدرية، القياسات، والمسارات ديال بزاف ديال الإعدادات حدّا لحدا:

bun run scripts/results-server.ts \
  --root a=outputs/run_a \
  --root b=outputs/run_b

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

استعمل Procedura Studio

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

cd web
bun install
bun run start

حلّ http://localhost:8080. Studio كتشغّل CLI من الجذر ديال المستودع وكتقرا نفس .env، وبهذا ما كتحتاج حتى إعداد منفصل للـAPI.

نصائح متقدمة

1. بدا بالرخيص، ومن بعد زِد ميزات الجودة. جرّب نقطة النهاية والبرومبت ديالك بتشغيل نصّي عادي قبل ما تفعّل توليد الصور، التغذية الراجعة البصرية، الدهان، ولا الحركة.
2. استعمل مرجع حقيقي إلا أمكن. المشروع كيعتبر --image أكبر تحسين منفرد فالدقة.
3. بدّل الموديلات حسب المرحلة. استعمل --agent-model، أو --scad-model، أو --paint-model، أو --motion-model باش تختار مفاتيح موديلات مختلفة لنقط النهاية ديال كل مرحلة.
4. حافظ على الهندسة الناجحة. شغّل الدهان والحركة كمراحل منفصلة من بعد التوليد ملي ما بغيتيش الفشل يفرض إعادة البناء كاملة.
5. راقب الميموار أثناء التشغيل المتوازي. Blender وIsaac Sim يقدرو يستهلكو ميموار كبير حتى إلا كانت نقطة النهاية ديال API قادرة تعالج طلبات متزامنة أكثر.
6. فحص المسارات ملي كتقلب على المشاكل. ملف المسار بصيغة JSONL ومجلدات التحسين ديال كل خطوة كيكشفو البرومبتات، ردود الموديلات، التعديلات، نتائج المترجم، وقرارات البوابات.
7. تأكد من دعم الواجهة الخلفية ديال OpenSCAD. إلا بان التوليد واقف، تأكد باللي Procedura كتستعمل OpenSCAD قادر على Manifold وماشي إصدار قديم خدام غير بـCGAL.

الخلاصة

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

Procedura مرخّصة برخصة MIT. توثيق المشروع، والورقة، وتفاصيل إضافية متوفرة فـصفحة مشروع Procedura.