img2threejs：开源AI智能体3D建模插件，程序化生成可交互Web3D模型代码

一、img2threejs 是什么

img2threejs 是一款基于 Python + TypeScript + Three.js 构建的开源AI视觉驱动单图程序化3D重建工具，适配 Claude Code、Codex、OpenCode 等各类AI代码智能体，项目许可证已由 MIT 更换为 Apache-2.0 开源协议。

和传统图生3D工具核心区别：它不生成网格模型文件、不使用摄影测量、不加载外部美术资源，仅依靠单张物体参考图片，通过分层流水线分析图像细节，自动输出可直接运行的 Three.js TypeScript 工厂代码，用基础几何体、程序化PBR着色器拼接出完整3D模型，成品原生支持浏览器实时渲染、交互与动画制作，全程无需专业3D建模软件。

二、功能特色

1. 单图无损程序化硬表面重建

仅输入一张物体图片，精准还原物体比例、倒角、金属包边、自发光标识、磨损污渍、螺丝刻线等全部视觉细节，内置细节清单质检机制，遗漏细节会直接阻断代码生成，保证还原度。支持宝箱、耳机、枪械、刀具、载具、卡通建筑等绝大多数硬质道具资产。

2. 人形角色专属重建管线

内置解剖感知重建流程，自动锁定人体比例、面部特征点位；v1.3 新增投影优化能力，将原图映射至参数化人体模板提升人像相似度，系统会输出面部、躯干各区域还原置信度，单图信息不足时主动提示补充多视角图片。

3. 原生动画与交互就绪模型输出

生成的代码返回标准 THREE.Group 对象，内置专属 root.userData.sculptRuntime 运行时数据，自带模型转轴、插槽、碰撞体、破碎分组，无需二次拆分模型，开箱即可做动画、交互、破坏特效。

4. 极致Token轻量化AI协作设计

整套自动化处理脚本仅依赖Python3标准库，无numpy、PIL、Playwright等第三方依赖，图像解析、规范校验、对比图生成等机械工作全部交由本地脚本完成；AI仅负责视觉评审、代码编写，大幅降低大模型上下文消耗，节省调用成本。

5. 闭环式分层质检生成流水线

采用8阶段串行生成流程，每一步渲染完成后自动生成「原图-渲染结果」对比图，交由AI视觉打分评审，分数不达标自动回退修正规范或代码，循环迭代直至还原度达标后，才进入下一制作阶段，杜绝低质量3D代码输出。

6. 标准PBR物理材质还原

独立解析原图金属度、粗糙度、自发光、基础色通道，不会将光照、阴影信息混进基础贴图，渲染质感贴近原图，支持金属、漆面、发光、布料等多种材质混合制作。

7. 全流程可追溯交付产物

每次生成输出三类可存档文件：细节完整的JSON规范文档、可直接导入项目的TypeScript模型工厂代码、每一轮迭代的原图渲染对比截图，方便版本管理、二次修改与效果溯源。

三、技术细节

1. 整体技术栈

• 底层自动化脚本：Python 3.10+（纯标准库，无第三方依赖，PNG读写依靠struct、zlib原生模块实现）

• 3D渲染输出：Three.js + TypeScript，输出标准化THREE.Group工厂函数

• AI协作载体：Claude Code / Codex / OpenCode 代码智能体，依托AI视觉能力完成图像评审

• 项目仓库分层：

1. forge：流水线执行脚本（图像预检、规范生成、代码输出、对比图打包）

2. grimoire：官方规范手册（重建标准、材质规则、角色解剖管线、质检门槛）

3. docs：技术文档、Token消耗分析、版本升级方案

4. assets、demo：在线演示素材与画廊资源

2. 核心8阶段流水线流程

块体粗模 → 结构搭建 → 形体细化 → 材质制作 → 表面细节 → 灯光匹配 → 交互插槽 → 性能优化
完整闭环逻辑：

1. 图像预检：探测图片基础信息，提取相机视角、材质、细节清单；

2. 预评估：区分物体/角色分类，评估重建复杂度，设定质量标准；

3. 生成ObjectSculptSpec规范文件，严格校验细节完整性，不合格直接回退；

4. 分阶段增量生成Three.js代码，浏览器实时渲染；

5. 自动打包原图与渲染图对比素材，交由AI视觉打分；

6. 评审不达标则修正规范/代码重新渲染；达标后进入下一阶段；

7. 全阶段通过后，输出完整可动画3D模型代码。

3. 多层质量拦截闸门

1. 适配性闸门：过滤模糊、遮挡严重、无法重建的无效图片；

2. 严格规范闸门：细节清单缺失直接阻止代码生成，避免无效Token消耗；

3. 渲染评审闸门：必须配套对比截图+达标视觉分数，才可进入下一阶段；

4. 部件绑定闸门：校验子部件连接逻辑，杜绝零件悬浮错位；

5. 材质光照闸门：校验PBR通道分离，防止光影信息污染基础色。

4. Token高效优化核心逻辑

1. 机械性重复工作全部交由本地Python脚本处理，不占用AI上下文；

2. 分阶段增量生成代码，每次仅输出当前制作阶段内容，不重复生成完整模型；

3. 前置拦截低质量输入，未达标直接终止流程，避免无效渲染消耗；

4. 输出文本格式TS+JSON，体积远小于网格二进制文件，Diff、版本管理更轻量化；

5. 单次评审仅提供一张对比图，减少AI多图处理带来的Token损耗。

