img2threejs: 이미지 한 장을 코드로 재구성하는 Three.js 3D 모델 생성 도구

9bow · 7월 26, 2026, 6:30오전

img2threejs 소개

이미지 한 장을 3D 모델로 바꾸는 접근은 보통 사진측량(photogrammetry) 이나 메시 추출, 혹은 미리 만들어진 에셋 팩을 내려받는 방식으로 이루어집니다. 이 방식들은 대용량 메시 파일을 만들어 내고, 결과물을 코드로 검토하거나 버전 관리하기 어렵습니다. AI 에이전트로 이 작업을 돌릴 때는 매 단계마다 모델 전체를 다시 읽고 픽셀을 점수 매기느라 토큰이 크게 소모되는 문제도 있습니다.

img2threejs는 이 문제를 코드에 의한 재구성(reconstruction-by-code) 으로 접근합니다. 참조 이미지 한 장을 주면, 그 객체를 기본 도형(primitive) 과 절차적 셰이더(procedural shader), 생성된 지오메트리로 다시 만든 TypeScript로 작성된 THREE.Group 팩토리를 산출합니다. 결과물에는 피벗, 소켓, 콜라이더 같은 런타임 계층이 포함되어 있어, 정적인 덩어리가 아니라 곧바로 애니메이션에 쓸 수 있는 모델이 됩니다.

img2threejs는 Claude Code, Codex, OpenCode 위에서 동작하는 에이전트 스킬 형태이며, 특정 에이전트에 종속되지 않습니다. 이미지 읽기, 브라우저 MCP, 프로젝트 미리보기, 사용자가 준 스크린샷 등 호스트가 제공하는 수단을 그대로 활용합니다. 아래는 참조 이미지 한 장을 코드로 재구성해 브라우저에서 돌아가는 3D 모델로 만든 예시입니다.

img2threejs가 참조 이미지(오른쪽)를 코드로 재구성한 3D 모델(왼쪽) 비교

img2threejs의 품질 게이트 파이프라인

img2threejs의 핵심은 단계별로 나뉜 조각(sculpting) 파이프라인입니다. 각 단계는 스크립트가 게이트를 강제하고, 통과 여부는 에이전트의 시각적 판단(agent vision) 이 결정합니다. 아래 그림은 전체 흐름을 정리한 것입니다.

참조 이미지가 들어오면 먼저 적합성 게이트로 3D 대상이 될 수 있는지 판단하고, 사양(spec) 을 작성합니다. 엄격 품질 게이트(strict-quality) 는 사양이 객체 복잡도에 비해 너무 얕으면 코드 생성 전에 되돌려 보냅니다. 이후 모델은 정해진 순서의 빌드 패스로 조각됩니다.

블록아웃 → 구조 → 형태 → 재질 → 표면 → 조명 → 상호작용 → 최적화

각 패스는 이전 패스가 검토·승인된 뒤에만 잠금이 풀립니다. 한 패스가 continue 로 넘어가려면 실제 렌더, 참조와 나란히 놓은 비교 시트, 그리고 임계값 이상의 에이전트 비전 점수가 모두 있어야 합니다. 점수가 임계값에 못 미치면 에이전트는 refine-spec(사양 교정) 이나 refine-code(코드 교정) 로 자기 교정을 수행합니다.

img2threejs가 토큰 효율적인 이유

img2threejs는 기계적인 작업을 결정적(deterministic) 스크립트로 밀어 넣고, 모델의 토큰은 판단이 필요한 곳에만 쓰도록 설계되었습니다. 검증, 게이트 처리, 사양 작성, PBR 추출, 비교 시트 패키징, 파이프라인 상태 관리는 모두 파이썬 스크립트가 담당하며, 이 스크립트들은 시각 점수를 매기지 않습니다. 모델의 토큰은 오직 하나, 나란히 놓인 비교 시트를 보고 통과/실패를 판단하는 데 쓰입니다.

이 스크립트들은 순수 파이썬 3.10+ 표준 라이브러리만 사용해, pip, PIL, numpy, Playwright 같은 의존성이 없습니다. PNG 읽기와 쓰기도 struct 와 zlib 로 처리합니다. 코드 생성기는 현재 잠금이 풀린 빌드 패스만 출력하므로, 매 반복마다 모델 전체를 다시 읽거나 재생성하지 않습니다. 결과물은 다중 메가바이트 메시 파일이 아니라 diff가 가능한 TypeScript와 JSON 사양이라, 검토하고 버전 관리하기에도 적합합니다.

img2threejs가 만들어 주는 결과물

ObjectSculptSpec JSON: 구성요소 트리, 재질, 반복 시스템, 소켓, 그리고 각 패스의 검토 이력을 담은 사양입니다.
TypeScript 팩토리: THREE.Group 을 반환하는 createObjectNameModel(spec, options) 함수로, root.userData.sculptRuntime 을 통해 노드, 소켓, 콜라이더, 파괴 그룹을 노출합니다.
렌더와 비교 시트: 각 패스의 충실도를 기록한 렌더 결과와 비교 시트입니다.

개발자는 이 도구의 한계도 분명히 밝히고 있습니다. 이미지 한 장으로는 보이지 않는 면이나 정확한 지오메트리를 보장할 수 없어, 결과가 근사적이거나 양식화(stylized) 되었을 때 이를 그대로 알린다고 설명합니다. 하드서피스(hard-surface) 객체에는 강하지만 캐릭터는 사진처럼 똑같은 재현이 아니라 양식화된 재구성이라는 점도 함께 언급합니다.

img2threejs 설치 및 사용법

img2threejs는 스킬 폴더를 스킬 디렉토리에 두는 방식으로 설치합니다.

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

Claude Code에서 객체 이미지를 첨부하거나 가리킨 뒤 스킬을 호출하면, 이미지를 검증하고 사양을 쓴 다음 패스별로 팩토리를 생성하며 매 단계 비교 결과를 보여줍니다.

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

스크립트는 스킬 루트에서 실행되며 파이썬 3.10 이상만 있으면 별도로 설치할 것이 없습니다.

img2threejs의 라이선스

img2threejs는 Apache 2.0 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

img2threejs 라이브 데모 갤러리

https://hoainho.github.io/img2threejs-showcase/

img2threejs 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~