hoainho/img2threejs 딥다이브
— 참조 이미지를 메시가 아니라 코드로 다시 짓는 절차적 Three.js 생성기

1프로젝트 한 줄 요약

이미지 한 장을 3D로 바꾸는 도구는 이미 많다. 대부분은 신경망(neural network)이 사진을 삼켜 메시(mesh) — 수천~수십만 개의 삼각형 덩어리 — 를 통째로 토해낸다. 결과는 그럴듯해 보이지만, 열어보면 정체를 알 수 없는 폴리곤 수프다. 어느 삼각형이 손잡이인지 바퀴인지 코드가 알지 못하고, 애니메이션을 붙이려면 사람이 처음부터 뼈대를 다시 심어야 한다.

img2threejs가 하는 일은 명확하다. 참조 이미지를 받아 → 물체를 뜯어보고(intake) → 부품·재질·관절 설계도를 JSON으로 쓰고(spec) → 그 설계도로 Three.js 코드를 생성하고(build) → 렌더한 뒤 원본과 비교해 채점하고(review) → 점수가 모자라면 다시 설계도/코드를 고쳐 이 과정을 반복한다. 핵심은 "AI가 알아서 잘하겠지"에 맡기지 않고, 기계적으로 측정 가능한 관문을 매 단계에 세워둔 것이다.

이름은 img2threejs(image → three.js)이지만, 진짜 핵심어는 "reconstruction-by-code(코드에 의한 재구성)"다. 사진측량(photogrammetry)도, 메시 추출도, 아트 에셋 다운로드도 아니다. 사람이 읽고 고칠 수 있는 코드로 물체를 짓는다는 점이 이 도구의 정체성이자, 이 문서에서 배울 것의 전부를 관통하는 열쇠다.

2왜 주목받는가

2026년, "이미지 넣으면 3D 나옴" 서비스는 흔하다(Meshy, Tripo, Rodin 등). 그런데 다들 같은 약점을 공유한다 — 결과가 복불복이고, 왜 이렇게 나왔는지 설명이 안 되며, 나온 메시를 사람이 손보기 어렵다. img2threejs가 트렌딩에 오른 이유는 이 지점을 정면으로 공략하기 때문이다. "AI의 창의성"이 아니라 "엔지니어링의 규율"로 3D 품질 문제를 푼다.

차별점 ① — "스크립트가 강제하고, 모델은 판단한다"

이 프로젝트의 설계 철학이 통째로 이 한 문장에 담겨 있다. 검증·게이팅·패키징처럼 정답이 정해진 일은 전부 결정론적(deterministic) 파이썬 스크립트가 처리한다. 값비싼 LLM 토큰은 오직 "이 비교 시트를 보니 원본과 닮았는가? 통과/실패"라는 판단 한 곳에만 쓴다. 덕분에 토큰이 절약되고, 무엇보다 "운이 좋아서 통과"가 원천 차단된다 — 실루엣이 안 맞으면 모델이 아무리 "괜찮다"고 해도 스크립트가 거부한다.

차별점 ② — 산출물이 "diff되는 텍스트"다

신경망이 뱉은 .glb 메시는 열어봐도 사람이 이해할 수 없는 바이너리다. img2threejs의 결과는 TypeScript 팩토리 함수(createObjectNameModel(spec, options))와 JSON 설계도다. 즉 버전관리(git)에 올려 "어제 모델과 오늘 모델이 코드 몇 줄 달라졌는지"를 그대로 볼 수 있고, 부품 하나의 색을 바꾸고 싶으면 해당 줄만 고치면 된다. AI 산출물을 협업 가능한 자산으로 만든 것이다.

차별점 ③ — 외부 의존성이 0이다

파이프라인 엔진(forge/)은 파이썬 표준 라이브러리만 쓴다. PNG를 읽고 쓰는 것도 struct+zlib로 직접, 색 차이 계산(CIEDE2000)도 순수 파이썬 구현이다. NumPy도, OpenCV도, PIL도, Playwright도 없다. requirements.txt에 아예 "NO third-party dependencies"라고 못박아 뒀다. 설치가 가볍고 어디서든 돌아가며, 공급망 보안 사고 위험도 없다.

3기술 스택 전체 지도

img2threejs를 처음 보면 헷갈린다. 파이썬 프로젝트인가, 타입스크립트 프로젝트인가? 답은 "둘 다이되, 역할이 다르다"이다. 파이썬은 공장의 기계(파이프라인 엔진)이고, 타입스크립트는 그 공장이 찍어내는 제품(3D 모델 코드)이다. 이 둘을 구분하는 순간 전체 그림이 선명해진다.

세계 A — 파이프라인 엔진 (forge/, Python)

"forge(대장간)"라는 이름 그대로, 물체를 제련하는 스크립트 뭉치다. 놀라운 점은 외부 라이브러리를 하나도 안 쓴다는 것.

세계 B — 산출물 (Three.js 팩토리, TypeScript)