5. 项目局限性技术说明

单张图片无法获取物体背面、内部隐藏结构，未可见区域依靠镜像逻辑自动推理，无法做到100%精准；硬表面道具还原效果最优，人形角色仅能实现风格化近似重建，无法达到照片级写实效果，系统会主动输出区域置信度提示精度缺陷。

四、应用场景

1. 前端Web3D项目快速资产开发
   网页游戏、数字展厅、WebGL可视化项目，无需3D美术建模，上传道具参考图一键生成浏览器可运行Three.js代码，大幅缩短资产制作周期。

2. AI智能体配套3D生成能力
   基于Claude Code等AI代码工具拓展3D建模能力，实现对话式图片转程序化3D模型，适合AI开发、自动化工具链搭建。

3. 独立游戏/小游戏轻量化资产制作
   宝箱、枪械、道具、家电、卡通建筑等低多边形硬表面资产快速产出，原生支持交互、破碎、发光动画，适配2D/3D休闲小游戏。

4. 教学与Three.js学习演示
   生成的代码完整保留几何体、材质、分层结构逻辑，学习者可直观参考程序化建模思路，配套在线Demo画廊实时查看渲染效果与源码。

5. 原型快速验证
   产品概念图、道具原画无需导出FBX/GLTF网格，直接生成可旋转预览的Web3D原型，快速验证外观、比例、材质设计。

五、使用方法

1. 环境前置要求

仅需 Python 3.10 及以上版本，无额外第三方库、无容器、无渲染软件依赖；适配 Claude Code AI 代码运行环境。

2. 一键安装（Claude 技能目录）

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

3. AI智能体一键调用指令

在Claude Code中上传物体参考图片，输入指令即可启动全自动重建流水线：

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

4. 手动分步执行Python脚本（本地独立运行）

# 1. 图像预检，检测图片基础问题
python3 forge/stage1_intake/probe_image.py 你的图片路径.png
# 2. 生成物体评估文档
python3 forge/stage2_spec/new_pre_spec_assessment.py "模型名称" --image 图片路径 --out assessment.json
# 3. 生成完整重建规范
python3 forge/stage2_spec/new_sculpt_spec.py "模型名称" --image 图片路径 --assessment assessment.json --out spec.json
# 4. 严格校验规范完整性
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality
# 5. 输出Three.js模型工厂TS代码
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts

5. 成果查看

项目配套在线Demo画廊，所有生成模型可实时拖拽旋转查看，同时支持一键查看对应生成源码；本地运行脚本后，可打开浏览器预览渲染对比图与成品3D效果。

六、竞品对比

选取市面主流2类图生3D工具（网格生成类、程序化代码类），与img2threejs进行横向对比：

七、常见问题解答

Q1：img2threejs 生成的模型可以直接导入Three.js项目使用吗？

A：可以，工具输出标准TypeScript工厂函数，调用后直接返回THREE.Group实例，自带完整材质、层级结构，无需额外转换，直接嵌入WebGL网页项目。

Q2：没有Claude Code，能否本地独立运行这套工具？

A：可以，项目提供全套独立Python执行脚本，无需AI智能体也能分步运行，仅缺少AI视觉自动评审环节，需要人工核对原图与渲染效果。

Q3：单张图片生成的模型背面结构准确吗？

A：不准确，单张图片无法获取物体背面、内部结构，工具会基于可见面镜像推理生成背面，复杂曲面、不对称物体还原会存在偏差，建议提供多角度图片提升精度。

Q4：工具支持生成人物、卡通角色完整3D模型吗？

A：支持基础角色重建，内置解剖感知管线，但仅能做到风格化近似效果，无法实现照片级写实人像；高精度人像需要多张不同角度参考图。

Q5：运行脚本需要安装numpy、PIL、Playwright等第三方库吗？

A：不需要，整套自动化脚本仅使用Python3内置标准库，无任何外部依赖，下载仓库后可直接执行，无需pip安装组件。

Q6：生成的模型支持导出glTF、GLB网格文件吗？

A：当前v1.3版本暂不支持网格导出，该功能规划于v1.4版本；现阶段仅输出程序化代码，依靠Three.js实时渲染展示模型。

Q7：项目之前是MIT协议，现在改为Apache-2.0有什么影响？

A：商用场景下无需担心版权风险，Apache-2.0协议包含专利授权条款，允许商用、二次分发、修改项目代码，仅需保留版权声明文件。

Q8：哪些图片不适合用于img2threejs重建？

A：重度遮挡、模糊失焦、透明复杂结构、大量动态光影、多层堆叠复杂场景、无清晰轮廓的抽象图片，系统预检阶段会直接拦截并提示更换参考图。

八、相关链接

• GitHub仓库地址：https://github.com/hoainho/img2threejs

九、总结

img2threejs是一款差异化极强的开源单图转Web3D程序化代码工具，摒弃传统图生3D生成网格模型的思路，依托分层质检流水线与轻量化Python脚本，深度适配AI代码智能体，以极低的Token消耗将单张参考图片转化为原生支持动画、交互的Three.js TypeScript资产，零第三方依赖、完全开源免费，尤其适合前端WebGL开发、小游戏轻量化资产制作与AI自动化3D工具链搭建，虽然受限于单图信息存在还原精度短板，但凭借代码化输出、AI友好、轻量化的核心优势，填补了市面上程序化图生3D代码工具的空白。