img2threejs

img2threejs 快速入门：从一张图到可动画的 Three.js 代码模型

这是什么？适合谁？

img2threejs 要做的事一句话说完：给你一张物体参考图，产出一个用 TS 写的 THREE.Group 工厂函数，把这个物体用基础几何体、程序化着色器和生成的几何重建出来（官方仓库）。作者在 README 里刻意把路线写死：「reconstruction-by-code, not photogrammetry, mesh extraction, or downloaded art packs」——不是摄影测量、不是抽网格、不是下载美术包。

这件事为什么值得单独做一个项目？因为图生 3D 的两条主流路线（云端重建出 .glb、或本地跑一个大模型出网格）都有同一个后果：你拿到的是一个二进制块。改不动、diff 不了、没法按参数调、也没法跟代码一起进 Git。img2threejs 换了个方向：模型是代码，所以能读、能改、能 review、能参数化、能按需动画。

它不是一个独立 App，而是一个装在编码 Agent 里的技能（skill）。官方写明支持 Claude Code、Codex、OpenCode、Hermes 四种宿主；技能负责给 Agent 一套固定的施工流程，Python 脚本负责校验和门禁，Agent 只负责「看图判断 + 写代码」。

核心机制：

• 分阶段雕刻流水线：blockout → structural → form → material → surface → lighting → interaction → optimization 八个阶段逐段推进，每一段生成后由 Agent 做视觉复核，不达标就自纠，再进下一段。官方强调脚本只做「验证与门禁」，不打分画面，判断留给模型。
• 细节清单先于代码：动手前先枚举 detailInventory（高光、倒角、螺丝、刻线、轮廓、污渍与磨损这些「决定像不像」的小细节），每一项都必须映射到真实的组件或材质条目；--strict-quality 会在生成任何代码之前把浅规格挡掉。
• 产出带运行时结构：不只是外观。返回的 THREE.Group 上挂着 root.userData.sculptRuntime（节点、插槽、碰撞体、可破坏分组），角色构建还会写 root.userData.rig（骨骼、共享 Skeleton、骨骼顺序与索引表、bound 绑定标志）。
• 纯标准库脚本：所有 Python 脚本零依赖（连 PNG 读写都用 struct + zlib 手写），不需要 pip、PIL、numpy、Playwright。

适合谁：

• 做 Web 3D / Three.js 项目，需要一个能改、能版本控制的模型，而不是一个几 MB 的 glb 的开发者；
• 想让编码 Agent 直接产出「可动画的代码资产」，省掉建模软件与美术包的团队；
• 需要按参数批量生成（同一族物体换尺寸/配色/部件）的场景化内容，例如电商展示、教学演示、小游戏道具。

不适合谁：

• 要求照片级还原、或在没有三维参考的情况下要精确几何的场合——官方自己写得很明白：「A single image cannot reveal hidden sides or guarantee exact geometry」，隐藏面靠镜像推测，不会假装有把握；
• 完全不想装 Node/npm、也不想用编码 Agent 的人——它的最短路径就是一条 npx 命令加一个 Agent。

与站内同类条目的关系：本站目前没有同赛道（图生 3D）条目，最接近的是 AI 视频生成（如 Kling）与 AI 设计类工具，但它们产出的是像素或版式，不是可运行的 3D 代码，不能互相替代。

核验日期：2026-11-02。依据 官网、GitHub 仓库 与 README 当页文本、GitHub 公开仓库指标。

准备工作

• Node.js ≥ 18 + Git + Python ≥ 3.10：官方 Quick start 第一句就写了这三个前置，缺一个都跑不起来。
• 一个编码 Agent：Claude Code、Codex、OpenCode、Hermes 四选一。技能装进去之后，你要做的是「贴参考图 + 提要求」，不是手写 Three.js。
• 一张够清楚的参考图：正面或 3/4 视角、主体完整、别裁掉关键部位。图的质量直接决定重建的可用性。
• 时间预算：先给 30–60 分钟跑通一个简单硬表面物体（杯子、头盔、摩托车）；角色会显著更久，因为要走解剖比例与 landmark 流程。
• 成本预期：项目本身 Apache-2.0 免费，脚本零依赖，真正的成本是 Agent 的模型 token。官方专门写了 TOKEN_COST 文档来控制这件事（分阶段、单张对比图、只解锁当前阶段的代码生成）。

