Yakha Amamodeli e-3D Ahlelekayo Ngombhalo nge-Procedura

Yini i-Procedura?

I-Procedura iyipayipi lokumodela le-3D elisebenzisa ama-agent, eliguqula umbhalo owufakayo ube umhlangano wenqubo ohlelekayo. Esikhundleni sokukhiqiza kuphela ifu lamaphoyinti noma i-triangle mesh, ibhala uhlelo lwe-parametric OpenSCAD olunezingxenye eziqanjwe amagama, ezixhunywe ngama-mate anezinhlobo. Ungahlola umthombo, uwuhlele, bese uwuhlanganisa futhi.

Uhlelo lusebenzisa imodeli yolimi enkulu eqandisiwe futhi aludingi ukuqeqeshwa okukhethekile kwe-3D. Ukuqalisa kungase kusekelwe embhalweni kuphela, kwakhe kabusha isithombe sereferensi esikhona, noma kukhiqize ireferensi ngemodeli yesithombe ehlelwe ngokwehlukile.

I-Procedura ingabela futhi izinto ze-PBR ingxenye ngayinye nge---paint, bese ithumela izinto ezikwazi ukunyakaza ku-OpenUSD naku-URDF nge---motion kanye ne---motion-urdf.

Izici Eziyinhloko

• Okuphumayo kwenqubo okuhlelekayo: Ikhiqiza ikhodi yomthombo ye-OpenSCAD kanye nejometri ehlanganisiwe.
• Ukukhiqiza ingxenye ngayinye: Ihlela into bese yakha izingxenye zayo eziqanjwe amagama kancane kancane.
• Ukwakha kabusha isithombe sereferensi: Yamukela isithombe esikhona ukuze ithuthukise kakhulu ukufana.
• Impendulo ye-3D: Ingakwazi ukunikeza isithombe sokwakhiwa kwamanje ngaphambi kokukhiqiza ingxenye entsha ngayinye.
• Ukumodela okuqaphela umhlangano: Isekela izici zokuhlanganisa ezifana nezikhonkwane ezinobukhulu obufanayo, amasokhethi, amaphethini amabhawodi, nama-snap.
• Ukucwengwa okuphindaphindwayo: Isebenzisa imijikelezo yokunikeza isithombe, ukugxeka, ukupasha, kanye nesango ukuze ithuthukise uhlaka.
• Izinto: Isigaba esisekelwe kumbono singabela umbala, i-metalness, kanye ne-roughness engxenyeni ngayinye.
• Ukunyakaza kwamalunga: Ingahlela ukunyakaza, ithumele amafayela e-OpenUSD ne-URDF, futhi iqinisekise ngokuzikhethela i-physics ku-NVIDIA Isaac Sim.
• Imisebenzi elandelekayo: Igcina ama-prompt, izimpendulo, ukubizwa kwamathuluzi, izinqumo zamasango, izithombe eziphakathi, kanye nokuhlela.
• Web Studio: Inikeza isixhumi esibonakalayo sesiphequluli sokuhlanganisa imisebenzi nokuhlola izinto ezikhiqiziwe.

Izidingo Zokuqala Nokufakwa

Yenza i-clone ye-repository bese usebenzisa isifaki samaphakheji ayo:

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

Isifaki silungisa i-Bun 1.3 noma entsha, amaphakheji ephrojekthi, i-snapshot ye-OpenSCAD ekwazi ukusebenzisa i-Manifold, i-Blender, kanye nefayela lokuqala le-.env. Ngokuzenzakalelayo, i-Bun ibekwa ngaphansi kwe-~/.bun, i-OpenSCAD ngaphansi kwe-~/opt/openscad, kanti i-Blender ibekwa ngaphansi kwe-~/opt/blender/.

