Procedura yordamida matndan tahrirlanadigan 3D modellar yarating

Procedura nima?

Procedura matnli so‘rovni tahrirlanadigan protseduraviy yig‘ma modelga aylantiradigan agentik 3D modellashtirish quvuridir. U faqat nuqtalar buluti yoki uchburchaklar to‘rini hosil qilish o‘rniga, nomlangan qismlari tiplashtirilgan biriktirgichlar orqali bog‘langan parametrik OpenSCAD dasturini yozadi. Siz manba kodini ko‘rishingiz, tahrirlashingiz va uni qayta kompilyatsiya qilishingiz mumkin.

Tizim muzlatilgan katta til modelidan foydalanadi va maxsus 3D o‘qituvini talab qilmaydi. Ishga tushirish faqat matn bilan boshlanishi, mavjud namunaviy tasvirni qayta tiklashi yoki alohida sozlangan tasvir modeli orqali namuna yaratishi mumkin.

Procedura shuningdek --paint yordamida har bir qismga alohida PBR materiallarini belgilashi hamda --motion va --motion-urdf yordamida artikulyatsiyalangan obyektlarni OpenUSD va URDF formatlariga eksport qilishi mumkin.

Asosiy imkoniyatlar

• Tahrirlanadigan protseduraviy natija: Kompilyatsiya qilingan geometriya bilan birga OpenSCAD manba kodini ham hosil qiladi.
• Qismma-qism generatsiya: Obyektni rejalashtiradi va uning nomlangan komponentlarini bosqichma-bosqich yaratadi.
• Namunaviy tasvirni qayta tiklash: Mavjud tasvirni qabul qilib, aniqlikni sezilarli darajada oshiradi.
• 3D fikr-mulohaza: Har bir yangi qismni yaratishdan oldin joriy yig‘ilmani render qilishi mumkin.
• Yig‘ilmaga mos modellashtirish: Nominal o‘lchamlari umumiy shtiftlar, uyalar, bolt naqshlari va mahkamlagichlar kabi biriktirish xususiyatlarini qo‘llab-quvvatlaydi.
• Iterativ takomillashtirish: Qoralamani yaxshilash uchun render, tanqid, tuzatish va tekshiruv sikllaridan foydalanadi.
• Materiallar: Tasvirga asoslangan bosqich har bir qism uchun rang, metallik va g‘adir-budirlikni belgilashi mumkin.
• Artikulyatsiya: Harakatni rejalashtirishi, OpenUSD va URDF fayllarini eksport qilishi hamda ixtiyoriy ravishda NVIDIA Isaac Sim’da fizikani tekshirishi mumkin.
• Kuzatiladigan ishga tushirishlar: So‘rovlar, javoblar, vosita chaqiruvlari, tekshiruv qarorlari, oraliq renderlar va tahrirlarni saqlaydi.
• Web Studio: Ishga tushirishlarni tuzish va ularning artefaktlarini ko‘rish uchun brauzer interfeysini taqdim etadi.

Talablar va o‘rnatish

Repozitoriyani klonlang va uning bog‘liqliklar o‘rnatuvchisini ishga tushiring:

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

O‘rnatuvchi Bun 1.3 yoki undan yangirog‘ini, loyiha paketlarini, Manifold’ni qo‘llab-quvvatlaydigan OpenSCAD snapshot versiyasini, Blender’ni va boshlang‘ich .env faylini sozlaydi. Standart bo‘yicha Bun ~/.bun ichiga, OpenSCAD ~/opt/openscad ichiga, Blender esa ~/opt/blender/ ichiga joylashtiriladi.

Skriptni qayta-qayta ishga tushirish xavfsiz. Ishlayotgan mavjud komponentlarga tegilmaydi. Bog‘liqliklarni tekshirish, Blender’ni o‘tkazib yuborish yoki boshqa o‘rnatish prefiksini tanlash uchun uning ixtiyoriy rejimlaridan foydalaning:

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

--check hech narsa o‘rnatmasdan yetishmayotgan talablar haqida hisobot beradi. --no-blender taxminan 350 MB hajmdagi Blender yuklab olinishini o‘tkazib yuboradi, biroq bir nechta render va fikr-mulohaza imkoniyatlari uchun Blender kerak bo‘ladi.

OpenSCAD Manifold backend’ini qo‘llab-quvvatlashi shart. Eski distributiv paketlar CGAL’ga qaytib, hisoblashni bir necha baravar sekinlashtirishi mumkin. Procedura ishga tushishda --backend parametrini tekshiradi va odatda mos kelmaydigan yig‘ilmani ishlatishdan bosh tortadi. Bu sekinlashuvni ataylab qabul qilsangizgina PROCEDURA_ALLOW_CGAL_OPENSCAD=1 ni o‘rnating.

