# img2obj: 참조 이미지를 애니메이션 가능한 Three.js 절차적 코드로 재구성하는 Codex 플러그인

**URL:** <https://discuss.pytorch.kr/t/img2obj-three-js-codex/11724>\
**Category:** 읽을거리&정보공유\
**Tags:** threejs, img2obj, codex, procedural-generation, 3d-modeling, agent-skills\
**Created:** [8월 31, 2026, 12:00오후 UTC](https://discuss.pytorch.kr/t/img2obj-three-js-codex/11724 "2026-08-31T12:00:33Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![9bow](https://discuss.pytorch.kr/user_avatar/discuss.pytorch.kr/9bow/32/16301_2.png) [@9bow](https://discuss.pytorch.kr/u/9bow)\
**Post date:** [8월 31, 2026, 12:00오후 UTC](https://discuss.pytorch.kr/t/img2obj-three-js-codex/11724/1 "2026-08-31T12:00:33Z")

</div>

![img2obj: 참조 이미지를 애니메이션 가능한 Three.js 절차적 코드로 재구성하는 Codex 플러그인](https://discuss.pytorch.kr/uploads/default/original/3X/5/9/59d9a63d28a50d46cbac2e10020a9d74f0890f0b.jpeg)

## img2obj 소개

웹에 3D 오브젝트를 하나 올리려면 보통 모델 파일을 구해 옵니다. 에셋 스토어에서 내려받거나, 사진 여러 장으로 포토그래메트리(Photogrammetry)를 돌려 메시를 뽑거나, 3D 도구에서 직접 모델링합니다. 세 방법 모두 결과물이 바이너리 메시라서 저장소에 수십 메가바이트가 들어오고, 회전축이나 여닫히는 부품을 나중에 붙이려면 원본 파일을 다시 열어야 하며, 부품 하나의 비율을 고치는 일이 코드 리뷰로 확인되지 않습니다. 웹 앱을 코드로 관리하는 팀에게 3D 자산만 다른 규칙으로 남는 셈입니다.

img2obj는 그 자산을 코드로 되돌리는 쪽을 택한 [Codex](https://developers.openai.com/codex) 플러그인입니다. 참조 이미지 한 장을 넣으면 픽셀을 메시로 변환하는 것이 아니라, 이미지를 판독해 부품 계층과 지오메트리와 재질을 담은 `ObjectSculptSpec` 을 먼저 작성하고, 그 명세에서 [Three.js](https://threejs.org/) 지오메트리를 절차적으로 생성하는 TypeScript 팩토리 함수를 만듭니다. 결과물이 코드이므로 회전축(Pivot)과 부착점(Socket)과 부모 자식 관계를 처음부터 명세에 넣을 수 있고, 값 하나를 바꾸는 수정이 diff로 남습니다.

절차 안에 검수 단계가 들어 있다는 점이 이 플러그인의 다른 축입니다. img2obj는 블록아웃에서 형태, 룩데브, 인터랙션으로 단계를 올리면서 각 단계마다 브라우저 렌더 결과를 원본 이미지와 나란히 놓고 차이가 큰 곳부터 고치도록 만들고, 다음 단계로 넘어가기 전에 사용자 승인을 요구합니다. 저자는 이 흐름을 \*"It guides Codex through a controlled reconstruction workflow"\*라고 설명하면서, 픽셀을 완성된 메시로 바꿔 주는 도구가 아니라는 점을 함께 밝히고 있습니다. 저장소는 원래 `Three.js-Object-Sculptor-Codex-Plugin` 이라는 이름이었고 지금은 `img2obj` 로 바뀌어 예전 주소가 새 주소로 넘어옵니다.

## img2obj가 만드는 것과 만들지 못하는 것

프로젝트가 첫 화면에서 적용 범위를 표로 정리해 둔 것이 도입 판단에 가장 먼저 쓰입니다:

| 항목 | 내용 |
| --- | --- |
| 입력 | 첨부한 오브젝트 이미지, 스크린샷, 또는 로컬 이미지 경로 |
| 출력 | `ObjectSculptSpec` 과 코드만으로 이루어진 절차적 Three.js 팩토리 |
| 목표 | 보이는 실루엣, 구조, 재질, 그리고 움직임을 붙일 수 있는 계층의 재현 |
| 적합 | 스타일라이즈드 소품, 기계 장치, 식물, 장면 자산, 인터랙티브 모델 |
| 부적합 | 포토그래메트리, 정확한 메시 추출, 이미지 한 장에서 프로덕션급 지오메트리 보장 |

부적합 열이 특히 중요합니다. 프로젝트가 밝힌 한계는 이미지 한 장으로는 가려진 면과 정확한 치수를 알 수 없다는 것, 결과가 스캔이나 추출이 아닌 절차적 근사라는 것, 투명한 유리와 연기와 액체와 털과 얇은 천과 정확한 인물 닮음에는 참조가 더 필요하거나 목표 정밀도를 낮춰야 한다는 것입니다. 생성된 팩토리 함수는 완성된 프로덕션 자산 파이프라인의 대체물이 아니라 출발점이라고 명시해 두었습니다.

## img2obj의 재구성 워크플로우

저자가 정리한 절차는 네 단계입니다. 첫 단계에서 참조 이미지의 품질과 오브젝트 가시성과 복잡도를 점검하고 더 깨끗한 원본이 필요한지 판정합니다. 두 번째 단계에서 부품 계층, 지오메트리, 재질, 회전축, 부착점, 시각적 우선순위를 `ObjectSculptSpec` 으로 서술합니다. 세 번째 단계에서 블록아웃, 형태, 룩데브, 인터랙션 순서로 진행하면서 뒤 단계의 디테일을 앞 단계에 끌어오지 않습니다. 마지막 단계에서 브라우저 렌더를 현재 원본과 비교해 영향이 큰 차이부터 고치고, 다음 단계로 올라가기 전에 승인을 받습니다.

품질 판정은 두 층으로 나뉩니다. 전체 정체성은 실루엣, 비율, 카메라, 재질, 조명을 봅니다. 핵심 특징은 그 오브젝트를 알아보게 만드는 소수의 부품, 예를 들어 지붕 윤곽이나 가지가 갈라지는 지점이나 바퀴 뭉치나 손이 물체에 닿는 부분을 봅니다. **전체 점수가 높아도 핵심 특징 하나가 실패하면 통과하지 못합니다.** 활성 단계에서는 시각적 증거와 사용자의 명시적 승인이 함께 있어야 다음으로 넘어갑니다.

이 워크플로우가 실제로 무엇을 만들어 내는지는 저장소가 공개한 두 개의 사례에서 확인할 수 있습니다.

 ![img2obj로 참조 이미지에서 재구성한 절차적 Three.js 누선(Tower Ship) 데모 화면](https://discuss.pytorch.kr/uploads/default/original/3X/3/2/3264cdbc9132461fa4c0310b4d0b8f02c8050e04.jpeg)

첫 번째 사례인 [누선(Tower Ship) 데모](https://3dship.harrysoftware.com)는 왼쪽 아래에 참조 이미지를 함께 띄워 두고, 절차적 지오메트리와 관절이 있는 부품과 재질 작업과 브라우저 조작을 함께 보여 줍니다. 화면 아래의 버튼으로 회전대, 강풍, 노 젓기, 등불, 번개를 켜고 끌 수 있는데, 이 움직임들이 명세 단계에서 미리 계획한 회전축과 부착점 위에서 동작합니다.

 ![img2obj로 참조 이미지에서 재구성한 절차적 Three.js 오래된 가을 나무 데모 화면](https://discuss.pytorch.kr/uploads/default/original/3X/d/0/d01c4c4f52cd143a2c6d944da37039683bb1c153.jpeg)

두 번째 사례인 [오래된 가을 나무(Ancient Autumn Tree) 데모](https://tree.harrysoftware.com/)는 성격이 다른 문제를 다룹니다. 절차적 곡선, 결정론적 가지 분기, 겹쳐 쌓은 껍질, 빽빽한 잎, 그리고 움직임을 붙일 수 있는 계층이 이 사례의 초점입니다. 가지가 결정론적으로 갈라진다는 것은 같은 명세에서 같은 나무가 다시 나온다는 뜻이라, 코드로 관리하는 자산에서 중요한 성질입니다.

## img2obj 설치와 사용

저장소를 받아 로컬 Codex 플러그인으로 불러오는 방식입니다. Codex의 로컬 플러그인 지원과 Python 3.10 이상, 그리고 생성된 팩토리를 띄울 Three.js 브라우저 프로젝트가 필요하고, 원본 정리와 계획 시점의 뷰 생성과 시각 검수에는 이미지와 비전 접근이 필요합니다:

```bash
git clone https://github.com/vinhhien112/img2obj.git
cd img2obj
python3 scripts/sculpt.py --help

```

플러그인을 불러온 뒤에는 오브젝트 이미지를 첨부하고 자연어로 요청합니다:

```plaintext
Use img2obj to turn the object in this image into a procedural Three.js model built entirely with code.

```

움직임이 필요하면 그 요구만 따로 덧붙입니다. 프로젝트가 든 예시는 \*"Make the visible hatch open on its hinge. Do not add physics or destruction"\*처럼 원하는 동작과 원하지 않는 범위를 함께 적는 형태입니다.

명령줄에서 직접 단계를 밟을 수도 있습니다. [저장소의 `scripts/sculpt.py`](https://github.com/vinhhien112/img2obj/blob/main/scripts/sculpt.py)가 통합 진입점이고, 명세 생성부터 검증과 코드 생성까지 하위 명령으로 이어집니다:

```bash
python3 scripts/sculpt.py init "Ancient Autumn Oak" \
  --image ./reference/oak-tree.png \
  --reference-separation clear \
  --complexity complex \
  --out object-sculpt-spec.json

python3 scripts/sculpt.py context object-sculpt-spec.json

python3 scripts/sculpt.py validate object-sculpt-spec.json \
  --for-pass blockout \
  --strict-quality

python3 scripts/sculpt.py generate object-sculpt-spec.json \
  --out src/AncientOak.generated.ts \
  --wrapper-out src/AncientOak.ts

```

`init` 이 참조 이미지와 분리도와 복잡도를 받아 명세 JSON을 만들고, `validate` 가 지정한 단계 기준으로 명세를 검사하며, `generate` 가 생성 파일과 그것을 감싸는 래퍼(Wrapper) 파일을 따로 떨궈 줍니다. 생성물과 손으로 고칠 파일을 분리해 두는 구성이라 재생성이 사용자 수정을 덮지 않습니다. 비교, 검수, 보정, 능력 팩, 프로브, PBR(Physically Based Rendering) 맵 관련 명령은 `--help` 로 확인할 수 있고, 워크플로우 계약과 스크립트를 고친 뒤에는 회귀 테스트를 실행합니다:

```bash
python3 -m unittest discover -s tests

```

핵심 워크플로우 정의는 [저장소의 `skills/object-to-threejs-procedural/`](https://github.com/vinhhien112/img2obj/tree/main/skills/object-to-threejs-procedural)에 들어 있어, 플러그인을 쓰지 않고 명세만 읽어 보는 것도 가능합니다.

## 이미지에서 3D를 만드는 다른 접근과 비교

같은 입력에서 출발하는 프로젝트들이 서로 다른 출력을 고릅니다. img2threejs (:pytorch::kr: [img2threejs: 이미지 한 장을 코드로 재구성하는 Three.js 3D 모델 생성 도구](https://discuss.pytorch.kr/t/img2threejs-three-js-3d/11410))도 이미지 한 장을 Three.js 코드로 재구성하고, 3DCellForge (:pytorch::kr: [3DCellForge: 참조 이미지를 인터랙티브 3D 모델로 만드는 웹 스튜디오](https://discuss.pytorch.kr/t/3dcellforge-3d/10706))는 참조 이미지를 인터랙티브 3D 모델로 만드는 웹 스튜디오를 제공하며, image-blaster (:pytorch::kr: [image-blaster: 이미지 한 장에서 3D 환경과 효과음을 만들어내는 Claude 스킬셋](https://discuss.pytorch.kr/t/image-blaster-3d-claude/11500))는 이미지에서 3D 환경과 효과음까지 함께 만들어 냅니다. 자연어에서 출발하는 CADAM (:pytorch::kr: [CADAM: 자연어로 3D CAD 모델을 만드는 오픈소스 text-to-CAD 웹 애플리케이션](https://discuss.pytorch.kr/t/cadam-3d-cad-text-to-cad/10814))처럼 입력 자체가 다른 계열도 있습니다.

img2obj가 이 중에서 다른 점은 **완성도를 게이트로 만들어 사람의 승인 없이는 단계가 올라가지 않게 한 것** 입니다. 저장소는 지원하지 않는 지오메트리와 검증되지 않은 보정을 조용히 추측한 결과로 대체하지 않고 거부한다고 적어 두었고, 시각적 수용 판정에는 비전 검수가 필요하며 로컬 스크립트는 증거를 정리할 뿐 유사도를 스스로 판정하지 않는다고 범위를 그어 두었습니다. 빠르게 결과를 얻는 것보다 어디까지 닮았는지를 확인하며 올라가는 쪽에 무게를 둔 설계입니다.

## img2obj는 누구에게 맞는가

Three.js로 웹 씬을 직접 만들고 있고, 소품이나 배경 자산을 바이너리 메시가 아닌 코드로 두고 싶다면 잘 맞습니다. 특히 부품이 여닫히거나 회전하는 인터랙티브 오브젝트가 필요할 때, 계층과 회전축을 처음부터 명세에 넣는 방식이 나중에 리깅을 얹는 것보다 손이 덜 갑니다. 이미 Codex를 쓰고 있다면 로컬 플러그인으로 불러오는 비용도 저장소를 받아 두는 것으로 끝납니다.

반대로 **실측 치수가 맞아야 하는 자산이나 실사 수준의 닮음이 필요한 팀에게는 img2obj가 적절한 선택지가 아닙니다.** 저자가 직접 포토그래메트리와 정확한 메시 추출을 부적합 항목으로 적어 두었고, 이미지 한 장에서는 가려진 면과 치수를 복원할 수 없다는 한계도 함께 밝혀 두었습니다. 사람이 매 단계 승인해야 진행되는 구조이므로, 자산 수백 개를 무인으로 찍어 내는 용도와도 맞지 않습니다.

## img2obj의 라이선스

img2obj는 [MIT 라이선스](https://github.com/vinhhien112/img2obj/blob/main/LICENSE)로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

## 🖼 img2obj로 만든 누선(Tower Ship) 라이브 데모

> **[Ancient Tower Ship — Procedural Three.js Study](https://3dship.harrysoftware.com)**

## 🖼 img2obj로 만든 오래된 가을 나무 라이브 데모

> **[Ancient Autumn Tree — Three.js procedural study](https://tree.harrysoftware.com/)**
>
> A procedural Three.js reconstruction of an ancient autumn tree from a reference image.

## :github: img2obj 프로젝트 GitHub 저장소

> **[GitHub - vinhhien112/img2obj: Codex plugin that turns attached object images...](https://github.com/vinhhien112/img2obj)**
>
> Codex plugin that turns attached object images into code-only, animation-ready procedural Three.js models.

## 더 읽어보기

- [img2threejs: 이미지 한 장을 코드로 재구성하는 Three.js 3D 모델 생성 도구](https://discuss.pytorch.kr/t/img2threejs-three-js-3d/11410)

- [3DCellForge: 참조 이미지를 인터랙티브 3D 모델로 만드는 웹 스튜디오](https://discuss.pytorch.kr/t/3dcellforge-3d/10706)

- [image-blaster: 이미지 한 장에서 3D 환경과 효과음을 만들어내는 Claude 스킬셋](https://discuss.pytorch.kr/t/image-blaster-3d-claude/11500)

- [CADAM: 자연어로 3D CAD 모델을 만드는 오픈소스 text-to-CAD 웹 애플리케이션](https://discuss.pytorch.kr/t/cadam-3d-cad-text-to-cad/10814)

- [WebGPU Claude Skill: TSL을 사용하여 WebGPU 기반 Three.js 애플리케이션 개발을 위한 Claude 스킬(Skill)](https://discuss.pytorch.kr/t/webgpu-claude-skill-tsl-webgpu-three-js-claude-skill/8822)

- [Sol Advisor: 작업 규모와 위험도에 따라 서브 에이전트 위임 여부를 결정하는 Codex 에이전트 오케스트레이션 플러그인](https://discuss.pytorch.kr/t/sol-advisor-codex/11678)

* * *

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

이 도구를 직접 설치해 사용해보셨다면, [:pytorch:파이토치 한국 사용자 모임🇰🇷](https://pytorch.kr/) 회원들을 위해 경험이나 팁을 댓글로 남겨주세요! 🙏