Jenga Miundo ya 3D Inayoweza Kuhaririwa Kutoka kwa Maandishi ukitumia Procedura

Procedura Ni Nini?

Procedura ni mchakato wa uundaji wa modeli za 3D unaotumia mawakala, ambao hubadilisha amri ya maandishi kuwa mkusanyiko wa kiparameta unaoweza kuhaririwa. Badala ya kuzalisha tu wingu la pointi au mesh ya pembetatu, huandika programu ya OpenSCAD yenye vipengele vilivyopewa majina na kuunganishwa kupitia viunganishi vilivyo na aina. Unaweza kukagua chanzo, kukihariri na kukikusanya tena.

Mfumo huu hutumia modeli kubwa ya lugha iliyogandishwa na hauhitaji mafunzo maalum ya 3D. Uendeshaji unaweza kuanza kwa maandishi pekee, kujenga upya picha ya marejeo iliyopo, au kuzalisha marejeo kupitia modeli ya picha iliyosanidiwa kando.

Procedura pia inaweza kugawa vifaa vya PBR kwa kila sehemu kwa kutumia --paint na kuhamisha vitu vinavyoweza kusogezwa hadi OpenUSD na URDF kwa kutumia --motion na --motion-urdf.

Vipengele Muhimu

• Matokeo ya kiparameta yanayoweza kuhaririwa: Huzalisha msimbo wa chanzo wa OpenSCAD pamoja na jiometri iliyokusanywa.
• Uzalishaji sehemu kwa sehemu: Hupanga kitu na kujenga vipengele vyake vilivyopewa majina hatua kwa hatua.
• Ujenzi upya kutoka kwa picha ya marejeo: Hukubali picha iliyopo ili kuboresha kwa kiasi kikubwa ufanisi wa ulinganifu.
• Maoni ya 3D: Inaweza kutoa taswira ya muundo wa sasa kabla ya kuzalisha kila sehemu mpya.
• Uundaji unaozingatia mkusanyiko: Husaidia vipengele vya kuunganisha kama pini zenye vipimo vya pamoja, soketi, mifumo ya bolti na klipu.
• Uboreshaji wa kurudia: Hutumia mizunguko ya kutoa taswira, kukosoa, kuweka marekebisho na kukagua ili kuboresha rasimu.
• Vifaa: Hatua inayotegemea uoni inaweza kugawa rangi, kiwango cha metali na ukakasi kwa kila sehemu.
• Uwezo wa kusogezwa: Inaweza kupanga mwendo, kuhamisha faili za OpenUSD na URDF, na kwa hiari kuthibitisha fizikia katika NVIDIA Isaac Sim.
• Uendeshaji unaoweza kufuatiliwa: Huhifadhi amri, majibu, miito ya zana, maamuzi ya ukaguzi, taswira za kati na marekebisho.
• Web Studio: Hutoa kiolesura cha kivinjari cha kuunda miendeshaji na kukagua vielelezo vyake.

Mahitaji na Usakinishaji

Fanya kloni ya hazina kisha uendeshe kisakinishi chake cha vitegemezi:

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

Kisakinishi huweka Bun 1.3 au toleo jipya zaidi, vifurushi vya mradi, toleo la OpenSCAD linaloweza kutumia Manifold, Blender na faili ya mwanzo ya .env. Kwa chaguo-msingi, Bun huwekwa chini ya ~/.bun, OpenSCAD chini ya ~/opt/openscad na Blender chini ya ~/opt/blender/.

Script hii ni salama kuendeshwa mara kwa mara. Vipengele vya kazi vilivyopo huachwa bila kuguswa. Tumia hali zake za hiari kukagua vitegemezi, kuruka Blender au kuchagua njia nyingine ya usakinishaji:

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

--check huripoti mahitaji yaliyokosekana bila kusakinisha chochote. --no-blender huruka upakuaji wa Blender wa takribani MB 350, ingawa Blender inahitajika kwa vipengele kadhaa vya kutoa taswira na kutoa maoni.

OpenSCAD lazima itumie backend ya Manifold. Vifurushi vya zamani vya usambazaji vinaweza kutumia CGAL badala yake na kuwa polepole kwa kiwango kikubwa. Procedura hukagua --backend wakati wa kuanza na kwa kawaida hukataa kutumia muundo usiooana. Weka PROCEDURA_ALLOW_CGAL_OPENSCAD=1 tu ikiwa unakubali kwa makusudi upunguzaji huo wa kasi.