安装与首个重建任务

1. 装基础技能

npx --yes img2threejs@latest install   # 把技能链到它找到的每个 Agent
npx --yes img2threejs@latest doctor    # 每个 Agent 一行，managed 表示已装好

Hermes 用户要额外做一步符号链接（安装器只写 ~/.hermes/skills/，不会写进 profile）：

ln -sfn ~/.hermes/skills/img2threejs ~/.hermes/profiles/${HERMES_ACTIVE_PROFILE:-img2threejs}/skills/img2threejs

装完重启 Agent，否则技能不会出现在上下文里。

2.（可选）装插件框架

只有在需要具体领域插件时才装这一步：

npx --yes @img2threejs/img2@latest install --yes
npx --yes @img2threejs/img2@latest plugins    # 看实时目录

官方插件的公开情况（README 的目录表，采集日期 2026-11-02）：

• character：角色绑定与动画（从 GLB 取骨架、蒙皮条件、片段测量、动作设计、十二项 rig 门禁）；
• cs2：CS2 武器与手套皮肤重建（分类、饰面/材质配方、阻断式复核门禁）；
• hello-cube：把图变成一个确定的 Three.js 立方体，用来验证「合同」是否跑通；
• img2glb：走托管的 TRELLIS 空间，把图变成 GLB 网格；
• environment：私有，需要被授权的 GitHub 访问。

官方明确提醒：不要默认全装。装了哪个插件，它才会贡献对应的清单步骤、证据采集与门禁。

3. 在 Agent 里跑第一次重建

在装好技能的 Agent 会话里贴参考图，然后给一句意图明确的指令，例如：

用 img2threejs 重建这张图里的物体。
只要硬表面，先做到 material 阶段停下给我看对比图。

接下来由技能接管：分类（object / character / hybrid）→ 打复杂度分并给出质量合同 → 产出 ObjectSculptSpec → 校验（--strict-quality）→ 逐阶段生成 → 每阶段出一张「参考图 vs 渲染」对比图给 Agent 判断。

4. 成功判定的标准

别用「看起来差不多」验收，用这三条：

1. 目录里出现 ObjectSculptSpec JSON：含组件树、材质、重复系统、插槽与每一轮的复核记录；
2. 出现 TS 工厂函数 createXxxModel(spec, options)：返回 THREE.Group，且 root.userData.sculptRuntime 里能查到节点/插槽/碰撞体；
3. 对比图能一行行对：把 reference 与 render 并排，逐条核对你给它的 detailInventory（倒角、螺丝、刻线）是否都落到组件上。

官方还留了一句话给验收方：“This cannot reach the requested fidelity from this image” 是合法的输出。当它明确说做不到时，那不是 bug，是该换图或换视角。

初级用法：三个能立刻做完的小目标

目标一：先跑 hello-cube 验证链路。 装插件后 img2 add hello-cube，让它把一张图变成一个确定的立方体。这一步不追求好看，只验证「技能 → 脚本 → 门禁 → 输出」四环都通；装完技能却不能出代码，通常就卡在这里。

目标二：硬表面物体先停在 material。 别一上来要求全流水线。让它在材质阶段停下，看对比图里高光位置、边缘倒角是否对上，再放行后四个阶段（surface / lighting / interaction / optimization）。分阶段看，返工成本最低。

目标三：把产出接进你的 Three.js 场景。 生成的工厂函数是纯几何代码，接进场景只需要三步：import 工厂 → 拿一个 THREE.Group → scene.add()。没有资源加载、没有 CORS、没有贴图路径问题——这也是「代码模型」相对 glb 最实际的收益。

高级玩法

玩法一：用插件把领域知识灌进去。 cs2 这类插件会往流程里注入清单步骤、证据采集与阻断门禁（例如饰品分类与材质配方）。如果你有稳定的垂直品类（枪械皮肤、家居、机械件），照插件结构写自己的规则，比每次靠提示词反复强调更可靠。

