img2threejs/img2threejs · 上手攻略

  • 仓库：img2threejs/img2threejs
  • 链接：https://github.com/img2threejs/img2threejs
  • 分类：AI 图像生成 · 3D/Web · Agent 工具链
  • 作者：Tom
  • 更新：2026-07-26

这是什么

img2threejs 是一个代码优先的图像→3D 重建工具。你给它一张参考图，它生成一段 TypeScript 代码，在浏览器里跑出一个 THREE.Group 工厂函数——所有几何体都由原始几何体（BoxGeometry、CylinderGeometry 等）、程序化着色器和生成式几何拼出来，没有 mesh 文件，没有 GLB 下载，产物天然是"代码"而不是"资源包"。

核心定位：不是 photogrammetry（多视角照片重建），不是 diffusion 生成 3D 模型，而是用 AI agent 照着图片手写 Three.js 代码。

输出物包含： - createObjectNameModel() — Three.js THREE.Group 工厂函数，可直接 new THREE.Group() 调用 - ObjectSculptSpec.json — 对象规格说明（部件树、材质、插槽） - root.userData.sculptRuntime — 运行时层级（pivots、sockets、colliders），动画就绪

它是一个 agent skill，设计跑在 Claude Code、Codex 或 OpenCode 里，由 Python 脚本驱动各阶段关卡，AI 模型负责视觉审查和代码生成。

解决什么问题

现有图像→3D 方案大多输出 GLB/GLTF mesh 文件，缺点是： - 不可编辑：你拿到的是一个二进制 blob，改局部要重新导出 - 不可动画：没有语义级别的关节、插槽信息 - 不可信赖：单图推理精度有限，接缝、比例错误难以自动发现

img2threejs 的解决思路是把 3D 重建变成一个规格驱动的编程过程，每一步都有视觉审查门（vision gate），产物是 TypeScript 源码而非二进制——你随时可以打开文件改某个部件的尺寸或颜色。

快速安装

方式一：作为 Claude Code Skill（推荐）

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

然后在 Claude Code 对话里附上一张图片，发起重建：

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

方式二：手动脚本链（Codex / OpenCode）

不需要 Claude Code，直接跑 Python 脚本（在仓库根目录执行，Python 3.10+ stdlib 即可，无需 pip）：

# Stage 1：探测图像可用性
python3 forge/stage1_intake/probe_image.py <image_path>

# Stage 2：预评估 + 生成规格
python3 forge/stage2_spec/new_pre_spec_assessment.py "ObjectName" \
  --image <image_path> --out assessment.json

python3 forge/stage2_spec/new_sculpt_spec.py "ObjectName" \
  --image <image_path> --assessment assessment.json --out spec.json

# 严格质量验证
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality

# Stage 3：生成 Three.js 工厂代码
python3 forge/stage3_build/generate_threejs_factory.py spec.json \
  --out src/createObjectModel.ts

⚠️ 注意：仓库在 2026-07-20 经 PR #9 重构，原 scripts/ 目录已拆分为 forge/（构建脚本）、grimoire/（知识库/评估标准）、docs/（文档）。如果你是老 fork，请拉取最新。

运行时依赖

  • Python 3.10+
  • stdlib only — 不需要 numpy、Playwright 或任何 pip 包
  • Three.js（前端运行时，npm install three 或 CDN 引入）
  • AI agent 环境（Claude Code / Codex / OpenCode，带视觉能力）

核心用法

标准工作流（8 个固定 pass，按顺序）

blockout → structural-pass → form-refinement → material-pass
→ surface-pass → lighting-pass → interaction-pass → optimization-pass

每 pass 结束时 agent 选一个动作：continue | refine-spec | refine-code | request-input | stop。

关键质量门

门 作用
Suitability gate 过滤构图不合格的参考图（无清晰主体、背景杂乱等）
Detail inventory 枚举身份定义细节（光泽、倒角、铆钉、刻线、磨损），缺失则阻断
Divine Eye 多信号评估（IoU / pHash / SSIM / edge / 比例 / 对称性），硬阈值阻断
Component coverage 确保规格中每个部件都有对应几何体，禁止部件塌缩
CS2 review gates 武器类专用：结构证据、map-stripped blockout、厚度/长轴视角验证

