img2threejs로 이미지를 Three.js 코드 모델로 바꾸기

개요

이미지 한 장에서 3D 결과물을 만들 때, 메시 파일 하나를 받는 것만으로는 부족할 때가 있습니다. 회전축과 부품 계층을 코드에서 다뤄야 애니메이션이나 상호작용에도 다시 쓸 수 있습니다.

img2threejs는 참조 이미지 속 물체를 THREE.Group 기반 TypeScript 팩토리로 다시 만드는 에이전트용 스킬입니다. 프리미티브, 절차적 셰이더, 생성 지오메트리로 구성하고 피벗·소켓·충돌체를 런타임 계층에 남깁니다. 결과가 바이너리 메시가 아니라 코드라서 Git diff와 코드 리뷰 흐름에 넣기 편합니다.

전체 구성 흐름

입력 이미지 검사: 대상 종류와 복잡도를 먼저 판정합니다.

명세 작성: 부품, 재질, 소켓을 ObjectSculptSpec에 기록합니다.

단계별 생성: blockout부터 optimization-pass까지 이전 검토가 끝난 단계만 생성합니다.

비교 검토: 참조 이미지와 렌더 결과를 한 장의 비교 시트로 묶어 다음 단계를 결정합니다.

1. 사용 가치

제 기준으로는 이미지에서 3D 에셋을 빨리 확보하는 일보다, 다음 수정까지 가능한 코드를 남겨야 할 때 검토할 도구입니다. GPT나 Claude의 일반 대화만으로 Three.js 코드를 만들면 부품 이름, 재질, 검토 기준이 매번 달라지기 쉽습니다. img2threejs는 스크립트가 명세 검증과 단계 상태를 맡고, 에이전트는 렌더 비교 판단에 집중하게 만듭니다.

README는 단일 이미지가 숨은 면이나 정확한 형상을 알 수 없다고 밝힙니다. 사람 얼굴과 캐릭터는 양식화된 재구성 경로이며, 사실적인 닮은꼴을 보장하지 않습니다. 한 장의 이미지만으로 정확한 메시를 얻는 도구로 기대하면 안 됩니다.

사전 준비 사항

• Claude Code, Codex, OpenCode 중 이미지와 브라우저 또는 미리보기 도구를 쓸 수 있는 에이전트
• Python 3.10 이상. README의 스크립트는 표준 라이브러리만 사용합니다.
• 재구성할 물체 이미지와 Three.js 프로젝트 경로

앞선 AI Engineering from Scratch 학습 글처럼 에이전트가 코드와 검토를 나눠 맡는 흐름을 이해하고 있으면 단계별 산출물을 읽기 좋습니다.

설치 절차

Claude Code 스킬 폴더에 저장소를 복제합니다. 다른 호스트는 해당 도구의 스킬 경로에 같은 폴더를 두시면 됩니다.

git clone https://github.com/hoainho/img2threejs.git ~/.claude/skills/img2threejs

설치 뒤 이미지와 함께 /img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.를 실행합니다. 스킬은 이미지 적합성 검사, 사전 명세, 코드 생성, 브라우저 렌더, 비교 검토 순서로 진행합니다.

1. 사용 방법

초기 명세만 확인하려면 아래 명령을 사용합니다. <image>에는 로컬 이미지 파일을 넣고 assessment.json 결과를 먼저 확인해주시면 됩니다.

cd ~/.claude/skills/img2threejs
python3 forge/stage1_intake/probe_image.py <image>
python3 forge/stage2_spec/new_pre_spec_assessment.py "ObjectName" --image <image> --out assessment.json
python3 forge/stage2_spec/new_sculpt_spec.py "ObjectName" --image <image> --assessment assessment.json --out spec.json
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality

--strict-quality 검사를 통과한 뒤에만 generate_threejs_factory.py로 TypeScript 팩토리를 만듭니다. 렌더 비교가 부족하면 현재 단계를 다시 다듬고, 통과한 단계만 다음 패스로 넘기시면 됩니다.

적용 대상

• 맞는 경우: 제품, 소품, 로봇처럼 부품 구조와 애니메이션 연결이 필요한 Three.js 에셋
• 비교 기준: 메시 파일을 바로 얻어야 하면 이미지-메시 생성 서비스가 경로가 더 짧습니다. 코드 리뷰와 런타임 제어가 우선이면 img2threejs 쪽이 맞습니다.
• 맞지 않는 경우: 사진과 같은 인물 재현, 보이지 않는 면까지 정확한 형상이 필요한 작업, 수동 모델링을 대체하려는 작업

확인

생성된 src/createObjectModel.ts에서 THREE.Group 팩토리와 root.userData.sculptRuntime 계층을 확인합니다. 브라우저 미리보기에서 비교 시트와 렌더가 함께 나오고 현재 패스가 통과 상태면 다음 생성 단계를 진행하시면 됩니다.