Iskripthi siphephile ukusisebenzisa ngokuphindaphindiwe. Izingxenye ezisebenzayo ezikhona ziyashiywa njengoba zinjalo. Sebenzisa izindlela zaso ozikhethela zona ukuhlola izidingo, ukweqa i-Blender, noma ukukhetha enye i-prefix yokufaka:

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

--check ibika izidingo ezingekho ngaphandle kokufaka noma yini. --no-blender yeqa ukulanda kwe-Blender okucishe kube ngu-350 MB, nakuba i-Blender idingeka ezicini eziningana zokunikeza izithombe nempendulo.

I-OpenSCAD kufanele isekele i-backend ye-Manifold. Amaphakheji amadala okusabalalisa angabuyela ku-CGAL futhi abe kancane kakhulu. I-Procedura ihlola i---backend ekuqaleni futhi ngokuvamile iyenqaba ukusebenzisa i-build engahambisani. Setha PROCEDURA_ALLOW_CGAL_OPENSCAD=1 kuphela uma wamukela ngamabomu lokho kwehla kwejubane.

Isifaki asifaki i-NVIDIA Isaac Sim. I-Isaac Sim idingeka kuphela ekuqinisekiseni i-physics okuhlobene nemisebenzi yokunyakaza; yonke enye i-Procedura isebenza ngaphandle kwayo. Isifaki siphinde sigcine ifayela le-.env elikhona.

Hlela I-LLM Endpoint

I-Procedura ayinawo okhiye be-API noma i-backend yokusebenzisa amamodeli ephethwe. Vula ifayela le-.env elikhiqiziwe bese unikeza i-endpoint nokhiye:

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

I-endpoint kufanele isekele POST {base}/chat/completions ngemicimbi ethunyelwa yiseva. Izinketho ezihambisanayo zingafaka i-OpenAI API, i-OpenRouter, i-gateway yenkampani, noma amaseva endawo asekelwe ku-vLLM, Ollama, noma LM Studio.

Ukukhethwa kwemodeli kuyintambo, ngakho ungasebenzisa noma yisiphi isihlonzi semodeli esinikezwa yi-endpoint ehleliwe. Ama-preset aziwayo asebenza kahle nemithetho yokuxazulula amamodeli kubhalwe ku-src/config/models.ts.

Sebenzisa I-Gemini Transport Yendabuko

Ukuze usebenzise i-Gemini ngendlela yayo yomdabu ye-GenAI, setha GEMINI_API_KEY kanye ne-GEMINI_BASE_URL, bese uqala isihlonzi semodeli nge-gemini::

PROCEDURA_MODEL=gemini:gemini-3-pro-preview

Le ndlela iveza izici zomdabu ezifana ne-thinkingConfig nezingxenye zemicabango ezisekelwa ngqo.

Ukukhiqiza Izithombe Ngokuzikhethela

I-Procedura ayishayeli i-API yezithombe ngaphandle kokuthi uyihlele noma uyicele ngokusobala. Ukuze unike amandla izithombe ezikhiqiziwe zamareferensi, engeza imodeli yezithombe:

PROCEDURA_IMAGE_MODEL=gpt-image-1

Imodeli yezithombe iphinde isebenzise OPENAI_BASE_URL kanye ne-OPENAI_API_KEY. Ngaphandle kwe---image noma imodeli yezithombe ehleliwe, imisebenzi ihlala isekelwe embhalweni kuphela futhi ayibangeli ngokufihlekile izindleko zokukhiqiza izithombe.

Dala Imodeli Yakho Yokuqala

Uhla lwemibhalo lokuphumayo luyadingeka. Luhlinzeke nge--o noma --output, bese unikeza i-prompt yombhalo:

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

Lokhu kugeleza komsebenzi okuzenzakalelayo kuhlela izingxenye, kuzakhe ngayinye ngesikhathi, bese kucwengisisa umumo ophelele. Kusekelwe embhalweni kuphela, akusebenzisi i-image API, futhi akufaki i-Blender emjikelezweni wokusalungiswa wengxenye ngayinye. Lokhu ukumiswa okungabizi kakhulu kodwa okuwusizo.