生成代码的用法示例

// 引入生成的工厂函数
import { createGlockGhostProtocolModel } from './createGlockGhostProtocolModel';

// 在 Three.js 场景中使用
const model = createGlockGhostProtocolModel();
scene.add(model);

// 访问动画插槽
const slideSocket = model.getObjectByName('slide_socket');
// → 可对 slideSocket 做动画，无需额外绑定

// 查看运行时元数据
console.log(model.userData.sculptRuntime);
// { pivots, sockets, colliders, destructionGroups, ... }

分类管道

工具自动识别对象类型，走不同重建路线：

  • object / hard-surface：刀具、枪械、电子产品、车辆 → 硬表面重建线
  • character：人物 → 解剖感知路线（头部比例、面部标志、姿态）
  • hybrid：混合体
  • CS2 weapon：CS2 游戏资产 → 家族特定部件合同（Glock-18、M9 Bayonet 等）

典型适用场景

  1. Web 3D 可视化：把产品照片变成可交互的 3D 展示，不需要 3D 建模师
  2. 游戏资产快速原型：AI 生成 Three.js 代码，直接嵌入 Phaser/A-Frame/Babylon.js 场景
  3. CLI 游戏/互动媒体：生成程序化 3D 资源，无需打包二进制资产
  4. AI Agent 工作流：作为 agent skill 集成到更大的自动化 pipeline
  5. CS2 自定义道具：游戏社区制作皮肤/武器可视化，输出代码直接集成

坑与注意

⚠️ Token 成本不低

每个对象约 80k–180k 模型 token（hard-surface），角色类 150k–350k。主要成本在渲染审查循环（5–8 轮，每轮 ~5k–12k token）。适合资产数量少、质量要求高的场景，不适合海量批量生成。

来源：仓库 docs/TOKEN_COST.md（工程估算，非实测 benchmark，v1.5 计划实测）

⚠️ 单图有限制

一张照片无法保证 100% 相似度。人物相似度路线（likeness_maximization）会报告每区域置信度，低于阈值时主动请求补充视角。

⚠️ 不适合有机角色

软体/毛发/布料类对象的几何体重建质量不如硬表面工具。

⚠️ 关节和部件需要主动描述

如果没有在 ObjectSculptSpec 中声明接缝/铰链信息，输出会是一个整体 mesh，无法做展开动画。提前规划好部件层级。

⚠️ 输出不是 GLB/GLTF

如果你的管线期待标准 3D 文件格式（Sketchfab、Unity、Blender 导入等），需要额外步骤将代码产物导出为 glTF。仓库 README 提到 glTF export 计划在 v1.4 实现，但当前（v1.4.1）可能仍为规划中。

与同类对比

方案 输出格式 可编辑性 动画就绪 Token 效率 适合场景
img2threejs TypeScript 代码 + THREE.Group ✅ 源码级 ✅ sockets/pivots ~80k–180k Web 3D / agent 工作流
Photogrammetry (RealityCapture 等) GLB/OBJ ❌ 二进制 ❌ 需手动绑定 N/A 实物数字化
TripoSG / Meshy GLB（AI 生成） ❌ 有限 ❌ 需重拓扑 API 计费 快速原型
SDF/NeRF 系列 神经隐式表示 ❌ 不可编辑 ❌ 渲染绑定 高 学术/体积视频
Babylon.js asset creation 手写代码 ✅ 源码级 ✅ 0（纯人工） 有 3D 经验的开发者

核心差异：img2threejs 走"代码即资产"路线，产物天然可版本控制、可 diff、可协同编辑；竞品大多输出二进制产物。

一句话推荐结论

如果你在构建 Web 3D 应用或 AI agent 工作流，需要一张照片就能产出可交互、可动画、可编辑的 Three.js 资源——而非等 3D 建模师——img2threejs 是目前最实际的代码优先方案；只要接受 token 成本和生成轮次的等待时间，它输出的 TypeScript 工厂函数可以直接嵌进你的场景。