img2threejs：一张图片直接生成可交互 Three.js 3D 模型，无需 Blender¶
以前想把一张产品图做成可旋转的 3D 展示，通常需要进 Blender 手动建模，或者交给图生 3D 服务生成网格——拿到结果之后能不能改、零件能不能动、材质怎么调，往往要等文件拿回来才知道。
img2threejs 走了另一条路。它让 AI Agent 观察参考图，拆出结构和材质，然后编写 Three.js TypeScript 代码，输出一个可以直接放进网页项目继续修改的 3D 模型工厂函数。截至 2026 年 7 月 30 日，GitHub 仓库已有 8,125 Stars，当前正式版本为 v1.4.3，采用 Apache 2.0 开源协议。
如果你正在做网页 3D、产品展示、游戏原型或交互式道具，img2threejs 的「代码优先」思路值得了解。
它和传统 3D 建模工具有什么不同¶
传统 3D 工作流的典型路径是：建模软件中手动或半自动重建物体，导出为 GLB / OBJ / STL 等通用格式，再导入游戏引擎或网页端渲染。这条路径的产出是「网格文件」，适合跨软件流转，但对前端开发者来说，拿到 mesh 之后改材质、拆零件、加动画仍然需要回到 DCC 软件。
img2threejs 的核心思路是「代码优先」。它不做 mesh 提取和导出，而是让 Agent 分析图片后，用 Three.js primitives、程序化几何和生成纹理直接写 TypeScript 代码。输出的是一个 createObjectModel(spec, options): THREE.Group 工厂函数——这段代码可以放进 Git 管理、直接运行在网页上、随时修改参数和材质。
这意味着：如果你想在网页里放一个可旋转的耳机盒，不用导出模型文件，只需要把生成的 TypeScript 代码 import 进你的 Three.js 项目即可。想改颜色？改代码里的材质参数。想加开盖动画？暴露的 pivot 和 socket 元数据直接供你接入动画系统。
一张图片经历哪些步骤：8 轮 Build Pass¶
img2threejs 不会一次性「看到图就出代码」。它采用多轮递进式生成流程，每一轮都会渲染并截图，再与参考图合成对照图，由视觉 Agent 逐轮审核比例、轮廓和局部特征。
通用物体的默认核心 build passes 是：
- blockout — 第一轮搭出大体积和基本轮廓
- structural-pass — 补充分子结构、连接件和内部零件
- form-refinement — 精修外形曲线和比例
- material-pass — 定义材质属性、颜色和纹理
- surface-pass — 处理表面细节和装饰元素
- lighting-pass — 调整灯光方案以匹配参考图光照
- interaction-pass — 配置可动部件的 pivot 和 socket
- optimization-pass — 性能优化和最终清理
每轮渲染后都会生成 comparison sheet——参考图与渲染图的并排对照。如果 Agent 判断比例不对、特征缺失或侧面厚度有误，它会回到对应的阶段调整规格或代码，而不是从头再来。这种「deterministic-first」架构让问题更容易定位：耳机盒盖角度不对，可以追到结构阶段；材质过亮，回到 material pass 调整即可。
你会得到四份核心产物¶
成功完成一次重建后，img2threejs 产出一套完整的工程化文件：
1. Pre-Spec Assessment — 记录物体类别、复杂度和质量要求的评估报告。复杂物体如果结构拆解不充分，strict-quality 门禁会阻止继续生成代码，避免输出一个没有内部结构的空壳。
2. ObjectSculptSpec JSON — 整个重建过程的结构依据，包含组件层级、材质定义、灯光配置、socket 和 pivot 定义，以及重点校验区域。这份 JSON 是后续代码生成的「蓝图」，规格漏掉的部件后面很难靠视觉补回来。
3. Three.js Factory（TypeScript 工厂函数） — 最终交付的代码。每个 mesh 都有可读的名称，活动部件作为独立节点，程序化噪声使用固定 seed 保证可复现。当前版本没有统一的资源销毁契约，集成时需要自行处理 geometry、material 和 texture 的释放。
4. Comparison Sheet — 每个 build pass 阶段都生成参考图与渲染图的并排对照。这是主要的人工/AI 审核输入——即使全局视觉分数达标，关键特征、结构覆盖或轨道视角任一硬门禁失败，流程仍会停止并要求修正。
这套产物分工明确：Python 脚本负责可确定的探测、JSON 校验、像素诊断、门禁、比较图和状态管理；Agent 负责语义图像分析、规格撰写、视觉判断和代码修改。确定性硬门禁失败时，VLM（视觉语言模型）不会被调用。
适合什么场景，不适合什么场景¶
img2threejs 最适合已经在做 Three.js 开发的团队或独立开发者。网页 3D 展示、交互式产品页面、游戏原型道具、可动画角色部件——这些场景中，可读、可改、可版本管理的代码比通用模型文件更有价值。
不适合的场景同样明确：如果你需要一个 GLB / OBJ / STL 文件导入 Blender、Unity 或 Unreal，当前版本做不到。3D 打印导出、Unity/Unreal 桥接和 Blender 集成仍在路线图中。项目文档也明确说明，它不会从照片中提取现成 mesh，也不会直接交付通用 3D 模型文件。
单张图片的信息天然有限——看不到背面和底部，无法保证真实尺寸，内部结构需要推断。最佳实践是提供正面、侧面和背面三张图，并把实际尺寸写进输入。
Token 成本估算与实践建议¶
根据项目文档 docs/TOKEN_COST.md，单物体重建的总 Token 消耗约为 8 万至 18 万模型 Token，角色重建约为 15 万至 35 万 Token。这些数字来自一个经过约 6 次渲染校验的宝箱案例，人物区间沿用 v1.2 生成器的成本模型，不同供应商的计费口径也不一致，应视为数量级估算而非精确报价。
实践中可以把跑脚本、改小段代码和整理中间产物交给低价执行模型。结构判断、渲染对照和失败修正如果频繁出错，返工会抵消单次调用节省的成本。
安装时建议固定版本。仓库历史自动化曾留下 v1.5.0 和 v1.6.0-beta.1 等非治理基线，维护方声明从 annotated tag v1.4.3 起，GitHub Releases 才是正式发布记录：
1 2 3 | |
使用时需要注意的三件事¶
第一，把单图重建当成精确扫描。 一张图只能约束可见轮廓。隐藏结构、绝对尺寸和内部零件都需要推断。只看正面截图时，扁平贴图也可能在某些角度看起来很像——项目要求非平面模型至少检查两个轨道视角，用来发现模型被做成薄片、连接件悬空或侧面厚度错误。
第二，人物和品牌素材有边界。 项目文档提供人物重建和 projection-first 工作流，也包含地标、相机匹配、去光照和投影描述符等辅助脚本。但单图无法保证 100% 相似，仓库要求输出每个区域的置信度。品牌产品、影视角色和游戏皮肤涉及商标、著作权及游戏资产许可——技术上能提取或投影，不代表获得了商业使用权。
第三，先读 SKILL.md，在临时分支运行。 img2threejs 的 Skill 包含大量流程指令和本地脚本。虽然 v1.4.3 的 263 项测试全部通过，仍建议先阅读 SKILL.md 和 forge/ 目录，固定版本，在临时分支运行，并用 Git diff 检查修改了哪些文件。
小结¶
img2threejs 的价值不在于「一句话生成 3D」的速度，而在于把「看图拆结构、写代码、渲染对照、继续修正」整理成了一套可审计、可版本管理、可继续工程化的流程。输出是可读的 TypeScript 代码，不是黑盒模型文件——这对于前端开发者来说，比拿到一个改不了的 GLB 更有长期价值。
如果只是需要下载一个通用模型文件导入任意 DCC 软件，当前版本还需要自己补导出链路。但对于已经在做 Three.js 项目、需要快速将产品图转化为可交互网页 3D 的开发者来说，img2threejs 提供了一条比手动建模更快的路径。
你有一张想变成 3D 的产品图吗？ 从无线耳机、台灯到玩具车，选一个轮廓清晰、背景简单的物体试试看——项目文档推荐的入门对象包括耳机盒、台灯、椅子、玩具车和收纳盒，都是适合第一轮测试的好选择。