O‘rnatuvchi NVIDIA Isaac Sim’ni o‘rnatmaydi. Isaac Sim faqat harakat jarayonlari bilan bog‘liq fizikani tekshirish uchun kerak; Procedura’ning qolgan qismi usiz ham ishlaydi. O‘rnatuvchi mavjud .env faylini ham saqlab qoladi.

LLM endpoint’ini sozlash

Procedura API kalitlari yoki joylashtirilgan inferens backend’ini o‘z ichiga olmaydi. Yaratilgan .env faylini ochib, endpoint va kalitni kiriting:

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

Endpoint server tomonidan yuboriladigan hodisalar bilan POST {base}/chat/completions so‘rovini qo‘llab-quvvatlashi kerak. Mos variantlar qatoriga OpenAI API, OpenRouter, korporativ gateway yoki vLLM, Ollama yoxud LM Studio asosidagi lokal serverlar kirishi mumkin.

Model tanlovi satr ko‘rinishida beriladi, shuning uchun sozlangan endpoint taqdim etadigan istalgan model identifikatoridan foydalanishingiz mumkin. Sinovdan o‘tgan presetlar va modelni aniqlash qoidalari src/config/models.ts faylida hujjatlashtirilgan.

Gemini’ning native transportidan foydalanish

Gemini’dan native GenAI yo‘li orqali foydalanish uchun GEMINI_API_KEY va GEMINI_BASE_URL ni o‘rnating, so‘ng model identifikatori oldiga gemini: prefiksini qo‘shing:

PROCEDURA_MODEL=gemini:gemini-3-pro-preview

Bu yo‘l thinkingConfig va birinchi darajali fikr qismlari kabi native imkoniyatlarni taqdim etadi.

Ixtiyoriy tasvir generatsiyasi

Procedura tasvir API’siga faqat uni aniq sozlaganingiz yoki so‘raganingizdagina murojaat qiladi. Namunaviy tasvirlarni generatsiya qilishni yoqish uchun tasvir modelini qo‘shing:

PROCEDURA_IMAGE_MODEL=gpt-image-1

Tasvir modeli OPENAI_BASE_URL va OPENAI_API_KEY dan qayta foydalanadi. --image yoki sozlangan tasvir modeli bo‘lmasa, ishga tushirishlar faqat matn bilan cheklanadi va tasvir generatsiyasi uchun to‘lovlar yashirincha yuzaga kelmaydi.

Birinchi modelingizni yarating

Natija katalogi majburiy. Uni -o yoki --output bilan ko‘rsating, so‘ng matnli so‘rov bering:

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

Ushbu standart ish jarayoni komponentlarni rejalashtiradi, ularni birma-bir yaratadi va to‘liq shaklni takomillashtiradi. U faqat matn bilan ishlaydi, rasm API’sidan foydalanmaydi va Blender’ni har bir qism uchun qoralama sikliga qo‘shmaydi. Bu foydali bo‘lgan eng kam xarajatli konfiguratsiyadir.

Barcha qo‘llab-quvvatlanadigan parametrlarni ko‘rish uchun quyidagini ishga tushiring:

bun run scripts/procedura.ts --help

Namuna Rasm Bilan Aniqlikni Oshirish

Namuna rasm taqdim etish loyiha aniqligini sezilarli darajada oshiradigan eng katta alohida omildir. O‘zingizda mavjud rasmni tavsiflovchi prompt bilan birga uzating:

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

Shuningdek, rasm modelini nomlash orqali ushbu ishga tushirish jarayonida namuna rasmni yaratishingiz mumkin:

bun run scripts/procedura.ts -o outputs/daybed \
  --image-model gpt-image-1 \
  --prompt "a brass daybed with tapered legs"

Shell’da qo‘shtirnoqqa olish noqulay bo‘lgan uzun tavsiflar uchun prompt’ni faylga saqlang:

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

To‘liq Sifat Pipeline’ini Ishga Tushirish

To‘liq ishga tushirish jarayoni namuna asosida qayta yaratish, vizual fikr-mulohaza, yig‘ish xususiyatlari, materiallar, harakat va uzoqroq takomillashtirish byudjetini birlashtirishi mumkin. Katta rejalar uchun LLM limitlari yuqoriroq bo‘lishi talab qilinishi mumkin, shuning uchun avval ikkala timeout o‘zgaruvchisini ham oshiring:

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 "a two-finger parallel robot gripper"

Har bir parametrning o‘ziga xos vazifasi bor:

