img2threejs/img2threejs

img2threejs – 단일 참조 이미지를 절차적 Three‑js 모델로 변환

What it is

• 대규모 언어 모델(Claude, Codex 등)이 사물이나 캐릭터의 단일 사진을 가져와, 프리미티브(primitives), 절차적 셰이더(procedural shaders) 및 생성된 지오메트리(geometry)만을 사용하여 동일한 것을 Three.js에서 구축하는 TypeScript code를 생성할 수 있게 해주는 스킬 스타일 라이브러리입니다. 결과물은 애니메이션 준비가 완료된 THREE.Group 팩토리이며, 메쉬 파일이나 다운로드가 필요 없습니다.

How it works

1. Intake – 이미지가 LLM(또는 모든 "agent‑vision" 도구)에 입력됩니다. 모델은 피사체(object, character, …)를 분류하고 정체성을 정의하는 특징(베벨, 나사, 마모, 색상 등)의 상세 인벤토리를 구축합니다.
2. Spec generation – 결정론적 Python 스크립트(forge/state.py)가 증거 체크리스트를 기록하고 지오메트리, 재질, 계층 구조를 설명하는 JSON spec을 생성합니다.
3. Code synthesis – LLM은 Three.js 프리미티브, 커스텀 셰이더 및 선택적으로 voxel-carved 실루엣을 사용하여 spec을 재현하는 TypeScript 팩토리를 생성합니다.
4. Vision‑review loop – 각 단계(blockout → structural → material → surface …)를 거친 후 렌더링된 결과가 참조 이미지와 비교됩니다. 누락된 세부 사항 블록이 충족될 때까지 프로세스가 진행됩니다.
5. Runtime output – 최종 코드는 브라우저에서 실행되며, 피벗(pivots), 소켓(sockets) 및 userData를 노출하여 모델을 즉시 애니메이션화할 수 있습니다.

Key features

• Token‑efficient: LLM 토큰은 시각적 판단과 코드 생성에만 소비됩니다. 무거운 작업은 결정론적 Python 검증이 수행합니다.
• Domain plugins: 플러그인 시스템(plugin‑cs2, plugin‑character, plugin‑img2glb, …)을 통해 특정 에셋 패밀리에 대한 특화된 체크리스트와 재구성 규칙을 추가할 수 있습니다.
• Quality gates: 모든 세부 사항은 실제 구성 요소에 매핑되어야 합니다. 파이프라인은 숨겨진 지오메트리를 "invent"하지 않습니다.
• Multi‑view silhouette carving (선택 사항) 여러 뷰가 제공될 때 voxel-based 헐(hull)을 위한 기능입니다.
• Live demo gallery: 공개 사이트에서 생성된 수십 개의 모델과 소스 코드 링크를 볼 수 있습니다.

Typical use‑cases

• 컨셉 아트로부터 가볍고 애니메이션 준비가 완료된 Three.js 모델이 필요한 게임 에셋 파이프라인.
• 무거운 메쉬를 내보내지 않고 3D UI 요소나 제품 시각화를 빠르게 프로토타이핑하는 경우.
• 절차적 지오메트리가 실제 사물을 어떻게 근사화할 수 있는지 보여주는 교육용 데모.
• AI 에이전트(Claude Code, Codex, OpenCode)에 "이 사물을 재구성하라"는 기능을 확장하는 경우.

Getting started

# Clone the skill into your Claude/Codex skills directory
git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs

# (Optional) Install the plugin harness and domain plugins
npx github:img2threejs/img2 install          # creates ~/.img2 and the `img2` launcher
img2 add img2threejs/plugin-cs2               # CS2 weapon‑skin rules
img2 add img2threejs/plugin-character         # animated‑character pipeline

Running the skill (Claude Code 또는 스킬을 호출할 수 있는 모든 LLM 내부에서):

/img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.

스킬은 다음과 같이 작동합니다:

1. 첨부된 이미지를 분석하고,
2. 단계별 spec을 생성하며,
3. TypeScript 팩토리를 생성하고,
4. 원본 참조와 나란히 실시간 미리보기를 보여줍니다.

Advanced control – 프롬프트에 명결한 제약 조건을 임베딩하여 게이트를 제어할 수 있습니다. 예:

/img2threejs Rebuild the subject in this image as a procedural Three.js model.
Fidelity   Hold proportions and silhouette, enumerate bevels, seams, fasteners, wear.
Materials  Derive finish and gradient stops from the pixels, flag colours that won’t tone‑map.

Runtime    Expose pivots and sockets for moving parts.

각 라인은 파이프라인의 실제 검증 게이트에 매핑됩니다.

Where to see it

• Live demo gallery: https://img2threejs.io/ (각 데모는 생성된 소스에 링크됩니다).
• Showcase repo: https://github.com/img2threejs/img2threejs-showcase.
• Architecture details: docs/ARCHITECTURE.md in the repository.

License & community

• Apache 2.0.
• Contributions welcome (see CONTRIBUTING.md).
• Sponsored by Atlas Cloud, Tripo, Hyper3D, and a Ko-fi page.

---

In short, img2threejs is an AI‑augmented pipeline that turns a single picture into clean, animation‑ready Three.js code, with a strong focus on deterministic validation and and extensible domain plugins.