Kisakinishi hakisakinishi NVIDIA Isaac Sim. Isaac Sim inahitajika tu kwa uthibitishaji wa fizikia unaohusiana na mitiririko ya kazi ya mwendo; sehemu nyingine ya Procedura hufanya kazi bila hiyo. Kisakinishi pia huhifadhi faili ya .env iliyopo.

Sanidi Endpoint ya LLM

Procedura haijumuishi funguo za API wala backend ya uelekezaji iliyopangishwa. Fungua faili ya .env iliyozalishwa na uweke endpoint pamoja na ufunguo:

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

Endpoint lazima itumie POST {base}/chat/completions yenye matukio yanayotumwa na seva. Chaguo zinazooana zinaweza kujumuisha OpenAI API, OpenRouter, gateway ya shirika au seva za ndani zinazotumia vLLM, Ollama au LM Studio.

Uteuzi wa modeli ni mfuatano wa herufi, kwa hiyo unaweza kutumia kitambulisho chochote cha modeli kinachotolewa na endpoint iliyosanidiwa. Preseti zinazojulikana kuwa nzuri na kanuni za kutatua modeli zimeandikwa katika src/config/models.ts.

Tumia Usafirishaji Asilia wa Gemini

Kwa Gemini kupitia njia yake asilia ya GenAI, weka GEMINI_API_KEY na GEMINI_BASE_URL, kisha ongeza kiambishi gemini: mwanzoni mwa kitambulisho cha modeli:

PROCEDURA_MODEL=gemini:gemini-3-pro-preview

Njia hii hutoa vipengele asilia kama thinkingConfig na sehemu za mawazo za kiwango cha kwanza.

Uzalishaji wa Picha wa Hiari

Procedura haiiti API ya picha isipokuwa uisanidi au uiombe waziwazi. Ili kuwezesha picha za marejeo zinazozalishwa, ongeza modeli ya picha:

PROCEDURA_IMAGE_MODEL=gpt-image-1

Modeli ya picha hutumia tena OPENAI_BASE_URL na OPENAI_API_KEY. Bila --image au modeli ya picha iliyosanidiwa, miendeshaji hubaki ya maandishi pekee na haisababishi kimyakimya gharama za uzalishaji wa picha.

Unda Modeli Yako ya Kwanza

Saraka ya matokeo inahitajika. Iweke kwa -o au --output, kisha toa amri ya maandishi:

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

Mtiririko huu wa kawaida hupanga vipengele, huviunda kimoja baada ya kingine, na huboresha umbo kamili. Unatumia maandishi pekee, hautumii API ya picha, na hauingizi Blender katika mzunguko wa rasimu wa kila sehemu. Huu ndio usanidi wa gharama ya chini zaidi unaofaa.

Ili kuona chaguo zote zinazotumika, endesha:

bun run scripts/procedura.ts --help

Boresha Uaminifu kwa Picha ya Marejeo

Kutoa picha ya marejeo ndilo uboreshaji mkubwa zaidi wa uaminifu uliotambuliwa na mradi. Pitisha picha ambayo tayari unayo pamoja na mwongozo wa maelezo:

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

Vinginevyo, tengeneza marejeo wakati wa uendeshaji huu kwa kutaja modeli ya picha:

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

Kwa maelezo marefu ambayo ni vigumu kuyaweka katika alama za kunukuu za shell, hifadhi mwongozo kwenye faili:

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

Endesha Mchakato Kamili wa Ubora

Uendeshaji kamili unaweza kuchanganya uundaji upya kutoka marejeo, mrejesho wa kuona, vipengele vya uunganishaji, nyenzo, mwendo, na bajeti ndefu ya uboreshaji. Mipango mikubwa inaweza kuhitaji vikomo virefu vya LLM, kwa hiyo ongeza vigezo vyote viwili vya muda wa kusubiri kwanza:

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"

Kila chaguo lina jukumu lake:

