Procedura란?
Procedura는 텍스트 프롬프트를 편집 가능한 절차적 조립체로 변환하는 에이전트 기반 3D 모델링 파이프라인입니다. 점군이나 삼각형 메시만 생성하는 대신, 이름이 지정된 부품이 타입이 지정된 메이트로 연결된 매개변수 기반 OpenSCAD 프로그램을 작성합니다. 소스 코드를 확인하고 편집한 뒤 다시 컴파일할 수 있습니다.
이 시스템은 동결된 대규모 언어 모델을 사용하며 특수한 3D 학습이 필요하지 않습니다. 텍스트만으로 실행을 시작하거나, 기존 참조 이미지를 재구성하거나, 별도로 구성된 이미지 모델을 통해 참조 이미지를 생성할 수 있습니다.
Procedura는 --paint를 사용해 부품별 PBR 재질을 지정할 수 있으며, --motion 및 --motion-urdf를 사용해 관절이 있는 객체를 OpenUSD 및 URDF로 내보낼 수 있습니다.
주요 기능
- 편집 가능한 절차적 출력: 컴파일된 형상과 함께 OpenSCAD 소스 코드를 생성합니다.
- 부품별 생성: 객체를 계획하고 이름이 지정된 구성 요소를 점진적으로 제작합니다.
- 참조 이미지 재구성: 기존 이미지를 입력으로 받아 완성도를 크게 높일 수 있습니다.
- 3D 피드백: 새 부품을 생성하기 전에 현재 빌드를 렌더링할 수 있습니다.
- 조립 인식 모델링: 공칭 치수를 공유하는 핀, 소켓, 볼트 패턴, 스냅과 같은 결합 기능을 지원합니다.
- 반복적 개선: 렌더링, 비평, 패치, 게이트 사이클을 사용해 초안을 개선합니다.
- 재질: 비전 기반 단계를 통해 부품별 색상, 금속성, 거칠기를 지정할 수 있습니다.
- 관절 동작: 동작을 계획하고 OpenUSD 및 URDF 파일을 내보내며, 선택적으로 NVIDIA Isaac Sim에서 물리 검증을 수행할 수 있습니다.
- 추적 가능한 실행: 프롬프트, 응답, 도구 호출, 게이트 결정, 중간 렌더링, 편집 내용을 저장합니다.
- Web Studio: 실행을 구성하고 결과물을 확인할 수 있는 브라우저 인터페이스를 제공합니다.
사전 요구 사항 및 설치
저장소를 복제한 후 종속 항목 설치 프로그램을 실행합니다.
git clone git@github.com:SpatiaOS/Procedura.git
cd Procedura
bash scripts/install-deps.sh설치 프로그램은 Bun 1.3 이상, 프로젝트 패키지, Manifold를 지원하는 OpenSCAD 스냅샷, Blender, 그리고 초기 .env 파일을 설정합니다. 기본적으로 Bun은 ~/.bun 아래에, OpenSCAD는 ~/opt/openscad 아래에, Blender는 ~/opt/blender/ 아래에 설치됩니다.
이 스크립트는 반복해서 실행해도 안전합니다. 이미 정상적으로 작동하는 구성 요소는 그대로 둡니다. 선택적 모드를 사용해 종속 항목을 확인하거나 Blender를 건너뛰거나 다른 설치 접두사를 선택할 수 있습니다.
bash scripts/install-deps.sh --check
bash scripts/install-deps.sh --no-blender
PREFIX=/opt bash scripts/install-deps.sh--check는 아무것도 설치하지 않고 누락된 요구 사항을 보고합니다. --no-blender는 약 350 MB 크기의 Blender 다운로드를 건너뛰지만, 여러 렌더링 및 피드백 기능에는 Blender가 필요합니다.
OpenSCAD는 Manifold 백엔드를 지원해야 합니다. 오래된 배포판 패키지는 CGAL로 대체되어 처리 속도가 수십 배 느려질 수 있습니다. Procedura는 시작할 때
--backend를 확인하며 일반적으로 호환되지 않는 빌드의 사용을 거부합니다. 해당 속도 저하를 의도적으로 감수하는 경우에만PROCEDURA_ALLOW_CGAL_OPENSCAD=1을 설정하세요.
설치 프로그램은 NVIDIA Isaac Sim을 설치하지 않습니다. Isaac Sim은 동작 워크플로와 관련된 물리 검증에만 필요하며, 나머지 Procedura 기능은 Isaac Sim 없이 작동합니다. 또한 설치 프로그램은 기존 .env 파일을 보존합니다.
LLM 엔드포인트 구성
Procedura에는 API 키나 호스팅된 추론 백엔드가 포함되어 있지 않습니다. 생성된 .env 파일을 열고 엔드포인트와 키를 입력합니다.
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
PROCEDURA_MODEL=gpt-5.2엔드포인트는 서버 전송 이벤트를 사용해 POST {base}/chat/completions를 지원해야 합니다. 호환 가능한 선택지로는 OpenAI API, OpenRouter, 기업용 게이트웨이, vLLM, Ollama 또는 LM Studio 기반 로컬 서버가 있습니다.
모델 선택은 문자열이므로 구성된 엔드포인트가 제공하는 모든 모델 식별자를 사용할 수 있습니다. 검증된 프리셋과 모델 확인 규칙은 src/config/models.ts에 문서화되어 있습니다.
네이티브 Gemini 전송 사용
네이티브 GenAI 경로를 통해 Gemini를 사용하려면 GEMINI_API_KEY와 GEMINI_BASE_URL을 설정한 다음 모델 식별자 앞에 gemini:를 붙입니다.
PROCEDURA_MODEL=gemini:gemini-3-pro-preview이 경로에서는 thinkingConfig와 일급 사고 파트 같은 네이티브 기능을 사용할 수 있습니다.
선택적 이미지 생성
Procedura는 이미지 API를 명시적으로 구성하거나 요청한 경우에만 호출합니다. 생성된 참조 이미지를 활성화하려면 이미지 모델을 추가합니다.
PROCEDURA_IMAGE_MODEL=gpt-image-1이미지 모델은 OPENAI_BASE_URL과 OPENAI_API_KEY를 재사용합니다. --image 또는 구성된 이미지 모델이 없으면 실행은 텍스트 전용으로 유지되며 이미지 생성 비용이 조용히 발생하지 않습니다.
첫 모델 만들기
출력 디렉터리는 필수입니다. -o 또는 --output으로 출력 디렉터리를 지정한 다음 텍스트 프롬프트를 입력합니다.
bun run scripts/procedura.ts -o outputs/daybed \
--prompt "a brutalist brass daybed with tapered legs"이 기본 워크플로는 구성 요소를 계획하고, 하나씩 빌드한 다음, 전체 형상을 다듬습니다. 텍스트만 사용하며 이미지 API를 사용하지 않고, 부품별 초안 루프에 Blender를 포함하지 않습니다. 유용한 구성 중 비용이 가장 낮습니다.
지원되는 모든 옵션을 확인하려면 다음을 실행하세요.
bun run scripts/procedura.ts --help참조 이미지로 충실도 향상
참조 이미지를 제공하는 것은 프로젝트에서 확인된 단일 개선 요소 중 충실도를 가장 크게 향상시킵니다. 이미 가지고 있는 이미지와 설명형 프롬프트를 함께 전달하세요.
bun run scripts/procedura.ts -o outputs/daybed \
--image ref.png \
--prompt "a brass daybed with tapered legs"또는 이미지 모델의 이름을 지정하여 이번 실행 중에 참조 이미지를 생성할 수 있습니다.
bun run scripts/procedura.ts -o outputs/daybed \
--image-model gpt-image-1 \
--prompt "a brass daybed with tapered legs"셸에서 인용하기 불편한 긴 설명은 프롬프트를 파일에 저장하세요.
bun run scripts/procedura.ts -o outputs/daybed \
--prompt-file my_prompt.txt전체 품질 파이프라인 실행
전체 실행에서는 참조 이미지 재구성, 시각적 피드백, 조립 기능, 재질, 동작 및 더 긴 개선 예산을 결합할 수 있습니다. 대규모 계획에는 더 긴 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 "a two-finger parallel robot gripper"각 옵션은 서로 다른 역할을 합니다.
--3d-feedback는 각 부품을 만들기 전에 현재 조립 상태의 렌더링 뷰를 생성기에 제공합니다. 부품마다 Blender 패스가 하나씩 추가됩니다.--assembly는 겹치는 형상에만 의존하지 않고 실제 결합 인터페이스를 추가합니다.--paint는 비전 호출을 사용하여 이름이 지정된 부품에 PBR 재질 속성을 할당합니다.--motion은 관절 동작을 계획하고 OpenUSD 데이터를 내보냅니다.--motion-urdf는 URDF 파일과 링크별 메시도 추가로 생성합니다.--max-steps 12는 최대 12회의 개선 주기를 허용합니다. 각 주기에서는 렌더링, 비평, 패치 및 게이트 작업을 수행하며 LLM 호출을 2회 사용합니다.
계획 호출이 오래 걸린다는 것은 파이프라인이 실질적인 작업을 수행하고 있다는 의미일 수 있습니다. README에서는 PROCEDURA_MAX_PARTS를 제한하기보다 타임아웃을 늘릴 것을 권장합니다. 부품 수를 제한하면 속도를 얻는 대신 모델 품질이 낮아지기 때문입니다.
개선 재개, 초안 재작성 또는 개선 건너뛰기
Procedura는 기존 출력 디렉터리에서 개선 루프를 계속 진행할 수 있습니다. 프롬프트를 생략하고 새로운 단계 예산을 지정하세요.
bun run scripts/procedura.ts -o outputs/daybed --max-steps 12기존 초안을 폐기하고 다시 만들려면 --redo를 추가하세요.
bun run scripts/procedura.ts -o outputs/daybed \
--prompt "a brutalist brass daybed" \
--redo초안만 필요할 때는 --no-refine을 사용하세요. Procedura는 해당 초안을 최종 출력 파일로 승격합니다. 이전 모놀리식 워크플로에서는 --one-shot이 계획 단계 없이 한 번의 생성 호출을 수행하며, 참조 이미지가 필요합니다.
bun run scripts/procedura.ts -o outputs/daybed \
--one-shot \
--image ref.png \
--prompt "a brutalist brass daybed"출력 디렉터리 이해하기
완료된 실행에는 다음 아티팩트가 포함될 수 있습니다.
image.png: 제공했거나 생성된 참조 이미지입니다.plan.json: 계획된 부품 구조입니다._parts/NN_name/: 점진적 생성을 위한 부품별 아티팩트입니다.draft.scad및draft.obj: 초기 절차적 소스와 컴파일된 메시입니다.final.scad및final.obj: 개선된 결과물입니다.final_summary.txt: 최종 판정과 제공된 연결성 정보입니다.preview_final/: 최종 메시를 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: 프롬프트, 응답, 도구 호출 및 게이트 결정입니다._refine_steps/step_NNN/: 각 개선 주기의 렌더링, 진단, 편집 및 컴파일 데이터입니다.
Procedura가 작성하는 모든 OBJ 파일은 단위 바운딩 박스로 정규화됩니다. 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을 사용할 수 없거나 내보낸 관절 동작 파일만 필요한 경우 유용합니다.
데이터 세트 처리
여러 사례를 처리하려면 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를 사용할 때는 병렬 실행 수를 2개 안팎으로 유지하세요. 헤드리스 Isaac Sim 인스턴스를 여러 개 실행하면 GPU 메모리가 고갈될 수 있습니다. 정제만 수행하는 배치는 약 8~12개의 워커를 허용할 수 있지만, 각 사이클마다 Blender가 실행되므로 API 속도 제한보다 메모리가 먼저 제한 요소가 될 수 있습니다.
실행 결과물 비교
Procedura에는 여러 구성의 렌더링 결과, 소스 파일, 메트릭, 궤적을 나란히 확인할 수 있는 로컬 결과 서버가 포함되어 있습니다.
bun run scripts/results-server.ts \
--root a=outputs/run_a \
--root b=outputs/run_b프롬프트, 단계별 모델, 정제 예산 또는 3D 피드백과 조립 인식 생성 같은 옵션을 테스트할 때 유용합니다.
Procedura Studio 사용
Studio는 동일한 파이프라인을 위한 웹 프런트엔드입니다. 프롬프트, 선택적 참조 이미지, 프리셋, 단계별 제어 항목으로 실행을 구성할 수 있습니다. 실행 중에는 부품이 생성되는 과정을 확인하고, 계획, 부품 결과물, 정제 기록, 최종 3D 메시, 재질, 관절 구조를 살펴볼 수 있습니다.
cd web
bun install
bun run starthttp://localhost:8080을 엽니다. Studio는 저장소 루트에서 CLI를 시작하고 동일한 .env를 읽으므로 별도의 API 설정이 필요하지 않습니다.
고급 팁
- 저렴하게 시작한 다음 품질 기능을 추가하세요. 이미지 생성, 시각적 피드백, 페인팅 또는 모션을 활성화하기 전에 기본 텍스트 전용 실행으로 엔드포인트와 프롬프트를 검증하세요.
- 가능하면 실제 참조 이미지를 사용하세요. 프로젝트에서는
--image를 단일 요소로는 가장 큰 충실도 향상 효과를 제공하는 옵션으로 설명합니다. - 단계별로 모델을 재정의하세요.
--agent-model,--scad-model,--paint-model또는--motion-model을 사용해 개별 단계마다 서로 다른 엔드포인트 모델 키를 선택할 수 있습니다. - 성공한 형상을 보존하세요. 실패로 인해 전체 재생성이 필요하지 않도록 페인팅과 모션을 별도의 후처리 단계로 실행하세요.
- 병렬 실행 중 메모리를 모니터링하세요. API 엔드포인트가 더 많은 동시 요청을 처리할 수 있더라도 Blender와 Isaac Sim은 상당한 메모리를 사용할 수 있습니다.
- 디버깅할 때 궤적을 확인하세요. JSONL 궤적과 단계별 정제 디렉터리에서 프롬프트, 모델 응답, 편집 내용, 컴파일러 결과, 게이트 결정을 확인할 수 있습니다.
- OpenSCAD 백엔드 지원을 확인하세요. 생성이 멈춘 것처럼 보이면 Procedura가 오래된 CGAL 전용 빌드가 아니라 Manifold를 지원하는 OpenSCAD를 사용하고 있는지 확인하세요.
결론
Procedura는 언어 모델 기반 계획을 절차적 CAD, 메시 컴파일, 시각적 정제, 재질, 선택적 관절 구조와 결합합니다. 설정된 엔드포인트와 간단한 텍스트 프롬프트로 시작한 다음, 품질 요구 사항이 높아짐에 따라 참조 이미지, 3D 피드백, 조립 기능, 페인팅, 모션을 추가하세요. 주요 결과물이 편집 가능한 소스 코드이므로 생성된 객체는 생성 후에도 계속 검사하고 재사용할 수 있습니다.
Procedura는 MIT 라이선스로 제공됩니다. 프로젝트 문서, 논문 및 추가 세부 정보는 Procedura 프로젝트 페이지에서 확인할 수 있습니다.