img2threejs/img2threejs

img2threejs – 단일 참조 이미지를 절차적 Three.js 코드로 변환

개요

• Python 기반 스킬로, 대규모 언어 모델 에이전트(Claude Code, Codex, OpenCode, Hermes 등)가 단일 사진에서 객체나 캐릭터를 TypeScript로 작성된 THREE.Group 팩토리로 재구성할 수 있습니다. 생성된 코드는 프리미티브, 절차적 셰이더 및 생성된 지오메트리만 사용하며 메시 파일이나 다운로드된 에셋은 포함하지 않습니다.

중요성

• 애니메이션 준비, 토큰 효율적인 3D 모델을 생성하여 Three.js 장면에 바로 삽입할 수 있습니다. 출력이 코드이므로 가볍고 버전 관리가 쉬우며 수정이 용이합니다.
• 품질 게이트 파이프라인을 갖추고 있어 모든 시각적 세부 사항을 열거하고, 재질 레지스트리와 검증하며, 시각적 판단이 필요한 부분에만 LLM 토큰을 사용합니다.

주요 기능

• 에이전트 비의존적 스킬 – 스킬을 실행할 수 있는 모든 LLM(Claude Code, Codex, OpenCode, Hermes)에서 작동합니다. 스킬은 에이전트의 스킬 저장소에 설치되고 간단한 프롬프트로 호출됩니다.
• 도메인 플러그인 – 특정 사용 사례(캐릭터 리깅, Counter-Strike 2 무기 스킨, 비공개 환경 플러그인 등)를 위한 선택적 확장 기능입니다. 플러그인은 추가 입력 계약, 리그 검사 및 검토 게이트를 추가합니다.
• 결정적 파이프라인 – 다단계 조각 흐름(blockout → structural → form → material → surface → lighting → interaction → optimization)으로 Python 스크립트가 게이트를 강제하고 저장된 상태에서 작업을 재개합니다.
• 라이브 데모 갤러리 – 공개 사이트(https://img2threejs.io)에서 수십 개의 재구성을 보여주며, 각 샘플에는 생성된 TypeScript 소스에 대한 링크가 포함되어 있습니다.
• 오픈소스 도구 – 핵심 스킬은 이 리포지토리에, 쇼케이스는 관련 리포지토리에 있으며, 플러그인은 img2 하네스를 통해 추가할 수 있는 별도의 패키지입니다.

설치

# 감지된 모든 에이전트에 스킬 설치
npx --yes img2threejs@latest install
# 에이전트별 설치 확인
npx --yes img2threejs@latest doctor

• Node ≥ 18, Git, Python ≥ 3.10이 필요합니다.
• Hermes 사용자는 README에 설명된 대로 스킬을 활성 프로필에 연결하세요.

선택적 플러그인 하네스

# 플러그인을 관리하는 하네스 설치
npx --yes @img2threejs/img2@latest install --yes
# 사용 가능한 플러그인 나열
img2 plugins
# 플러그인 추가 (예: 캐릭터 리깅)
img2 add character --yes

플러그인은 기본적으로 설치되지 않습니다. 필요한 것만 선택하세요.

재구성 실행

1. 설치 후 에이전트를 다시 시작합니다.
2. 에이전트 채팅에서 이미지를 첨부(또는 경로 제공)하고 다음과 같은 프롬프트를 발행합니다.

   /img2threejs Rebuild the object in ./reference.png as a procedural Three.js model.
   Keep its proportions, silhouette and colours. Follow the quality gates.
   

3. 에이전트는 다음을 수행합니다.
   • 이미지 검증.
   • 세부 인벤토리 및 사양 문서 구축.
   • TypeScript 팩토리를 패스별로 생성.
   • 숨겨진 Three.js 뷰에서 결과를 렌더링하고 참조와 비교.
   • 생성된 소스 파일, 렌더 검토 증거 및 신뢰 점수를 반환합니다.

출력

• src/model.ts(또는 유사한 이름) 파일로 THREE.Group 팩토리를 내보냅니다.
• 계층, 재질 및 신뢰 메트릭을 설명하는 JSON 사양.
• 시각적 검토 단계에 사용되는 렌더링된 스크린샷.

문서 및 리소스

• 아키텍처 및 게이트 설계: docs/ARCHITECTURE.md
• 설치 가이드: docs/INSTALL.md
• 플러그인 시스템: docs/PLUGINS.md
• 자체 플러그인 작성: WRITING_A_PLUGIN.md
• 라이브 데모 갤러리: https://img2threejs.io

라이선스

• Apache 2.0(LICENSE 참조).

대상 사용자

• 무거운 메시 파일을 배포하지 않고 가볍고 애니메이션 가능한 에셋이 필요한 게임 개발자.
• 코드 우선 3D 모델을 선호하는 인터랙티브 웹 경험 제작자.
• LLM 기반 3D 생성 파이프라인을 연구하는 연구자.
• 사진을 Three.js 코드로 변환하는 결정적이고 품질 관리된 방법을 원하는 모든 사람.