공장이 찍어내는 제품은 순수 Three.js 코드다(래퍼 프레임워크 없음). 브라우저 WebGL 위에서 도는 THREE.Group 하나를 반환하는 팩토리 함수다.

세계 C — 눈(vision)은 어디서 오나

img2threejs 소스에는 OpenAI/Anthropic API 키도, 모델 호출 코드도 없다. 이미지를 "보는" 능력(VLM, Vision-Language Model)은 이 스킬을 실행하는 호스트 에이전트가 제공한다(Claude Code의 네이티브 이미지 리딩, 브라우저 MCP, 사용자 스크린샷 등). 스크립트 쪽 vlm_gate.py는 VLM을 주입형 콜러블(callable)로 받아, 그 판단을 결정론 규칙에 종속시켜 게이팅만 한다. 그래서 어떤 에이전트에 붙여도 동작하는 agent-agnostic 설계가 가능하다.

4아키텍처 심화 분석

img2threejs의 모든 것은 "어떻게 나쁜 결과를 코드 생성 전에 걸러내고, 나온 결과를 어떻게 자동으로 고칠 것인가"로 귀결된다. 그래서 파이프라인이 intake → spec → build → review 네 단계로 나뉘고, 각 단계 사이마다 게이트(관문)가 서 있다. 폴더 이름 접두사(stage1_~stage4_)가 그대로 이 순서를 보여준다.

③ 빌드 — "잠긴 패스"라는 아이디어

물체를 한 번에 완성하지 않는다. orchestrate_passes.py가 정한 순서대로 패스(pass)를 하나씩 잠금 해제한다.

코드 생성기는 지금 열린 패스만 코드로 뽑는다. 미래 패스를 미리 요청하면 "이전 패스가 아직 리뷰를 통과 안 했다"며 실패시킨다. 매 반복마다 모델 전체를 다시 그리지 않으니 토큰이 절약되고, 큰 형태가 틀린 채로 디테일에 힘 빼는 낭비를 막는다. 반복 부품은 InstancedMesh 하나로 묶어 성능까지 챙긴다.

// 반복 부품(톱니·나사·바퀴살)을 InstancedMesh 하나 = draw call 하나로
const cluster = new THREE.InstancedMesh(geo, mat, count);
for (let i = 0; i < count; i++) {
  /* 방사형/축 배치 행렬을 계산해서 */
  cluster.setMatrixAt(i, _m);
}

④ 리뷰 — "Divine Eye"라는 결정론 채점기

핵심 중의 핵심. divine_eye.py는 토큰을 한 개도 안 쓰는 결정론 멀티시그널 채점기다. 두 층으로 작동한다.

층 1 — HARD 게이트 (평균으로 못 덮는 치명적 실패)

층 2 — SOFT 신호 (가중 앙상블)

여러 각도의 유사도 신호를 가중 평균해 최종 fidelity(충실도, 목표 0.85)를 낸다. 신호가 서로 크게 엇갈리면(spread > 0.35) "확신이 없다"고 보고 probe(추가 확인)로 보낸다.

똑똑한 장치가 하나 있다. 사진과 절차적 렌더는 프레이밍이 달라 실루엣 IoU만으로 억울하게 탈락할 수 있다. 그래서 objectness가 "같은 물체(≥0.48)"라고 말하면, 확신에 찬 reject를 probe로 강등해 재확인 기회를 준다. 단, 자동 통과는 절대 안 시킨다 — 충실한 재구성을 살리되 기준은 안 낮춘다.

VLM은 "종속 계층"이다

모델의 눈(VLM)이 개입하는 유일한 곳이 vlm_gate.py인데, 규칙이 엄격하다.

if hard_failures:   # 규칙 1: HARD 게이트 실패 땐 VLM을 아예 호출조차 안 함
    return {"verdict":"reject", "action":"refine-code", "ranVlm":False}

N번 샘플링해 중앙값 투표를 하고, 의견이 흩어지면(spread > 0.20) probe로 보낸다. 그리고 VLM은 기하학적 HARD 실패를 절대 통과시킬 수 없다. "모델이 좋다고 우겨서 넘어가는" 사고를 구조적으로 막은 것이다.

수정 루프 — "무한 반복"을 원천 봉쇄

점수가 모자라면 고쳐서 다시 도는데, 자칫 영원히 돌 수 있다. correction_loop.py는 종료를 수학적으로 보장하는 우선순위 상태머신이다.

5디렉토리 구조 해부

폴더 이름이 재밌다. 실행되는 스크립트는 forge(대장간)에, 그 스크립트가 기준으로 삼는 규칙 문서는 grimoire(마법서)에 나눠 담았다. "기계는 forge에서 만들고, 판단 기준은 grimoire에서 읽는다"는 구조다.

구조가 말해주는 이야기는 분명하다. 진짜 무게중심은 stage2_spec(설계도 검증 1912줄)과 stage4_review(채점)에 있다. "어떻게 그리느냐"(stage3_build)보다 "어떻게 나쁜 걸 걸러내느냐"에 코드가 훨씬 많이 쏠려 있다는 뜻이다. 이건 이 프로젝트의 정체성 — "생성"이 아니라 "품질 관리"가 본질 — 을 그대로 반영한다.