玩法二：把 ObjectSculptSpec 当资产版本库。 spec 是 JSON、代码是 TS，两者都能 diff。做法是每个物体一个目录，spec 与生成代码同仓管理；改需求时改 spec、重跑对应阶段，append_review.py 会留下每轮复核记录。这样「上一版为什么更像」是可查的，而不是靠记忆。

玩法三：参数化家族。 同一族物体（不同尺寸的杯子、不同配色的头盔）共用一份 spec 骨架，把可变项抽成 createXxxModel(spec, options) 的 options，再用脚本批量出图对比。硬表面物体收益最大，因为重复系统（阵列、镜像、螺纹）本来就是 spec 里的一等公民。

玩法四：角色走 rig 路线，别指望照片级。 角色构建会产出 root.userData.rig，官方也直说角色是风格化重建、不是照片级相似。要「像某个人」时用投影优先路径（landmark 拟合 + 去光 + 相机匹配 + 投影），并且接受它按区域给置信度、必要时要求更多视角。

常见踩坑

踩坑 1：装完技能，Agent 里根本没有这个技能。 症状：doctor 显示 managed，但会话里让 Agent 用 img2threejs，它说没有该能力。 原因：安装器只写 ~/.hermes/skills/，Hermes 的 profile 目录是另一处。 解决：按 README 的 Hermes 段做符号链接后重启 Agent；不确定就重跑 npx --yes img2threejs@latest doctor 看逐项输出。

踩坑 2：一上来就要「全部做完」，结果每一步都被打回。 症状：Agent 在阶段之间来回自纠，token 烧得很快。 原因：八阶段是逐段门禁，前一段的细节清单没过，后段判据全都建立在错的几何上。 解决：一次只放行一个阶段，先看对比图再进下一段；--strict-quality 会把浅规格挡在代码生成之前，这是省 token 的关键，不要绕过它。

踩坑 3：拿一张只拍到正面的产品图，要求还原侧面与背面。 症状：背面明显「镜像感」，部件位置对不上。 原因：单图信息不足，官方明说隐藏面靠镜像推测。 解决：要么补图（多视角）、要么接受近似并在需求里写清「背面允许推测」，要么换成结构性更强、对称的物体。

踩坑 4：期待的是 .glb，拿到的是代码，不会用。 症状：产出目录里没有模型文件，只有一个 createXxxModel 的 TS 文件。 原因：这是路线差异，不是缺步骤。 解决：需要网格时，插件目录里有 img2glb（走托管 TRELLIS 空间）；需要代码资产时才用主流水线。两条路不要混。

踩坑 5：把「私有插件」当成公开插件装。 症状：img2 add environment 失败或拉不到仓库。 原因：environment 插件需要被授权的 GitHub 访问。 解决：先确认你是否有权限；没有就用基础配置（默认只有 generic 与 character 两个 profile），缺插件时流程会明确报错并指出缺哪个，而不是静默降级。

踩坑 6：模型 token 花在机械活上。 症状：一次重建的消耗远超预期。 原因：没有让脚本承担验证——手工重读整个模型、手工核对 JSON、每轮重新打分。 解决：按官方分工来——脚本做校验与门禁，模型只做「看一张并排图 + 判断通过与否」；一次复核只给一张打包好的对比图，别散着丢十张截图。

踩坑 7：改了模型却不知道哪一版更好。 症状：两版几何都在，但没有可比较的记录。 原因：绕过了复核记录（append_review.py）与对比图打包（make_comparison_sheet.py）。 解决：每轮都留 record：分数、决定、证据。这是它相对「手搓 three.js 场景」的差异点之一。

小技巧

• 先跑 hello-cube：它是官方的「合同练习」，链路通不通五分钟就知道。
• 参考图裁到只剩物体：背景越干净，细节清单越准。
• 需求里直接写清 2–3 个「决定像不像」的细节（例如「顶部两排铆钉」「侧盖有斜切角」），比说「做精细点」有用得多。
• 硬表面优先：官方明确说硬表面强、角色是风格化，选对赛道成功率最高。
• 复核对齐用并排图，不要用记忆里的样子对比——视觉判断必须有一张当轮证据。
• 每个物体单独目录，spec 与代码同仓；换参数只改 options，不重跑全流程。
• 阶段名记住两个就够：material 之前管「形」，之后管「质」。卡住时先判断错在形还是错在质。

