本文内容
img2threejs 教程：将图片转成可编辑的 Three.js 代码
产品照片能展示一盏台灯。产品配置器还要让用户换灯罩颜色，并让灯头绕正确的铰链转动。模型里的零件必须能够分开识别，由应用控制。
img2threejs 是一项智能体技能，能根据参考图片，用 TypeScript 重建程序化 Three.js 模型。它为编程智能体提供分阶段的重建流程，产出可检查、可修改的源代码，以及能够支持交互的对象层级。具体约定见 img2threejs 官方仓库。
资料核对日期：。本文依据项目文档及 v2.0.1 版本的生成器源码。台灯示例和验收项目是建议开展的试验；我们没有实际执行图片重建，也没有测量其速度、还原度或成本。
img2threejs.org 明确说明，它是独立运营的托管服务。该网站的 Native Mesh 流程和下载包，不属于本文介绍的 GitHub 技能。
img2threejs 会生成什么？
img2threejs 生成结构化的重建规格文件，以及用于构造 Three.js 对象的 TypeScript。智能体负责视觉判断，脚本负责验证规格、控制各阶段的推进。要显示模型并让用户操作它，仍需接入应用。
流程架构文档列出的顺序是：粗模、结构、形体、材质、表面细节、灯光、交互，最后优化。实际工作可以这样理解：
- 智能体观察参考图，记录能看到的特征和无法确认的部分。
- 把零件、材质及其关系写进规格文件。
- 用代码构建当前阶段的模型，并在浏览器中渲染。
- 将渲染结果与参考图比较，修正问题后再进入下一阶段。
我们检查的 TypeScript 工厂函数生成器会根据目标名称生成函数名。函数接收一个选项对象，返回 THREE.Group；规格内容已编译进源码。生成文件还会导入 Three.js 及其扩展辅助模块，因此模型依然有运行时依赖。
可编辑的 TypeScript 对 3D 网页有什么用？
TypeScript 源码能说明对象如何组装，开发者可以据此修改配置或动画需要控制的零件。采用这套流程前，先用一个真实修改需求验证可编辑性。源码看得懂，不代表现成的控制接口就好用。
生成器通过 root.userData.sculptRuntime 暴露零件映射。运行时层级指南说明了用于运动的枢轴、用于连接附件的挂点，以及碰撞体描述。有碰撞体描述，并不等于应用已接入物理模拟。
| 需要的修改 | 应要求的实现 | 验收时检查什么 |
|---|---|---|
| 改变灯罩颜色 | 通过应用控件操作对应材质 | 其他台灯实例保留各自的颜色 |
| 转动灯头 | 使用命名枢轴，约定旋转轴和运动范围 | 灯罩绕铰链转动，不会脱离连接处 |
| 改变灯臂长度 | 修改规格后重新生成，或专门设计一个几何参数 | 连接位置和比例仍符合目标款式 |
| 选择可购买的配置 | 将场景控件连接到经过校验的应用状态 | 显示的组合与保存的产品款式一致 |
工厂函数不会自动为任意尺寸提供参数。先确定后续修改以规格文件还是手工维护的 TypeScript 为准，否则从旧规格重新生成时，可能覆盖已经修好的部分。
检查实际生成的导出函数后，再把对象加入已有的 scene。下面的文件名和函数名仅用于示意：
import { createDeskLampModel } from "./generated/desk-lamp";
const lamp = createDeskLampModel({ castShadow: true });
scene.add(lamp);这段代码只将构建好的对象加入场景。相机位置、渲染、操作控件和资源清理，仍由应用负责。
如何把 img2threejs 安装到编程智能体？
为一个受支持的编程智能体安装技能，然后重启该智能体。安装指南列出的环境是 macOS 或 Linux，以及 Git、Node.js 18 或更高版本、Python 3.10 或更高版本。运行时版本还必须满足智能体自身的要求。本文检查的安装器不支持 Windows。
npx --yes img2threejs@latest install --host codex
npx --yes img2threejs@latest doctor根据所用智能体，把 codex 换成 claude、opencode 或 hermes。Hermes 还需要完成指南中的 profile 链接步骤。doctor 检查的是安装状态，无法证明模型质量。如果已有技能不由这个安装器管理，导致安装受阻，先检查它所在的路径，再决定如何处理。
这些命令采用文档给出的安装方式，本文没有实际执行。请记录最终安装的技能版本和提交号，因为 @latest 会变化。npm 包清单表明它提供的是安装命令行工具。把这个包加进 Web 应用，并不会得到图片转换 API。
怎样写 img2threejs 提示词？
明确指定目标物体、带名称且可修改的零件，以及检查结果的要求。输入适用性规则倾向于轮廓清楚、主体可辨认的参考图，不支持把精确网格提取或制造级尺寸精度作为交付要求。
下面是我们设计的试验任务。请使用你有权提供的参考图，并将示例中的 400 mm 高度换成实测尺寸。如果侧面和背面会影响使用，就一并提供对应参考图。
使用已安装的 img2threejs 技能处理 ./reference.png。
用 TypeScript 将台灯构建为程序化 Three.js 模型。
目标：浏览器中的交互式产品原型。
约定一个场景单位等于一米，初始姿态的总高度为 0.4 个单位。
底座、灯臂和灯罩要能够分别识别。
为灯罩设置命名枢轴，位置与实际铰链一致。
建模前列出所有推断的表面和尺寸。
如果无法确认必要特征，要求补充其他视角。
保留重建规格文件及生成的源码。
说明导出的工厂函数及其实际支持的选项。
渲染与参考图匹配的视角，以及侧面和背面视角。
展示无纹理视图，避免材质细节掩盖几何错误。
演示一次灯罩换色，以及一次铰链运动。
报告剩余缺陷、依赖项和任何外部资产或调用。
如果约定的交互需要改用其他资产制作流程，先停下并提交评审。细化表面之前，先检查轮廓和铰链。纹理修得再好，也无法纠正错位的铰链。把验收通过的规格和源码放进同一次提交，方便接手的开发者复现修改。
图片转程序化 3D 适合哪些场景？
我们会先选择一个需要独立零件响应用户操作的浏览器原型。台灯就提供了具体的修改任务。先确认重建结果能完成这个任务，再考虑批量制作同类产品目录。
| 目标用途 | 为什么值得评估 | 什么情况需要重新选择方案 |
|---|---|---|
| 交互式产品原型 | 命名零件可用于选择和移动 | 缺失的几何结构妨碍了所需交互 |
| 风格化讲解场景 | 通过源码修改突出解释概念所需的特征 | 近似建模会让人误解实际原理 |
| 早期产品配置器 | 验证产品选项如何改变场景 | 场景无法稳定表达有效的产品款式 |
| 尺寸要求严格或需要形变的资产 | 原型可帮助厘清需求 | 验收要求 CAD 精度、经过验证的拓扑或专业绑定 |
项目的角色相似度工作流可以将参考图像投影到程序化几何体上。因此，输出 TypeScript 本身不能证明流程完全不使用纹理。要检查实际生成模型的依赖。
插件架构将基础流程与专业扩展分开。要让角色按预期运动，仍需检查绑定和形变，不能仅凭对象层级就判定动画可用。
如果你正在选择整套游戏资产制作流程，可以阅读面向游戏开发的 AI 3D 生成器比较，其中讨论了工具选择、拓扑和引擎交付。
生成结果能导出 GLB 或交给 Blender 吗？
Three.js 可以将场景导出为 GLB，但验收前应在 Blender 或实际目标工具中检查结果。官方导出器文档列出了支持的场景数据和扩展。导出文件不会保留构建场景的 TypeScript 程序。
导入后，检查材质、动画和缩放比例。自定义着色器与应用逻辑需要另外处理。导出资产时保留源码：GLB 仍可在合适的工具中编辑，而程序化源码提供了另一种维护方式。
可选的 img2glb 插件使用托管 TRELLIS 服务从图片生成网格，有独立的网络和依赖要求。它是另一条生成流程，并不是将程序化工厂函数的结果导出成文件。
生成的 3D 模型上线前要检查什么？
把 img2threejs 的输出放进目标应用，用用户实际需要完成的操作来验收。参考视角相似，仍可能藏着错误的背面或枢轴。项目的自我修正指南也提醒：通过二维图像比较，不足以证明三维模型真实可信。
下表是建议执行的检查，不是已通过的测试报告。开始前先约定设备和性能预算，再记录观察结果与未解决的缺陷。
| 检查项 | 具体操作 | 保留的证据 |
|---|---|---|
| 形状与尺寸 | 比较参考视角、侧面和背面，核对约定的总高度 | 带标注的截图、尺寸结果及推断区域清单 |
| 几何可编辑性 | 通过约定的维护方式修改一项灯臂尺寸 | 可评审的差异，以及连接处仍然对齐的模型 |
| 材质独立性 | 同时显示两盏台灯，只给其中一个灯罩换色 | 另一盏台灯保持不变 |
| 零件运动 | 让灯头在预期范围内转动 | 正确的铰链轴，以及穿插问题或限制的记录 |
| 产品状态 | 选择、保存并重新加载配置 | 控件和场景显示同一套有效配置 |
| 设备性能 | 在最低性能的受支持设备上加载并操作 | 启动耗时、每帧耗时、绘制调用次数和内存占用，与约定预算对照 |
| 生命周期 | 反复进入、离开并重新打开查看器 | 应用负责的 GPU 资源不会持续累积，控件不会重复创建 |
| 降级方案 | 使用键盘操作，并关闭 3D 显示路径 | 产品信息和配置功能仍然可用 |
Three.js 资源清理指南说明，不再使用的几何体、材质和纹理需要显式释放。只把对象移出场景还不够。要跟踪资源归属，避免释放仍被另一个模型使用的资源。
把这些检查加入针对 AI 生成代码的质量保障流程。几何验收可能遗漏配置保存故障，TypeScript 构建通过也不能证明形状正确。
使用 img2threejs，要算哪些成本？
预算应包含智能体用量、未通过验收的尝试，以及把合格资产接入应用所需的工作。项目的 token 成本文档将其数字明确标为工程估算，我们不会直接用它们作为生产项目报价。
试验中应记录输出、智能体用量、人工投入分钟数和剩余缺陷，再与现有建模流程比较。还原度要按用途判断：内部原型和面向顾客的商品目录，验收标准并不相同。
文件保存在本地，不能证明智能体也在本地处理图片。提供保密产品参考资料前，应确认宿主、模型端点，以及可选插件会发起哪些调用。
什么时候值得试用 img2threejs？
如果浏览器原型的核心需求是控制可编辑零件，而且团队有能力评审重建结果，就值得试用 img2threejs。从一个物体和一项有意义的交互开始。如果产出的源码让下一次已批准的修改更容易实现和验证，再保留这套流程。
从 AI 构建原型走向生产环境的指南可帮助你明确交付边界。Hyperstate AI 案例展示的是相邻领域的 AI 应用经验，并不记录 img2threejs 部署或 3D 建模工作。
如果要交付实际的查看器或产品配置器，可以从我们的交互式 3D 开发服务开始。先讨论一个产品、它需要的交互和目标设备，让试验有明确的验收依据。