• --3d-feedback huipa jenereta mwonekano uliotolewa wa uunganishaji wa sasa kabla ya kuunda kila sehemu. Hii huongeza mchakato mmoja wa Blender kwa kila sehemu.
• --assembly huongeza miingiliano halisi ya kuunganisha badala ya kutegemea jiometri zinazoingiliana pekee.
• --paint hutumia mwito wa kuona kugawa sifa za nyenzo za PBR kwa sehemu zilizopewa majina.
• --motion hupanga uelekezaji wa mwendo na kusafirisha data ya OpenUSD.
• --motion-urdf huunda pia faili za URDF na mesh za kila kiungo.
• --max-steps 12 huruhusu hadi mizunguko 12 ya uboreshaji. Kila mzunguko hufanya uonyeshaji, ukosoaji, kiraka, na shughuli za lango, na hutumia miito miwili ya LLM.

Miito mirefu ya upangaji inaweza kuashiria kuwa mchakato unafanya kazi muhimu. README inapendekeza kuongeza vikomo vya muda badala ya kuzuia PROCEDURA_MAX_PARTS, kwa sababu kuzuia idadi ya sehemu hubadilisha ubora wa modeli kwa kasi.

Endeleza, Tengeneza Rasimu Upya, au Ruka Uboreshaji

Procedura inaweza kuendelea na mzunguko wa uboreshaji katika saraka ya matokeo iliyopo. Acha mwongozo na bainisha bajeti mpya ya hatua:

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

Ili kutupa rasimu iliyopo na kuiunda tena, ongeza --redo:

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

Tumia --no-refine unapotaka rasimu pekee. Procedura huendeleza rasimu hiyo kuwa faili za mwisho za matokeo. Kwa mchakato wa zamani wa monolithiki, --one-shot hufanya mwito mmoja wa uundaji bila hatua ya upangaji na huhitaji picha ya marejeo:

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

Elewa Saraka ya Matokeo

Uendeshaji uliokamilika unaweza kuwa na vitu vifuatavyo:

• image.png: Picha ya marejeo iliyotolewa au iliyoundwa.
• plan.json: Muundo wa sehemu uliopangwa.
• _parts/NN_name/: Vitu vya kila sehemu kwa ajili ya uundaji wa hatua kwa hatua.
• draft.scad na draft.obj: Chanzo cha awali cha kiutaratibu na mesh iliyokusanywa.
• final.scad na final.obj: Vitu vya mwisho vilivyoboreshwa.
• final_summary.txt: Hukumu ya mwisho na taarifa ya muunganisho iliyowasilishwa.
• preview_final/: Uonyeshaji wa mesh ya mwisho wa Blender wenye occlusion ya mazingira.
• final_materials.json: Rangi, kiwango cha umetaliki, na ukwaru wa kila sehemu vilivyoundwa na --paint.
• final_painted.scad, final_painted.obj, na final_painted.mtl: Vitu vya modeli vilivyopakwa rangi.
• preview_painted/: Uonyeshaji wa Cycles wa PBR wa modeli iliyopakwa rangi.
• motion/final_motion.usda: Matokeo ya uelekezaji wa OpenUSD.
• motion/urdf/ na motion/links/: Data ya URDF na mesh za kila kiungo zinapoombwa.
• _trajectory/procedura-id.jsonl: Miongozo, majibu, miito ya zana, na maamuzi ya lango.
• _refine_steps/step_NNN/: Data ya uonyeshaji, utambuzi, uhariri, na ukusanyaji kwa kila mzunguko wa uboreshaji.

Kila faili la OBJ linaloandikwa na Procedura hurekebishwa kuwa kisanduku cha mipaka cha kitengo. Usafirishaji wa STL ni wa hiari na unaweza kuwezeshwa kwa --export-stl.

Endesha Tena Nyenzo au Mwendo kwa Kujitegemea

Upakaji rangi na mwendo hufanya kazi kwenye saraka ya uendeshaji uliokamilika, kwa hiyo unaweza kurudia hatua yoyote kwa modeli nyingine au baada ya hitilafu bila kuunda upya jiometri:

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

Alama ya hiari ya --no-validate huruka uthibitishaji wa mwendo. Hii ni muhimu wakati Isaac Sim haipatikani au unapohitaji tu faili za uelekezaji zilizotolewa.

Chakata Seti ya Data

Kwa visa vingi, tumia hati ya kundi pamoja na faili ya maelekezo ya 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

Mtiririko wa kazi wa karatasi huzalisha umbo na uunganishaji kwa pamoja, kisha hupaka rangi kila kisa kilichokamilika kivyake. Hii huzuia hitilafu ya upakaji rangi kubatilisha jiometri iliyokamilika:

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

