img2threejs — превращение изображений в 3D-модели с помощью ИИ и Three.js

img2threejs — это skill для Claude Code, Codex и OpenCode, который по одному изображению объекта воссоздаёт его в виде процедурной Three.js-модели. Результат — TypeScript-фабрика, возвращающая THREE.Group, готовый к анимации: с пивотами, сокетами, коллайдерами и иерархией.

Никакой фотограмметрии, извлечения мешей или загрузки арт-паков. Только код.

Как это работает

Конвейер состоит из последовательных этапов («проходов»), каждый из которых разблокируется только после проверки предыдущего:

blockout → structural-pass → form-refinement → material-pass → surface-pass → lighting-pass → interaction-pass → optimization-pass

На каждом проходе генерируется только одна порция кода. Агентский вижен проверяет рендер, сравнивает с эталоном и выносит вердикт: continue, refine-spec, refine-code, request-input или stop.

flowchart TD
    A[Reference image] --> B[Probe and suitability gate]
    B --> C[Pre-Spec Assessment]
    C --> D[Author ObjectSculptSpec]
    D --> E{Validate and strict-quality}
    E -- too shallow --> D
    E -- ok --> F[Locked build passes]
    F --> G[Generate Three.js factory]
    G --> H[Render in browser]
    H --> I[Package comparison sheet]
    I --> J{Agent vision review}
    J -- below threshold --> K[Self-correct]
    K --> F
    J -- pass --> L{More passes?}
    L -- yes --> F
    L -- no --> M[Animation-ready model]

Детали конвейера

Предварительная оценка. Изображение классифицируется как object, character или hybrid. Для объектов используется hard-surface конвейер, для персонажей — anatomy-aware трек с пропорциями головы, лицевыми landmarks и позой. Документация по персонажам лежит в grimoire/character/reconstruction.md.

Детальный инвентарь. До генерации кода собирается detailInventory — все ключевые детали: глянец, скругления, винты, гравировка, потёртости. Каждая деталь должна быть привязана к реальному компоненту или материалу. Строгий quality-gate блокирует генерацию, пока инвентарь неполон. Таксономия деталей — grimoire/intake/detail_inventory.md.

Спецификация ObjectSculptSpec. JSON с полным деревом компонентов, материалами, системами повторений и сокетами. Проходит валидацию с флагом --strict-quality.

Гейты качества. Конвейер использует несколько гейтов: suitability gate (проверяет, пригодно ли изображение для 3D), strict-quality gate (блокирует поверхностные спеки до кодогенерации), screenshot feedback (требует рендер + comparison sheet + проходной вижен-скор), attachment correctness (проверяет, что дочерние части не висят в воздухе), material and lighting realism (независимые PBR-каналы).

Самокоррекция. Если вижен-скор ниже порога, агент выбирает refine-spec (правит поверхностную спецификацию) или refine-code (правит геометрию, материалы, освещение). Решение всегда единственное — никаких параллельных действий.

Почему это эффективно по токенам

Большинство image-to-3D решений тратят токены на механическую работу: перечитывание всей модели на каждом шаге, скоринг пикселей, ручную валидацию JSON. img2threejs выносит всё это в детерминированные Python-скрипты и тратит токены модели только там, где нужно суждение.

• Скрипты на чистом Python 3.10+ стандартной библиотеки — ноль зависимостей, ноль pip install. PNG читается через struct и zlib.
• Генерация только текущего прохода — модель не пересоздаёт всю модель на каждой итерации, каждый шаг маленький и scoped.
• Fail fast: shallow spec блокируется до начала кодогенерации, чтобы не тратить токены на заведомо плохую модель.
• Одна comparison sheet на проверку — не россыпь скриншотов.
• Результат — diffable TypeScript + JSON, а не многомегабайтные меши. Код маленький, обозримый, под версионный контроль.

Скрипты

Быстрый старт

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.

Запуск скриптов вручную:

python3 forge/stage1_intake/probe_image.py <image>
python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json
python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts

Что получается на выходе

• ObjectSculptSpec JSON — дерево компонентов, материалов, сокетов, системы повторений и история ревью каждого прохода.
• TypeScript-фабрика createObjectNameModel(spec, options) с root.userData.sculptRuntime, экспонирующая узлы, сокеты, коллайдеры и destruction groups.
• Рендер и comparison sheets для каждого прохода, документирующие точность.

Дорожная карта

• v1.0 — конвейер объектов: скульптинг по этапам, цикл ревью, иерархия. Готово.
• v1.1 — detail-first анализ: обязательный инвентарь деталей, strict-quality gate. Готово.
• v1.2 — генератор человекоподобных персонажей: anatomy-трек, пропорции. Готово.
• v1.3 — максимизация сходства: projection-first рендеринг, поканальная уверенность. Запланировано.
• v1.4 — анимационные риги: SkinnedMesh, morph targets, glTF. Запланировано.

Ограничения

Одно изображение не показывает скрытые стороны и не гарантирует точную геометрию. Проект честно сообщает, когда результат приблизительный, стилизованный или low-poly. Хорошо работает для hard-surface объектов; персонажи — стилизованные реконструкции, не фотореалистичные копии. «This cannot reach the requested fidelity from this image» — валидный и ожидаемый результат.

Демо

Живые примеры в браузере: наушники Sony WF-1000XM3, дробовик ISSACA, нож Gerber Paracord, изометрический дом Дораэмона, военный транспорт War-Hauler, сундук с сокровищами. Каждую модель можно покрутить и посмотреть исходный код:

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

Лицензия

Apache License 2.0.