常见问题 FAQ

Q1: 它和 Meshy、Tripo 这类「图生 3D」有什么区别？

A: 路线不同。Meshy、Tripo 这类服务产出的是网格文件（glb/fbx），核心价值是「快速拿到一个能导进引擎的模型」；img2threejs 产出的是 TypeScript 代码模型，核心价值是「可读、可改、可 diff、可参数化、天然可动画」。要成品模型走前者，要能进代码仓库的资产走后者。

Q2: 必须有 Claude Code 或 Codex 吗？我只用别的编辑器。

A: 官方写的是四种宿主：Claude Code、Codex、OpenCode、Hermes（Cursor 在安装文档里另有说明）。它不是独立 GUI，本质是「技能 + 脚本」，所以关键是要有一个能读图、能跑命令、能改文件的 Agent 宿主。纯文本编辑器里手写 three.js 不行，那等于自己实现整条流水线。

Q3: 免费吗？会不会偷偷调用付费服务？

A: 项目本身 Apache-2.0，脚本零第三方依赖，模型推理由你自己配置的 Agent 提供——所以「免费」指的是软件，token 费用算在你用的模型上。插件里有需要授权的私有项（environment），那属于另一层访问控制，不是收费墙的描述。

Q4: 生成出来的模型能直接用在我的网站里吗？

A: 能，且这是它的主要用法：产物是 THREE.Group 工厂函数，import 后 scene.add() 即可，无需资源加载器。注意性能：程序化几何的面数取决于 spec 的复杂度和 optimization 阶段是否执行，移动端项目记得跑完优化阶段再上线。

Q5: 支持动画和骨骼吗？

A: 支持，但分两层。物体层给的是运行时结构（sculptRuntime 的节点、插槽、碰撞体、可破坏分组），你可以基于插槽绑部位做程序化动画；角色层需要 character 插件，产出 root.userData.rig（骨骼、共享 Skeleton、bound 标志）。官方明确说角色是风格化重建。

Q6: 一张图能还原到什么程度？

A: 官方给的口径比宣传诚实：可见面按细节清单还原，隐藏面镜像推测，单图不保证 100% 相似。硬表面物体（武器、机械、器皿）效果最好；人脸与复杂角色建议补视角，或接受风格化。

进阶学习建议

想真正把它用顺手，重点不在 Three.js 语法，而在「规格怎么读」与「门禁怎么用」：

1. 先把 docs/ARCHITECTURE.md 读完一遍：八个阶段各自的判据、自纠逻辑、脚本职责都在里面。看懂这一段，你才知道该在哪个阶段提要求。
2. 读 grimoire/intake/detail_inventory.md 与 grimoire/character/reconstruction.md：前者定义「什么算决定身份的小细节」，后者是角色走解剖路线的规范。这两份是你写需求时的词汇表。
3. 对照 stage4_review/ 的五个脚本理解复核闭环：material_views.py 出多角度证据、material_comparator.py 分类偏差、material_feedback.py 做有界修正、material_gate.py 阻断未达标的材质阶段。学会看这些输出，比反复重跑有用。
4. 挑一个有公开参考的物体做对照组：例如官方 gallery 里的 AWP、Starship、Tropical Island——它们各有源码在 img2threejs-showcase 仓库，可以拿自己的产出跟作者版本逐段比对。
5. 把 token 预算当工程指标：docs/TOKEN_COST.md 有分阶段与分轮次的成本拆解。目标不是「一次成功」，而是「每次失败都发生在最便宜的阶段」。

参考链接

• img2threejs 官网（实时 Demo Gallery）
• GitHub 仓库 img2threejs/img2threejs
• README（安装、插件、流水线）
• Showcase 仓库（每个 demo 的生成源码）
• Three.js 官方文档
• 安装文档 docs/INSTALL.md

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。