Ukuze ubone zonke izinketho ezisekelwayo, sebenzisa:

bun run scripts/procedura.ts --help

Thuthukisa Ukunemba Ngesithombe Esiyisithenjwa

Ukunikeza isithombe esiyisithenjwa kuwukuthuthukiswa okukhulu kakhulu kokunemba okuhlonzwe iphrojekthi. Dlulisa isithombe osuvele unaso kanye nomyalo ochazayo:

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

Ngaphandle kwalokho, yenza isithenjwa phakathi nalokhu kuqalisa ngokunikeza igama lemodeli yesithombe:

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

Ezincazelweni ezinde okunzima ukuzicaphuna ku-shell, gcina umyalo efayeleni:

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

Qalisa Ipayiphi Egcwele Yekhwalithi

Ukuqalisa okuphelele kungahlanganisa ukwakha kabusha kusetshenziswa isithenjwa, impendulo ebonakalayo, izici zokuhlanganisa, izinto zokwakha, ukunyakaza, kanye nesabelomali eside sokucwengisisa. Izinhlelo ezinkulu zingadinga imikhawulo emide ye-LLM, ngakho qala uphakamise zombili iziguquguquko zesikhathi sokulinda:

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"

Inketho ngayinye inendima yayo ehlukile:

• --3d-feedback inikeza umakhi umbono onikeziwe we-assembly yamanje ngaphambi kokuba adale ingxenye ngayinye. Lokhu kwengeza ukudlula okukodwa kwe-Blender ngengxenye ngayinye.
• --assembly yengeza izindawo zangempela zokuhlanganisa esikhundleni sokuthembela kuphela ku-geometry egqagqanayo.
• --paint isebenzisa ucingo lombono ukwabela izingxenye eziqanjwe izakhiwo zezinto ze-PBR.
• --motion ihlela ukunyakaza okuhlangene futhi ikhiphe idatha ye-OpenUSD.
• --motion-urdf futhi idala amafayela e-URDF nama-mesh engxenye ngayinye.
• --max-steps 12 ivumela imijikelezo yokucwengisisa efinyelela ku-12. Umjikelezo ngamunye wenza imisebenzi yokunikezela, ukugxeka, ukuphesha, kanye nesango, futhi usebenzisa izingcingo ezimbili ze-LLM.

Izingcingo zokuhlela ezinde zingabonisa ukuthi ipayiphi lenza umsebenzi obalulekile. I-README incoma ukuphakamisa izikhathi zokulinda esikhundleni sokukhawulela PROCEDURA_MAX_PARTS, ngoba ukukhawulela inani lezingxenye kushintshanisa ikhwalithi yemodeli ngesivinini.

Qhubeka, Yenza Kabusha, noma Yeqa Ukucwengisisa

I-Procedura ingaqhubeka nomjikelezo wokucwengisisa kufolda ekhona yemiphumela. Shiya umyalo bese ucacisa isabelomali esisha sezinyathelo:

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

Ukuze ulahle okusaliswayo okukhona bese ukudala futhi, engeza --redo:

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

Sebenzisa --no-refine uma ufuna kuphela okusaliswayo. I-Procedura idlulisela lokho kusaliswayo kumafayela okugcina emiphumela. Kugelezo lomsebenzi elidala eliyingcezu eyodwa, --one-shot yenza ucingo olulodwa lokukhiqiza ngaphandle kwesigaba sokuhlela futhi idinga isithombe esiyisithenjwa:

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

Qonda Ifolda Yemiphumela

Ukuqalisa okuqediwe kungaba nalezi zinto ezilandelayo:

