一张图生成可旋转 3D：img2threejs 直接写出 Three.js 代码
给 Agent 一张物体参考图，img2threejs 会分阶段生成 Three.js 模型代码，并根据渲染截图反复校准。这里给出可复现的安装与使用流程，并说明单图重建限制、模型格式、Token 成本和图片版权边界。
以前想把一张产品图做成可旋转、可交互的 3D，通常要进 Blender 建模，或者交给图生 3D 服务生成网格。生成结果能不能改、零件能不能动、材质怎么调，往往要等文件拿回来才知道。
img2threejs 走了另一条路。它让 Agent 观察参考图，拆出结构和材质，再编写 Three.js TypeScript 代码。成功完成实现路线后，会得到一个 THREE.Group 工厂函数，可以放进网页项目继续改，还能暴露 pivot 、 socket 和碰撞代理等元数据，供宿主项目接入动画或物理系统。
截至 2026 年 7 月 30 日，GitHub 仓库已有 8,125 Stars，当前正式版本为 v1.4.3 。
我把 v1.4.3 拉到本地，按 CI 同款命令运行仓库的 Python 测试集：
python3 -m unittest discover -s forge/tests
263 项测试全部通过。这里没有覆盖生成 TypeScript 的实际构建、浏览器渲染、三种宿主的集成兼容性，也不能代替对每个 3D 成品的视觉验收。
它生成的是代码模型
成功完成实现路线时，核心工程产物是一份 ObjectSculptSpec JSON 和一个 TypeScript 工厂函数：
createObjectNameModel(spec, options): THREE.Group
模型由 Three.js primitives 、程序化几何、材质和生成纹理组成。代码可以放进 Git 管理，参数、零件和材质也容易继续修改。流程还会留下 Pre-Spec Assessment 、渲染截图、 comparison sheets 和 review history 。输入不足时，它也可能只返回分析、请求补图或停止。
它不会直接交付 GLB 、 OBJ 、 STL，也不会从照片里提取一个现成 mesh 。 3D 打印导出、 Unity/Unreal 导出和 Blender bridge 仍在路线图中。
这决定了它更适合网页 3D 、交互展示、游戏原型和可动画道具。只想拿到一个通用模型文件导入任意 DCC 软件，当前版本还要自己补导出链路。
一张图会经历哪些步骤
通用物体的默认核心 build passes 是：
blockout
→ structural-pass
→ form-refinement
→ material-pass
→ surface-pass
→ lighting-pass
→ interaction-pass
→ optimization-pass
第一轮搭出大体积和轮廓，后续再补结构、表面和材质。每轮都会渲染并截图，再与参考图合成对照图。视觉 Agent 检查比例、轮廓和局部特征，再决定继续、调整规格或代码、补充输入，或停止。人物和 CS2 专用路线会插入额外阶段与门禁。
Python 负责可确定的探测、 JSON 校验、像素诊断、门禁、比较图和状态管理；Agent 负责语义图像分析、规格撰写、视觉判断和代码修改。确定性硬门禁失败时，VLM 不会被调用。仓库把这套分工称为 deterministic-first 。
这种流程比“一句话生成 3D”慢，但问题更容易定位。耳机盒盖角度不对，可以追到结构阶段；材质过亮，可以回到 material pass；隐藏面信息不足时，流程会要求补图，避免凭空补全。
安装时固定 v1.4.3
仓库历史自动化曾留下 v1.5.0 和 v1.6.0-beta.1 等非治理基线。维护方声明，从受批准的 annotated tag v1.4.3 起，GitHub Releases 才是正式发布记录。
Claude Code 可以这样安装：
git clone --branch v1.4.3 --depth 1 \
https://github.com/img2threejs/img2threejs.git \
~/.claude/skills/img2threejs
git -C ~/.claude/skills/img2threejs rev-parse HEAD
# 预期：9a8ecf129a58c1b557a1f03f7727f6295672cd51
项目文档声明其指令可用于 Claude Code 、 Codex 和 OpenCode，但仓库只给出 Claude Code 的安装目录，也没有三种宿主的兼容测试矩阵。其他宿主的目录、命令发现、图像和浏览器工具能力需要分别确认。
Python 工具链要求 Python 3.10 以上，forge/requirements.txt 没有第三方依赖。生成结果所在的前端项目仍需 Three.js 、 TypeScript 和构建环境；自动截图还依赖宿主的浏览器能力。
安装完成后，建议先在临时 Git 项目里试用。 Agent Skill 会指导宿主读取图片、运行脚本、写 TypeScript 、启动浏览器预览并修改文件。安装 Skill 不会限制宿主 Agent 原有的终端和文件权限。
第一次测试选什么图片
第一张图最好满足这些条件：
- 单个物体，轮廓完整，没有被手或其他物体遮住；
- 纯色或简单背景，物体与背景对比明显；
- 三分之四视角，能同时看到正面和侧面；
- 不要一上来测试透明玻璃、毛发、复杂人物和大场景。
无线耳机、台灯、椅子、玩具车、收纳盒都适合做第一轮。图片必须是自己拍摄、获授权或允许再利用的素材。
单张图片看不到背面和底部。项目会镜像或推断隐藏区域，并记录置信度；它无法保证还原真实尺寸，也无法从一张图恢复完整工程结构。
最短可运行提示词
在 Claude Code 中附上图片，然后执行：
/img2threejs Rebuild this object as a Three.js model,
keep the proportions, angles, and colours.
如果要让结果后续可动画，可以把用途写清楚：
/img2threejs Rebuild the object in this image as a procedural Three.js model.
Keep the visible proportions and silhouette close to the reference.
List the identity-defining details before writing code.
Expose pivots and sockets for parts that should move.
Add root.userData.tick for a subtle looping idle animation.
Run strict-quality gates and show a side-by-side comparison after each pass.
Mark hidden or inferred regions with confidence notes.
提示词里的“可动零件”会改变输出结构。一个耳机盒如果需要开盖，盖子和盒身必须是独立节点，并拥有正确 pivot 。只写“做得逼真”，无法替代这类具体要求。
运行中重点看四份产物
1. Pre-Spec Assessment
它记录物体类别、复杂度和质量要求。复杂物体如果只拆出一个根节点，strict-quality 会阻止继续生成代码。
2. ObjectSculptSpec
这是整个重建过程的结构依据，包括组件层级、材质、灯光、 socket 、 pivot 和重点校验区域。规格漏掉一个部件，后面的代码很难靠视觉修补回来。
3. Three.js Factory
最终模型以 TypeScript 源码交付。检查每个 mesh 是否有可读名称，活动部件是否独立，程序化噪声是否固定 seed 。当前工厂没有可依赖的统一资源销毁契约，集成方还要自行释放 geometry 、 material 和 texture，或为生成代码补充 dispose。
4. Comparison Sheet
每个阶段都应该有参考图与渲染图的并排对照。单张 comparison sheet 是主要 VLM 输入，不等于整个评审只有一个视角。即使全局 AI-vision 分数达标，关键特征、结构覆盖或轨道视角任一硬门禁失败，仍不得继续。
Token 成本估算
项目用 Python 脚本完成确定性校验，并按阶段小步修改，以控制 Token 消耗。仓库没有承诺每次重建都能维持低成本。
docs/TOKEN_COST.md 给出的单物体总成本约为 8 万～18 万模型 Token，角色重建约为 15 万～35 万模型 Token 。文档把它们标为数量级工程估算，参考的是一个经过约 6 次渲染校验的宝箱案例；人物区间沿用 v1.2 生成器的成本模型。不同供应商对图片、缓存、工具调用和 reasoning token 的口径也不一致，不能直接换算成统一费用。
社交演示还加入了另一层编排：主 Agent 负责规划，再调用 Ling-3.0-flash 执行部分任务。cc-ling 包装不属于 img2threejs 仓库，安装 Skill 后也不会自动提供。
演示对象是一把手枪，而 v1.4.3 文档内部对这条路线存在冲突：CHANGELOG 提到 Glock-18 专用 adapter，当前 SKILL.md 又写明 CS2 初始边界只支持 knife，pistol 应停止为 unsupported-family。这段视频可能使用了不同提交、通用物体路线或绕过了严格门禁，不能视为 v1.4.3 手枪路线的可复现证明。
截至模型快照时间，OpenRouter API 仍列出 inclusionai/ling-3.0-flash:free，输入和输出标价均为 0 。演示帖称免费体验截至 8 月 3 日，但 OpenRouter 模型 API 没有对应的到期字段。价格为 0 也不代表无限调用或稳定可用，最终以调用时的模型列表、路由限额和活动规则为准。
实践中可以把跑脚本、改小段代码和整理中间产物交给低价执行模型。结构判断、渲染对照和失败修正如果频繁出错，返工会抵消单次调用节省的成本。
使用时注意三点
把单图重建当成精确扫描
一张图只能约束可见轮廓。隐藏结构、绝对尺寸和内部零件都需要推断。产品级资产最好补充正面、侧面和背面图，并把尺寸写进输入。
只看正面截图
扁平贴图也可能在一个角度看起来很像。项目要求非平面模型至少检查两个轨道视角，用来发现模型被做成薄片、连接件悬空或侧面厚度错误。
直接在重要项目里放开 Agent 权限
Skill 包含大量流程指令和本地脚本。当前 v1.4.3 的 263 项测试通过，仍建议先阅读 SKILL.md 和 forge/，固定版本，在临时分支运行，并用 Git diff 检查它修改了哪些文件。
人物、品牌和游戏素材的边界
项目文档提供人物重建和 projection-first 工作流，也包含地标、相机匹配、去光照和投影描述符等辅助脚本。实际拟合与投影质量仍依赖 Agent 判断和工程补全，不能把它当成成熟的一键人脸重建服务。单图无法保证 100% 相似，仓库也要求输出每个区域的置信度。
Python 脚本可以在本地运行，但完整 Agent 工作流的数据流由宿主、视觉模型、浏览器/MCP 和日志配置共同决定。使用前需要分别核对上传范围、保留期、训练选项和地区合规要求。身份证件、未公开产品、客户样机和私人照片不适合直接投入未核对的云端工作流。
品牌产品、影视角色和游戏皮肤还涉及商标、著作权及游戏资产许可。仓库主项目使用 Apache 2.0，只覆盖仓库自身代码；它不会自动授予参考图片、品牌造型或生成资产的商业使用权。照片投影、游戏纹理和品牌皮肤路线可能把受保护像素直接带进输出，技术上能够提取或投影，不代表获得了复制、再发布或商用授权。
仓库也没有为所有生成结果提供独立的版权保证。重新分发仓库代码或衍生部分时，还要遵守 Apache 2.0 对 LICENSE 、修改声明和署名保留的要求。
适合谁用
img2threejs 适合已经在做 Three.js 、网页互动、游戏原型或产品展示的人。它把“看图拆结构、写代码、渲染对照、继续修正”整理成一套可审计流程，生成结果也能继续进入工程代码库。
设计师只想下载一个 GLB，或者团队需要可直接进入 Blender 、 Unity 的标准资产，当前版本仍要补不少工作。它现阶段最有价值的产物是可读、可改、可版本管理的 Three.js 代码。
如果给它一张图，你最想先做成 3D 的是什么：产品、玩具，还是自己的角色？