img2threejs

참조 이미지를 메시가 아니라 절차적 Three.js 코드로 되살리는 에이전트 스킬

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

참조 이미지 한 장을 받아 그 사물을 코드만으로 재구성하는 에이전트 스킬입니다. 사진 측량이나 메시 추출, 내려받은 에셋을 쓰지 않고 기본 도형과 절차적 셰이더, 생성된 지오메트리로 TypeScript Three.js 팩토리를 만듭니다. 피벗과 소켓, 충돌체를 갖춘 런타임 계층까지 함께 나와 바로 애니메이션을 붙일 수 있습니다. Claude Code 와 Codex, OpenCode 에서 돕니다.

판단

이럴 때 씁니다

참조 이미지의 사물을 웹에서 바로 도는 3D 모델로 옮기되 에셋 파일을 늘리고 싶지 않을 때
만들어진 결과에 곧바로 애니메이션을 붙여야 할 때. 피벗과 소켓이 함께 나옵니다
생성 결과를 사람이 읽고 고칠 수 있는 코드로 받고 싶을 때
여러 각도의 이미지를 모아 보이지 않는 면을 추정 대신 낮은 신뢰도로 남기고 싶을 때

이럴 땐 쓰지 마세요

사진 측량 수준의 실측 정확도가 필요할 때. 목적 자체가 다릅니다
이미지 한 장으로 특정 인물의 100퍼센트 닮음이 보장돼야 할 때. 저장소가 보장할 수 없다고 직접 밝힙니다
에이전트 없이 자동 변환 파이프라인만 돌리려 할 때
beta 표기를 감수할 수 없는 작업일 때

차별점

메시 파일이 아니라 코드를 만듭니다. 결과를 사람이 읽고 고칠 수 있고 내려받을 에셋이 없습니다.
정체성을 이루는 세부 목록을 먼저 세우고 그것이 완성되기 전에는 생성을 막는 게이트가 있습니다.
결정적인 파이썬 스크립트가 검증과 게이트를 맡고 모델 토큰은 시각 판단과 코드에만 씁니다.
단계마다 만들고 보고 고치는 구조라 마지막에 한 번 판정하지 않습니다.
특정 에이전트에 묶이지 않습니다. 호스트가 제공하는 시각 도구를 그대로 씁니다.

워크플로

01저장소를 스킬 디렉터리에 클론합니다. 호스트를 여러 개 쓴다면 체크아웃 하나를 두고 각 진입점을 심볼릭 링크로 걸어 어긋나지 않게 합니다.
02대상 이미지를 붙이거나 가리켜 스킬을 부릅니다.
03파이프라인이 먼저 사물을 사물과 캐릭터, 혼합 중 하나로 분류하고 정체성을 이루는 세부 목록을 만듭니다. 이 목록이 완성되기 전에는 코드 생성이 막힙니다.
04블록아웃부터 구조, 형상, 재질, 표면, 조명, 상호작용, 최적화까지 단계마다 코드를 만들고 시각 검토로 스스로 고칩니다.
05필요하면 여러 각도의 실루엣을 교차해 부피를 깎는 선택 경로나 인물 닮음을 높이는 투영 경로를 켭니다.

주요 명령

명령	설명
`git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs`	스킬 디렉터리에 설치합니다. Codex 는 ~/.codex/skills 아래에 링크로 겁니다.
`forge/next.py --state`	기록된 점검 목록에서 중단한 지점부터 다시 이어 갑니다.
`forge/state.py`	일반과 캐릭터, CS2 프로파일별로 근거가 붙은 순서 있는 점검 목록을 기록합니다.

함정

설치 전에 확인하세요

