img2threejs는 참조 이미지(Reference image)로부터 고품질의 애니메이션 준비가 완료된(animation-ready) Three.js 모델을 코드 기반으로 재구성하는 프로시저럴(procedural) 모델링 파이프라인입니다. 기존의 사진 측량(photogrammetry)이나 메쉬 추출(mesh extraction) 방식과 달리, 런타임에 실행 가능한 코드로 객체를 구현하여 효율성과 수정 가능성을 극대화합니다.

핵심 방법론 및 기술적 구조

이 프로젝트의 핵심은 '스크립트가 강화(enforce)하고 모델(AI)이 판단(judge)하는' 구조의 단계적 조각(staged sculpting) 파이프라인입니다.

1. 파이프라인 단계 (Build Passes):

모델은 정해진 순서에 따라 조각됩니다:
blockout → structural-pass → form-refinement → material-pass → surface-pass → lighting-pass → interaction-pass → optimization-pass.
각 단계는 이전 단계의 검증(통과) 없이는 진행되지 않으며, 매 단계마다 렌더링된 결과와 참조 이미지를 나란히 배치한 비교 시트(comparison sheet)를 통해 에이전트의 시각적 검토를 거칩니다.

2. 엄격한 품질 게이트 (Strict-Quality Gates):

단순 텍스처링에 의존하는 것을 방지하기 위해, 코드 생성 전 detailInventory(gloss, bevel, rivet, linework 등 식별 가능한 세부 요소 목록)를 작성해야 합니다. 또한, CS2(Counter-Strike 2) 무기 모델링의 경우, 가족별 구성 요소 계약(component contracts)과 같은 구조적 무결성 검증을 거쳐 실제 기하학적 구조를 준수하도록 강제합니다.

3. 결정론적 스크립트 기반 운영:

성능 최적화를 위해 모델의 토큰은 시각적 판단과 코드 작성에만 집중적으로 사용됩니다. Python 3.10+ 표준 라이브러리 기반의 스크립트가 다음 역할을 수행합니다:

• Intake & Assessment: probe_image.py로 기술적 문제를 식별하고, new_pre_spec_assessment.py로 객체의 클래스 및 복잡도를 평가합니다.
• Spec Generation: ObjectSculptSpec JSON을 통해 구성 요소, 재질, 소켓 등을 정의하며, validate_sculpt_spec.py가 불완전한 명세를 차단합니다.
• PBR Extraction: 재질의 물리 기반 렌더링(PBR) 데이터를 참조 이미지의 픽셀에서 추출하여 적용합니다.

4. 런타임 계층 구조 (Runtime Hierarchy):

생성된 결과물은 단순한 기하학적 덩어리가 아니라, root.userData.sculptRuntime을 통해 피벗(pivots), 소켓(sockets), 콜라이더(colliders)가 노출되는 계층 구조를 가집니다. 이는 애니메이션 및 상호작용이 즉시 가능한 상태를 보장합니다.

토큰 효율성 전략

• Fail-fast: 명세가 불충분할 경우 코드 생성 단계로 진입하지 않아 토큰 낭비를 방지합니다.
• Incremental Generation: 전체 모델을 재작성하는 대신, 잠금 해제된 특정 build pass에 대해서만 코드를 생성합니다.
• Script-driven: 복잡한 기하학적 검증, 파일 입출력, 상태 관리는 파이썬 스크립트가 처리하고, 모델은 시각적 결과물의 합격 여부($score >= threshold$)만 결정합니다.

향후 로드맵 및 확장

본 프로젝트는 v1.4~v1.5(에셋 업데이트)를 거쳐, v1.6~v1.7(환경 및 게임 파이프라인), v1.8~v1.9(애니메이션 및 AI 스튜디오), 최종적으로 v2.0(절차적 세계 생성)으로 나아가는 로드맵을 지향합니다. 이는 단순히 단일 객체 재구성을 넘어, 이미지로부터 플레이 가능한 월드를 생성하는 플랫폼으로의 발전을 목표로 합니다.