• --3d-feedback generatorga har bir qismni yaratishdan oldin joriy yig‘maning render qilingan ko‘rinishini beradi. Bu har bir qism uchun bittadan Blender bosqichini qo‘shadi.
• --assembly faqat ustma-ust tushadigan geometriyaga tayanish o‘rniga haqiqiy birikish interfeyslarini qo‘shadi.
• --paint nomlangan qismlarga PBR material xususiyatlarini belgilash uchun vision chaqiruvdan foydalanadi.
• --motion artikulyatsiyani rejalashtiradi va OpenUSD ma’lumotlarini eksport qiladi.
• --motion-urdf qo‘shimcha ravishda URDF fayllari va har bir havola uchun mesh’larni yaratadi.
• --max-steps 12 ko‘pi bilan 12 ta takomillashtirish sikliga ruxsat beradi. Har bir siklda render, tanqidiy tahlil, patch va gate amallari bajariladi hamda ikkita LLM chaqiruvi sarflanadi.

Uzoq davom etadigan rejalashtirish chaqiruvlari pipeline mazmunli ish bajarayotganini ko‘rsatishi mumkin. README PROCEDURA_MAX_PARTS ni cheklash o‘rniga timeout’larni oshirishni tavsiya qiladi, chunki qismlar sonini cheklash tezlik evaziga model sifatini pasaytiradi.

Davom Ettirish, Qayta Yaratish yoki Takomillashtirishni O‘tkazib Yuborish

Procedura mavjud chiqish katalogida takomillashtirish siklini davom ettirishi mumkin. Prompt’ni qoldirib, yangi qadamlar byudjetini belgilang:

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

Mavjud qoralamani o‘chirib, uni qaytadan yaratish uchun --redo ni qo‘shing:

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

Faqat qoralama kerak bo‘lganda --no-refine dan foydalaning. Procedura ushbu qoralamani yakuniy chiqish fayllariga aylantiradi. Eski monolitik ish jarayoni uchun --one-shot rejalashtirish bosqichisiz bitta generatsiya chaqiruvini amalga oshiradi va namuna rasmni talab qiladi:

bun run scripts/procedura.ts -o outputs/daybed \
  --one-shot \
  --image ref.png \
  --prompt "a brutalist brass daybed"

Chiqish Katalogini Tushunish

Yakunlangan ishga tushirish jarayoni quyidagi artefaktlarni o‘z ichiga olishi mumkin:

• image.png: Taqdim etilgan yoki yaratilgan namuna rasm.
• plan.json: Rejalashtirilgan qismlar tuzilmasi.
• _parts/NN_name/: Bosqichma-bosqich generatsiya uchun har bir qism artefaktlari.
• draft.scad va draft.obj: Dastlabki protseduraviy manba va kompilyatsiya qilingan mesh.
• final.scad va final.obj: Takomillashtirilgan yakuniy fayllar.
• final_summary.txt: Yakuniy xulosa va chiqarilgan ulanish ma’lumotlari.
• preview_final/: Yakuniy mesh’ning Blender ambient-occlusion renderi.
• final_materials.json: --paint tomonidan yaratilgan har bir qism uchun rang, metallik va dag‘allik qiymatlari.
• final_painted.scad, final_painted.obj va final_painted.mtl: Bo‘yalgan model aktivlari.
• preview_painted/: Bo‘yalgan modelning PBR Cycles renderi.
• motion/final_motion.usda: OpenUSD artikulyatsiya chiqishi.
• motion/urdf/ va motion/links/: So‘ralganda URDF ma’lumotlari va har bir havola uchun mesh’lar.
• _trajectory/procedura-id.jsonl: Prompt’lar, javoblar, vosita chaqiruvlari va gate qarorlari.
• _refine_steps/step_NNN/: Har bir takomillashtirish sikli uchun render, tashxis, tahrir va kompilyatsiya ma’lumotlari.

Procedura yozadigan har bir OBJ fayli birlik chegaralovchi qutisiga normallashtiriladi. STL eksporti ixtiyoriy bo‘lib, uni --export-stl bilan yoqish mumkin.

Materiallar yoki Harakatni Mustaqil Ravishda Qayta Ishga Tushirish

Bo‘yash va harakat tugallangan ish katalogida ishlaydi, shuning uchun geometriyani qayta yaratmasdan har ikkala bosqichni boshqa model bilan yoki xatolikdan keyin takrorlashingiz mumkin:

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

Ixtiyoriy --no-validate parametri harakatni tekshirishni o‘tkazib yuboradi. Bu Isaac Sim mavjud bo‘lmaganda yoki faqat eksport qilingan artikulyatsiya fayllari kerak bo‘lganda foydalidir.

Ma’lumotlar To‘plamini Qayta Ishlash

Bir nechta holat uchun JSON Lines prompt fayli bilan batch skriptidan foydalaning:

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

Maqola ish jarayonida shakl va artikulyatsiya birgalikda yaratiladi, so‘ng har bir yakunlangan holat alohida bo‘yaladi. Bu bo‘yashdagi xatolik yakunlangan geometriyani yaroqsiz holga keltirishining oldini oladi:

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