• image.png: Isithombe esiyisithenjwa esinikeziwe noma esikhiqiziwe.
• plan.json: Isakhiwo sezingxenye esihleliwe.
• _parts/NN_name/: Izinto zengxenye ngayinye zokukhiqiza kancane kancane.
• draft.scad kanye draft.obj: Umthombo wokuqala wenqubo kanye ne-mesh ehlanganisiwe.
• final.scad kanye final.obj: Imiphumela yokugcina ecwengisisiwe.
• final_summary.txt: Isinqumo sokugcina kanye nolwazi lokuxhumana oluthunyelwe.
• preview_final/: Ukunikezwa kwe-Blender kwe-mesh yokugcina kusetshenziswa i-ambient occlusion.
• final_materials.json: Umbala, i-metalness, kanye ne-roughness yengxenye ngayinye okukhiqizwe yi---paint.
• final_painted.scad, final_painted.obj, kanye final_painted.mtl: Izimpahla zemodeli ependiwe.
• preview_painted/: Ukunikezwa kwe-Cycles kwe-PBR kwemodeli ependiwe.
• motion/final_motion.usda: Umphumela wokunyakaza ohlanganisiwe we-OpenUSD.
• motion/urdf/ kanye motion/links/: Idatha ye-URDF nama-mesh ezixhumanisi ngayinye uma kuceliwe.
• _trajectory/procedura-id.jsonl: Imiyalo, izimpendulo, izingcingo zamathuluzi, kanye nezinqumo zesango.
• _refine_steps/step_NNN/: Idatha yokunikezela, ukuxilonga, ukuhlela, kanye nokuhlanganisa yomjikelezo ngamunye wokucwengisisa.

Wonke amafayela e-OBJ abhalwe yi-Procedura alungiswa abe yibhokisi elibophayo eliyunithi. Ukukhipha i-STL kuyazikhethela futhi kunganikwa amandla nge---export-stl.

Qalisa Kabusha Izinto Zokwakha noma Ukunyakaza Ngokuzimela

Ukupenda nokunyakaza kusebenza kufolda yokuqalisa eseqediwe, ngakho ungaphinda noma yisiphi isigaba usebenzisa enye imodeli noma ngemva kokwehluleka ngaphandle kokukhiqiza kabusha i-geometry:

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

Inketho yokuzikhethela ethi --no-validate yeqa ukuqinisekiswa kokunyakaza. Lokhu kuyasiza uma i-Isaac Sim ingatholakali noma uma udinga kuphela amafayela okunyakaza akhishiwe.

Icubungule Isethi Yedatha

Ezimweni eziningi, sebenzisa iskripthi se-batch kanye nefayela lemiyalo le-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

Ukuhamba komsebenzi kwephepha kwakha ukuma nokunyakaza kwamalunga ndawonye, bese kupenda icala ngalinye eliqediwe ngokwehlukana. Lokhu kuvimbela ukwehluleka kokupenda ukuthi kwenze ijiyomethri eqediwe ingasebenzi:

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

Gcina ukuhambisana kuseduze kokubili uma usebenzisa --motion --validate, ngoba izimo eziningi ze-Isaac Sim ezisebenza ngaphandle kwesibonisi zingase ziqede inkumbulo ye-GPU. Amaqoqo agxile ekucwengisiseni kuphela angase abekezelele cishe abasebenzi abangu-8 kuya kwabangu-12, kodwa umjikelezo ngamunye uqala i-Blender, ngakho inkumbulo ingaba umthombo womkhawulo ngaphambi kwemikhawulo yezinga le-API.

Qhathanisa Imiphumela Yokusebenza

I-Procedura ihlanganisa iseva yemiphumela yasendaweni yokubuka ama-render, amafayela omthombo, amamethrikhi, nemizila yokunyakaza yokulungiselelwa okuningi ngapha nangapha:

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

Lokhu kuyasiza lapho kuhlolwa ama-prompt, amamodeli aqondene nezigaba, amabhajethi okucwengisisa, noma izinketho ezifana nempendulo ye-3D nokukhiqizwa okwazi ngokuhlanganiswa.