Weka uendeshaji sambamba karibu na miwili unapotumia --motion --validate, kwa sababu matukio mengi ya Isaac Sim yanayoendeshwa bila kiolesura yanaweza kumaliza kumbukumbu ya GPU. Batch za uboreshaji pekee zinaweza kuvumilia takriban wafanyakazi 8 hadi 12, lakini kila mzunguko huanzisha Blender, hivyo kumbukumbu inaweza kuwa rasilimali yenye ukomo kabla ya mipaka ya kasi ya API.

Linganisha Mabaki ya Uendeshaji

Procedura ina seva ya ndani ya matokeo ya kutazama renderi, faili chanzo, vipimo, na trajektoria za usanidi mbalimbali kwa kulinganisha:

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

Hii ni muhimu unapojaribu vidokezo, miundo mahususi kwa hatua, bajeti za uboreshaji, au chaguo kama mrejesho wa 3D na uzalishaji unaozingatia uunganishaji.

Tumia Procedura Studio

Studio ni kiolesura cha wavuti cha mtiririko huo huo. Hukuwezesha kuunda uendeshaji kwa kutumia kidokezo, picha ya marejeo ya hiari, mipangilio iliyowekwa awali, na vidhibiti vya kila hatua. Wakati wa utekelezaji, unaweza kutazama sehemu zikionekana na kukagua mpango, mabaki ya sehemu, historia ya uboreshaji, mesh ya mwisho ya 3D, vifaa, na uunganishaji.

cd web
bun install
bun run start

Fungua http://localhost:8080. Studio huanzisha CLI kutoka kwenye mzizi wa hifadhi na husoma .env hiyo hiyo, kwa hivyo haihitaji usanidi tofauti wa API.

Vidokezo vya Juu

1. Anza kwa gharama ndogo, kisha ongeza vipengele vya ubora. Thibitisha endpoint yako na kidokezo chako kwa uendeshaji wa kawaida wa maandishi pekee kabla ya kuwezesha uzalishaji wa picha, mrejesho wa kuona, upakaji rangi, au mwendo.
2. Tumia marejeo halisi inapowezekana. Mradi unabainisha --image kuwa uboreshaji mkubwa zaidi wa uaminifu wa matokeo.
3. Badilisha miundo kwa kila hatua. Tumia --agent-model, --scad-model, --paint-model, au --motion-model kuchagua funguo tofauti za miundo ya endpoint kwa hatua mahususi.
4. Hifadhi jiometri iliyofanikiwa. Endesha upakaji rangi na mwendo kama hatua tofauti za baada ya uchakataji wakati hitilafu hazipaswi kulazimisha ujenzi kamili upya.
5. Fuatilia kumbukumbu wakati wa uendeshaji sambamba. Blender na Isaac Sim zinaweza kutumia kumbukumbu kubwa hata wakati endpoint yako ya API inaweza kushughulikia maombi mengi zaidi kwa wakati mmoja.
6. Kagua trajektoria unapotatua hitilafu. Trajektoria ya JSONL na saraka za uboreshaji za kila hatua huonyesha vidokezo, majibu ya modeli, mabadiliko, matokeo ya mkusanyaji, na maamuzi ya lango.
7. Thibitisha usaidizi wa backend ya OpenSCAD. Ikiwa uzalishaji unaonekana kukwama, hakikisha Procedura inatumia OpenSCAD yenye uwezo wa Manifold badala ya toleo la zamani linalotumia CGAL pekee.

Hitimisho

Procedura huunganisha upangaji wa modeli ya lugha na CAD ya kiutaratibu, ukusanyaji wa mesh, uboreshaji wa kuona, vifaa, na uunganishaji wa hiari. Anza na endpoint iliyosanidiwa na kidokezo rahisi cha maandishi, kisha ongeza picha ya marejeo, mrejesho wa 3D, vipengele vya uunganishaji, upakaji rangi, na mwendo kadiri mahitaji yako ya ubora yanavyoongezeka. Kwa kuwa bidhaa kuu ni msimbo chanzo unaoweza kuhaririwa, vitu vinavyotokana hubaki vinaweza kukaguliwa na kutumiwa tena baada ya uzalishaji.

Procedura ina leseni ya MIT. Nyaraka za mradi, karatasi, na maelezo ya ziada yanapatikana kwenye ukurasa wa mradi wa Procedura.