6학습 포인트

배울 것 ① — 절차적 3D 지오메트리(Three.js)

"3D 모델 = 무거운 메시"라는 통념을, generate_threejs_factory.py가 깬다. Box·Sphere·Lathe·Tube·Extrude 같은 기본 도형을 코드로 조립해 어떻게 복잡한 물체를 표현하는지, 반복 부품을 InstancedMesh로 어떻게 성능 최적화하는지를 실물 코드로 볼 수 있다. Three.js 지오메트리 API의 좋은 교재다.

배울 것 ② — "판단"과 "실행"을 가르는 AI 시스템 설계

요즘 AI 앱의 최대 난제는 "어디까지 LLM에 맡기고 어디부터 코드로 강제할까"다. img2threejs는 이 경계선의 모범 답안이다 — 측정 가능한 건 전부 스크립트, 인지가 필요한 판단만 모델. LLM 파이프라인을 짜는 개발자라면 vlm_gate.py의 "종속 계층" 설계 하나만으로도 배울 게 많다.

배울 것 ③ — 결정론 이미지 품질 측정

divine_eye.py는 라이브러리 없이 실루엣 IoU, SSIM, pHash, CIEDE2000 색차, objectness를 구현해 앙상블한다. "두 이미지가 얼마나 닮았나"를 숫자 하나로 만드는 컴퓨터 비전의 고전 기법들을, 순수 파이썬 구현으로 정독할 수 있다. 무거운 딥러닝 없이도 이런 측정이 가능하다는 걸 배운다.

배울 것 ④ — 종료가 보장되는 자율 루프

"AI가 알아서 반복 개선"은 멋지지만, 실무에선 무한 루프·토큰 폭발이 공포다. correction_loop.py의 우선순위 상태머신(EMPTY→…→HARD_CEILING)은 "어떤 경우에도 반드시 끝난다"를 코드로 증명하는 법을 보여준다. 자율 에이전트를 안전하게 짜는 실전 패턴.

배울 것 ⑤ — PBR·색 이론의 실전 적용

extract_pbr_evidence.py(834줄)는 사진에서 albedo·roughness·normal·AO를 추론하되, 신뢰도가 0.7 미만이면 값을 거부한다. "AI가 자신 없으면 조용히 넘어가지 말고 명시적으로 거부하라"는 태도, 그리고 MeshPhysicalMaterial 계수로 재질을 표현하는 실전 지식을 얻는다.

7시스템 요구사항

주목할 점은 "무거움의 위치"다. 엔진 자체는 서브프로세스라 토큰을 거의 안 쓴다. 비용은 전부 모델이 이미지를 보고 판단하는 render-review 루프(패스당 비교 시트 ~2–3k 토큰, 5–8 사이클)에서 발생한다. 그래서 "패스를 잠그고 현재 것만 생성", "HARD 게이트로 조기 탈락", "VLM은 필요할 때만 호출" 같은 설계가 전부 토큰 절감 장치로 맞물려 있다. 아키텍처와 비용 구조가 한 몸인 셈이다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

이 순서를 밟으면 img2threejs는 단순한 "AI 3D 생성기"가 아니라 3D 그래픽스·컴퓨터 비전·AI 시스템 설계를 잇는 살아있는 교과서가 된다. 각 주차 개념이 정확히 어느 소스 파일에 구현돼 있어, "이론 → 실제 코드" 왕복 학습이 가능하다.

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/hoainho/img2threejs (Apache-2.0 · v1.3.0 · 저자 hoainho)
• TrendShift: trendshift.io/repositories/83608 (2026-07-25 Daily #2)
• 라이브 데모 갤러리: hoainho/img2threejs-showcase (GitHub Pages 데모 + TypeScript 데모 소스)
• 핵심 문서: SKILL.md(스킬 매니페스트·파이프라인 지침) · README.md(사용법) · docs/UPGRADE_PLAN.md(기술 스펙) · docs/TOKEN_COST.md(토큰 비용 모델)
• 핵심 소스: forge/stage4_review/divine_eye.py(결정론 채점) · vlm_gate.py(VLM 종속 게이트) · correction_loop.py(종료 보장 루프) · forge/stage3_build/generate_threejs_factory.py(코드 생성기) · forge/stage2_spec/validate_sculpt_spec.py(strict-quality 검증)
• 루브릭(grimoire): build/geometry_patterns.md(프리미티브 선택) · readiness/action_rigging.md(관절·소켓) · intake/surface_topology.md(위상 분류)
• 배경 개념: Three.js 지오메트리·MeshPhysicalMaterial(PBR) · 컴퓨터 비전 유사도(IoU/SSIM/pHash) · CIEDE2000 색차 · SMPL-X·FLAME(캐릭터) · 결정론 게이트가 있는 LLM 에이전트 루프