Sebenzisa i-Procedura Studio

I-Studio iyisixhumi esibonakalayo sewebhu somzila ofanayo. Ikuvumela ukuthi uhlanganise ukusebenza nge-prompt, isithombe sereferensi ozikhethela sona, ama-preset, nezilawuli zesigaba ngasinye. Ngesikhathi sokusebenza, ungabuka izingxenye zivela futhi uhlole uhlelo, izinto zobuciko zezingxenye, umlando wokucwengisisa, imeshi yokugcina ye-3D, izinto zokwakha, nokunyakaza kwamalunga.

cd web
bun install
bun run start

Vula http://localhost:8080. I-Studio iqala i-CLI isuka empandeni yenqolobane futhi ifunda i-.env efanayo, ngakho ayidingi ukulungiselelwa kwe-API okuhlukile.

Amasu Athuthukile

1. Qala ngokushibhile, bese wengeza izici zekhwalithi. Qinisekisa i-endpoint ne-prompt yakho ngokusebenzisa okuzenzakalelayo kombhalo kuphela ngaphambi kokunika amandla ukukhiqizwa kwezithombe, impendulo ebonakalayo, ukupenda, noma ukunyakaza.
2. Sebenzisa ireferensi yangempela lapho kungenzeka khona. Iphrojekthi ikhomba --image njengokuthuthukiswa okukodwa okukhulu kakhulu kokwethembeka.
3. Shintsha amamodeli ngokwesigaba. Sebenzisa --agent-model, --scad-model, --paint-model, noma --motion-model ukukhetha okhiye bamamodeli e-endpoint abahlukene ezigabeni ezithile.
4. Gcina ijiyomethri ephumelele. Sebenzisa ukupenda nokunyakaza njengezigaba ezihlukene zangemva kokucubungula lapho ukwehluleka kungafanele kuphoqe ukwakhiwa kabusha okuphelele.
5. Qapha inkumbulo ngesikhathi sokusebenza ngokuhambisana. I-Blender ne-Isaac Sim zingasebenzisa inkumbulo enkulu ngisho nalapho i-endpoint yakho ye-API ikwazi ukuphatha izicelo eziningi ngesikhathi esisodwa.
6. Hlola imizila yokunyakaza lapho ulungisa amaphutha. I-trajectory ye-JSONL nezinkomba zokucwengisisa zesinyathelo ngasinye ziveza ama-prompt, izimpendulo zamamodeli, ukuhlela, imiphumela yabahlanganisi, nezinqumo zamasango.
7. Qinisekisa ukwesekwa kwe-backend ye-OpenSCAD. Uma ukukhiqizwa kubonakala kumile, qinisekisa ukuthi i-Procedura isebenzisa i-OpenSCAD ekwazi i-Manifold esikhundleni sokwakhiwa kwakudala okusekela i-CGAL kuphela.

Isiphetho

I-Procedura ihlanganisa ukuhlela kwemodeli yolimi ne-CAD ye-procedural, ukuhlanganiswa kwemeshi, ukucwengisiswa okubonakalayo, izinto zokwakha, nokunyakaza kwamalunga okungakhethwa. Qala nge-endpoint elungiselelwe kanye ne-prompt elula yombhalo, bese wengeza isithombe sereferensi, impendulo ye-3D, izici zokuhlanganisa, ukupenda, nokunyakaza njengoba izidingo zakho zekhwalithi zikhula. Ngenxa yokuthi umphumela oyinhloko uyikhodi yomthombo ehlelekayo, izinto ezikhiqiziwe zihlala zihlolwa futhi zisetshenziswe kabusha ngemva kokukhiqizwa.

I-Procedura inelayisensi ye-MIT. Imibhalo yephrojekthi, iphepha, neminye imininingwane kuyatholakala ekhasini lephrojekthi ye-Procedura.