--motion --validate parametrlaridan foydalanganda parallel ishlash darajasini ikkiga yaqin saqlang, chunki bir nechta headless Isaac Sim nusxasi GPU xotirasini tugatib qo‘yishi mumkin. Faqat takomillashtirishga mo‘ljallangan paketlar taxminan 8–12 ta ishchini ko‘tara oladi, biroq har bir sikl Blender’ni ishga tushiradi, shu sababli API tezlik cheklovlaridan oldin xotira cheklovchi omilga aylanishi mumkin.

Ishga Tushirish Artefaktlarini Taqqoslash

Procedura turli konfiguratsiyalardagi renderlar, manba fayllari, ko‘rsatkichlar va trayektoriyalarni yonma-yon ko‘rish uchun lokal natijalar serverini o‘z ichiga oladi:

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

Bu promptlar, bosqichga xos modellar, takomillashtirish budjetlari yoki 3D fikr-mulohazasi va yig‘ishga yo‘naltirilgan generatsiya kabi parametrlarni sinashda foydalidir.

Procedura Studio’dan Foydalanish

Studio ayni pipeline uchun mo‘ljallangan veb interfeysdir. U prompt, ixtiyoriy reference rasm, presetlar va har bir bosqich uchun boshqaruv elementlari bilan ishga tushirishni tuzish imkonini beradi. Bajarilish jarayonida qismlar paydo bo‘lishini kuzatish hamda reja, qismlar artefaktlari, takomillashtirish tarixi, yakuniy 3D mesh, materiallar va artikulyatsiyani tekshirish mumkin.

cd web
bun install
bun run start

http://localhost:8080 manzilini oching. Studio CLI’ni repozitoriy ildizidan ishga tushiradi va ayni .env faylini o‘qiydi, shuning uchun alohida API konfiguratsiyasi talab qilinmaydi.

Ilg‘or Maslahatlar

1. Avval arzonroq boshlang, keyin sifat funksiyalarini qo‘shing. Rasm generatsiyasi, vizual fikr-mulohaza, bo‘yash yoki harakatni yoqishdan oldin endpoint va promptingizni standart, faqat matnga asoslangan ishga tushirish orqali tekshiring.
2. Iloji bo‘lsa, haqiqiy reference’dan foydalaning. Loyiha --image parametrini aniqlikni eng ko‘p oshiradigan yagona omil sifatida ko‘rsatadi.
3. Modellarni bosqichlar bo‘yicha almashtiring. Alohida bosqichlar uchun turli endpoint model kalitlarini tanlashda --agent-model, --scad-model, --paint-model yoki --motion-model parametrlaridan foydalaning.
4. Muvaffaqiyatli geometriyani saqlab qoling. Xatoliklar to‘liq qayta qurishni talab qilmasligi uchun bo‘yash va harakatni alohida, keyingi qayta ishlash bosqichlari sifatida ishga tushiring.
5. Parallel ishga tushirishlarda xotirani kuzating. API endpointingiz ko‘proq bir vaqtdagi so‘rovlarni bajara olsa ham, Blender va Isaac Sim katta hajmda xotira sarflashi mumkin.
6. Muammolarni tuzatishda trayektoriyalarni tekshiring. JSONL trayektoriyasi va har bir qadam uchun takomillashtirish kataloglari promptlar, model javoblari, tahrirlar, kompilyator natijalari va nazorat qarorlarini ko‘rsatadi.
7. OpenSCAD backend qo‘llab-quvvatlanishini tasdiqlang. Agar generatsiya to‘xtab qolgandek ko‘rinsa, Procedura eski, faqat CGAL’ni qo‘llab-quvvatlaydigan versiya o‘rniga Manifold’ni qo‘llab-quvvatlaydigan OpenSCAD’dan foydalanayotganini tekshiring.

Xulosa

Procedura til modeliga asoslangan rejalashtirishni protseduraviy CAD, mesh kompilyatsiyasi, vizual takomillashtirish, materiallar va ixtiyoriy artikulyatsiya bilan birlashtiradi. Konfiguratsiya qilingan endpoint va oddiy matnli promptdan boshlang, so‘ng sifat talablari oshgani sari reference rasm, 3D fikr-mulohazasi, yig‘ish funksiyalari, bo‘yash va harakatni qo‘shing. Asosiy natija tahrirlash mumkin bo‘lgan manba kodi bo‘lgani uchun, yaratilgan obyektlar generatsiyadan keyin ham tekshiriladigan va qayta foydalaniladigan bo‘lib qoladi.

Procedura MIT litsenziyasi asosida tarqatiladi. Loyiha hujjatlari, maqola va qo‘shimcha tafsilotlar Procedura loyiha sahifasida mavjud.