v1.5 는 스크립트만의 베타입니다. 개별 사물의 튜닝 산출물은 저장소에서 빠지고 무시 목록에 들어갔습니다. 빌드의 입력이 아니라 튜닝 세션의 출력이기 때문입니다.
README 배지의 버전 표기가 실제 태그보다 낮습니다. 릴리스 탭을 기준으로 보는 편이 정확합니다.
이미지 한 장으로는 특정 인물의 완전한 닮음을 보장할 수 없습니다. 파이프라인이 영역별 신뢰도를 보고하고 필요하면 추가 각도를 요구합니다.
보이지 않는 영역을 지어내지 않고 낮은 신뢰도로 기록합니다. 결과물에 빈 곳이 남을 수 있다는 뜻입니다.
에이전트의 시각 판단에 의존하므로 호스트가 이미지 읽기나 브라우저 도구를 제공해야 합니다.

검토 메모

공식 문서·릴리스·공개 자료를 바탕으로 정리한 편집 메모입니다.

저는 이 프로젝트의 핵심이 3D 생성이 아니라 산출물의 형태를 코드로 정한 결정이라고 봅니다. 메시 파일로 나오면 결과가 마음에 안 들 때 다시 만드는 것 말고 할 수 있는 일이 거의 없습니다. 코드로 나오면 읽고 고치고 버전 관리에 넣을 수 있고, 웹에 올릴 때 내려받을 에셋이 없습니다. 이 성질이 맞는 용도라면 정확도 손해를 감수할 이유가 충분합니다.

파이프라인 설계에서 인상적인 부분은 세부 목록 게이트입니다. 정체성을 이루는 작은 특징을 먼저 열거하게 하고 그 목록이 완성되기 전에는 코드 생성 자체를 막습니다. 생성 결과가 그럴듯해 보이지만 정작 그 물건답게 만드는 요소가 빠지는 실패를 앞에서 잡겠다는 뜻으로 읽힙니다. 결정적인 스크립트가 검증을 맡고 모델은 시각 판단에만 토큰을 쓰게 나눈 것도 같은 계열의 절약입니다.

기대치는 저장소가 적은 대로 잡으시기 바랍니다. 이미지 한 장으로 특정 인물의 완전한 닮음은 보장할 수 없다고 스스로 밝혔고, 보이지 않는 면은 지어내는 대신 낮은 신뢰도로 남깁니다. 저는 이 정직함을 신뢰 신호로 봅니다. 다만 v1.5 가 스크립트만의 베타이고 README 배지 버전이 실제 태그보다 낮게 적혀 있으니, 무엇이 최신인지는 릴리스 탭에서 확인하고 들어가시는 편이 좋습니다.

운영 면에서 눈에 띄는 배려는 중단한 지점에서 다시 이어 갈 수 있게 해 둔 부분입니다. 단계마다 만들고 보고 고치는 구조라 한 사물을 끝내는 데 시간이 걸리는데, 근거가 붙은 순서 있는 점검 목록을 파일로 기록해 두고 그 지점부터 재개합니다. 여러 세션에 걸쳐 붙잡고 있어야 하는 작업에서 이 장치가 없으면 처음부터 다시 도는 일이 생깁니다. 토큰을 시각 판단에만 쓰도록 설계했다는 설명과 같은 방향의 절약이라고 봅니다.

비교

이미지에서 3D 를 만드는 도구가 대개 메시를 생성하거나 사진 측량으로 형상을 복원한다면, 이쪽은 같은 목표를 코드 생성으로 풉니다. 결과가 텍스트라 버전 관리와 수정이 되고 용량이 거의 없는 대신, 실측 정확도를 겨루는 용도로는 맞지 않습니다.

최근 변경

v1.5.1에서는 참조 GLB를 1:1 측정 기준으로 삼는 3단계 재구성 파이프라인 glb_character_pipeline을 옵트인으로 추가했고, 참조가 없을 때는 GLB 의존 단계를 건너뛰고 파라메트릭 경로만 쓰도록 했습니다. SDF quad 패스의 경계 값 오류와 configs/example.env의 x2·x3 티어 매핑이 뒤바뀌어 있던 문제를 바로잡았습니다.

공식 변경 내역