TL;DR

이 레포는 단일 레퍼런스 이미지를 입력으로 받아 단계별 검증과 비교 시트 기반의 에이전트 채점을 통해 TypeScript로 된 Three.js 팩토리 코드를 생성하는 스킬이다. 핵심은 Python 표준 스크립트가 검증·게이팅·패키징을 담당하고 에이전트는 시각 판단에만 토큰을 소비하도록 설계된 패스 게이팅 파이프라인이다. 결과물은 런타임 계층을 노출하는 애니메이션 준비 THREE.Group 팩토리와 ObjectSculptSpec JSON으로 제공되어 배포와 리뷰가 용이하다. 단일 이미지 한계로 보이지 않는 면의 정확한 지오메트리는 보장하지 않으며 품질 부족 시 엄격한 게이트가 코드 생성을 차단한다.

주요 기능

• TypeScript 팩토리를 생성해 THREE.Group 형태의 런타임 계층과 root.userData.sculptRuntime을 노출하므로 소켓·피벗·콜라이더를 그대로 애니메이션에서 활용할 수 있다. 생성된 코드는 텍스트 차별화를 통해 버전 관리와 리뷰가 가능하며 메쉬 파일을 내려받을 필요가 없다. 런타임 구조가 명세와 직접 연결되어 후처리나 파이프라인 통합이 수월하다.
• 단계화된 조각(scultping) 파이프라인을 운영해 blockout에서 lighting-pass까지 순차적으로 빌드 패스를 잠금·해제한다. 각 패스는 실제 렌더와 비교 시트를 기반으로 에이전트가 채점한 결과로만 통과하며, 실패 시 명세 재정의 또는 코드 수정을 통해 셀프 코렉트를 진행한다. 이 구조는 낮은 품질의 사양에서 불필요한 코드 생성을 차단한다.
• 파이프라인 로직과 품질 게이트는 Python 3.10+ 순수 표준 라이브러리 스크립트가 담당하므로 외부 종속성 없이 실행 가능하다. PNG 입출력과 PBR 증거 추출이 struct 및 zlib 같은 표준 도구로 구현되어 설치·디버그 비용이 거의 없다. 스크립트는 검증·패키징·파이프라인 상태 관리를 자동화해 모델 토큰을 시각 판단에만 사용하도록 설계되었다.
• 비교 시트 기반의 단일 이미지 판정으로 각 패스에서 모델이 재처리해야 할 컨텍스트를 최소화하므로 에이전트 토큰 소비가 절감된다. 패스별로 생성 범위를 좁혀 현재 패스의 코드만 배출하므로 반복 비용이 낮다. 결과는 diff 가능한 텍스트(TypeScript)와 JSON 명세로 보관되므로 변경 추적과 리뷰가 용이하다.

어떻게 동작하는가

레퍼런스 이미지를 입력으로 받아 단계별로 스펙을 작성하고 각 패스마다 렌더와 비교 시트를 패키지해 에이전트가 시각 판단을 내리는 순차적 파이프라인이다. 검증·품질 게이트·PBR 추출·비교 시트 패키징 등은 Python 스크립트가 결정론적으로 처리하고, 에이전트는 오직 비교 시트를 보고 합격 여부를 판정하는 데 토큰을 사용한다. 코드 생성은 현재 잠금 해제된 단일 패스에 대해서만 이루어지며 결과는 TypeScript로 된 THREE.Group 팩토리로 출력되어 런타임 계층을 바로 활용할 수 있다.

해결 문제

단일 사진만으로 애니메이션 준비가 된 Three.js 모델을 얻기 위해 복잡한 포토그래메트리나 대용량 메쉬 파일을 제작할 필요를 없애는 문제를 해결한다. 파이프라인은 레퍼런스에서 식별한 주요 디테일을 명세로 구성해 품질이 충분하지 않으면 코드 생성을 차단함으로써 낭비되는 토큰과 작업을 줄인다. 결과물은 텍스트 기반 TypeScript 팩토리와 JSON 명세로 제공되어 버전 관리·검토·애니메이션 통합이 바로 가능한 상태로 배포된다.

지금 주목받는 이유

라이브 데모 갤러리와 v1.2.0의 기능(휴머노이드 트랙 포함) 공개로 레포가 실사용 예시와 함께 주목을 받고 있다.

차별점

• 순수 코드 기반 재구성으로 메쉬 파일 대신 TypeScript 팩토리만 배포하므로 용량과 배포 복잡도가 크게 낮다.
• 패스 게이팅 설계는 에이전트가 매번 전체 컨텍스트를 다시 읽지 않게 하여 토큰 비용과 반복 작업량을 줄이는 데 초점을 맞추었다.
• 파이프라인의 품질 게이트는 디테일 인벤토리와 비교 시트 점수를 기준으로 엄격하게 동작해 얕은 사양에서의 불필요한 코드 생성을 방지한다.

사용 사례

• 웹 기반 게임이나 인터랙티브 데모에서 빠르게 프로토타이핑용 하드서피스 자산을 코드로 생성해 애니메이션에 바로 연결할 수 있다. 레퍼런스 한 장으로 형태·베벨·재료를 재현해 소품 수준의 자산을 반복 생성할 때 개발 시간이 단축된다. TypeScript 팩토리는 런타임 계층을 노출하므로 게임 엔진의 소켓·파괴 그룹과 매끄럽게 연동된다.
• 디자인 검토용으로 아트 디렉터가 이미지 한 장을 제공하면 비교 시트 기반의 반복 리뷰로 빠르게 형태와 재질을 수렴할 수 있다. 각 패스에서 렌더를 비교해 시각적 판단을 내리므로 피드백 루프가 짧다. 텍스트 출력이므로 리뷰 주석과 변경 이력 관리가 쉽다.
• 웹용 제품 시연이나 UI 애니메이션에 필요한 경량 3D 컴포넌트를 절차적으로 생성해 바로 임베드할 수 있다. 메쉬 파일을 내려받지 않아 클라이언트 배포가 간단하며 Three.js 런타임에서 즉시 실행된다. 재질과 라이팅 패스가 분리되어 있어 스타일 변형이 용이하다.

시작하기

레포를 Claude 스킬 디렉터리에 클론하면 로컬에서 즉시 스크립트를 실행할 수 있다. 설치는 별도 패키지가 필요하지 않으며 Python 3.10+ 환경에서 제공된 forge 단계 스크립트를 차례로 실행하면 이미지 프로브에서 사양 작성, 검증, 현재 패스의 Three.js 팩토리 생성까지 진행된다. 라이브 데모는 호스트된 쇼케이스 링크에서 생성된 TypeScript 소스와 렌더를 직접 확인할 수 있다.

요구사항

• Python 3.10 이상 런타임이 필요하며 모든 스크립트는 표준 라이브러리로만 동작하므로 추가 pip 의존성이 없다. PNG 입출력과 압축 처리가 struct와 zlib로 구현되어 있어 환경에 별도 바이너리 설치가 필요하지 않다.
• Three.js 런타임을 로컬 또는 브라우저 환경에서 실행할 수 있어야 하며 생성된 TypeScript 팩토리는 Three.js와 호환되는 빌드 체인에서 사용 가능하다. 호환성은 README의 데모 소스와 호환되는 브라우저 환경에서 검증되었다.

이미지 분석