주요 특징

• 출력이 메시 파일이 아니라 코드라는 점이 이 프로젝트의 출발점입니다. 참조 이미지를 넣으면 `createObjectNameModel(spec, options)` 형태의 TypeScript 팩토리가 나오고, 그 함수가 반환하는 `THREE.Group`의 `userData.sculptRuntime`에 노드·소켓·콜라이더·파괴 그룹이 노출됩니다. 캐릭터 빌드에서는 `userData.rig`에 본 목록, 하나로 공유되는 `Skeleton`, 본 순서와 인덱스 맵, 그리고 모든 스킨드 메시가 실제로 바인딩됐는지를 계산한 `bound` 플래그가 들어갑니다. 함께 나오는 `ObjectSculptSpec` JSON에는 컴포넌트 트리·머티리얼·반복 시스템·소켓과 패스별 리뷰 이력이 기록됩니다. 결과가 수 MB짜리 바이너리가 아니라 diff 가능한 텍스트라서 코드 리뷰와 버전 관리에 그대로 올라갑니다.
• 생성 과정은 한 번에 끝내지 않고 `blockout → structural → form → material → surface → lighting → interaction → optimization` 여덟 패스로 쪼갠 뒤, 패스마다 렌더와 참조 이미지를 나란히 붙인 비교 시트를 만들어 통과 여부를 판정하고 임계값을 넘을 때까지 자기 수정합니다. 코드 생성기는 현재 잠금 해제된 패스만 내보내므로 매 반복마다 모델 전체를 다시 읽거나 다시 만들지 않습니다. 코드 생성 전에는 `--strict-quality` 게이트가 얕은 스펙을 막고, 팩토리 생성기는 실패 시 `BLOCKED`과 함께 스펙 아티팩트·실패 지표·원인·다음 조치를 반환하며 파일을 쓰지 않는 fail-closed 방식입니다. `--allow-nonstrict`는 레거시 테스트 픽스처 전용으로만 남겨 뒀습니다.
• 토큰 비용을 설계 목표로 명시한 점이 차별점입니다. 검증·게이팅·스펙 작성·PBR 근거 추출·비교 시트 패키징·파이프라인 상태 관리는 전부 결정론적 Python 스크립트가 처리하고, 모델 토큰은 비교 시트 한 장을 보고 통과/실패를 판단하는 시각적 판단과 코드 작성에만 씁니다. 스크립트는 Python 3.10+ 표준 라이브러리만 쓰며 pip·PIL·numpy·Playwright가 필요 없고, PNG 읽기/쓰기까지 `struct`와 `zlib`로 직접 처리해 설치 자체가 없습니다. 리뷰는 스크린샷 여러 장이 아니라 패스당 정확히 한 장의 비교 시트로 이뤄집니다. `forge/`에는 약 90개 모듈이 들어 있고 게이트별 계약은 `grimoire/review/gates_reference.md`에 문서화돼 있습니다.
• 대상은 `object`·`character`·`hybrid`로 분류돼 각각 다른 트랙을 탑니다. 코드 생성에 앞서 광택, 베벨과 라운딩, 나사·리벳, 각인·페인트 라인워크, 컨투어, 얼룩과 마모 같은 정체성을 결정짓는 디테일을 `detailInventory`로 열거하고, 각 디테일이 실제 컴포넌트나 머티리얼 항목에 매핑돼야만 생성이 진행됩니다. 캐릭터는 머리 단위 비례·얼굴 랜드마크·포즈를 다루는 해부학 트랙으로 라우팅되고, 특정 인물이나 캐릭터를 최대한 닮게 만드는 옵션 경로는 파라메트릭 템플릿을 랜드마크에 맞춘 뒤 사진을 디라이팅하고 카메라를 정합해 참조를 메시에 투영합니다. 최소 두 장의 직교 실루엣을 교차시켜 유계 복셀 메시를 만드는 `visualHull` 옵션도 있으며, 보이지 않는 영역은 지어내지 않고 저신뢰로 기록합니다.
• 설치는 체크아웃을 스킬 디렉터리에 두는 것으로 끝나고(`~/.claude/skills/img2threejs`), 호스트가 여러 개면 심볼릭 링크로 한 체크아웃을 공유해 버전 드리프트를 막도록 안내합니다. 호스트에 종속되지 않아 네이티브 이미지 읽기, 브라우저 MCP, 프로젝트 프리뷰, 사용자가 준 스크린샷 중 무엇이든 그 자리에서 제공되는 수단을 씁니다. SAM2 마스크·Depth Anything V2·MediaPipe·Playwright 같은 외부 도구는 격리된 선택적 근거 계층으로만 붙고 패스를 승인하거나 지오메트리를 대신 만들지 못합니다. 한계도 문서에 명시돼 있습니다 — 이미지 한 장으로는 가려진 면이나 정확한 지오메트리를 보장할 수 없어 보이지 않는 면은 보이는 면을 미러링해 추론하며, 하드서피스 객체에는 강하지만 캐릭터는 포토리얼 유사성이 아닌 양식화된 재구성이고, "이 이미지로는 요구한 충실도에 도달할 수 없다"는 결론 자체를 정상 결과로 취급합니다.