hoainho/img2threejs · 上手攻略

• 仓库：hoainho/img2threejs
• 链接：https://github.com/hoainho/img2threejs
• 分类：AI 建模 · Three.js · Agent 工具
• 作者：Tom
• 更新：2026-07-25

这是什么

img2threejs 是一个代码驱动式图像→3D 重建工具。它接受一张物体参考图，通过 AI Agent（Claude Code / Codex / OpenCode）驱动一个分阶段质量门控流水线，输出一段 TypeScript Three.js 工厂函数，将该物体用几何体 Primitive、程序化材质和自定义几何重建出来——不是生成 mesh 文件，而是生成可读、可改、可动画的代码。

核心理念：reconstruction-by-code，不是 photogrammetry，不是 mesh 提取，不是贴图包。每一行代码对应一个视觉特征。

官方展示画廊：https://hoainho.github.io/img2threejs-showcase/

解决什么问题

当你有某个物体的照片（比如产品设计、机械零件、游戏道具），想快速得到一个可在 Three.js 中编辑/动画的 3D 模型，但： - 没有该物体的多视角照片做 photogrammetry - 不想要下载的 mesh / 贴图资产 - 希望模型是纯代码、可注入动画、可程序化操控

img2threejs 用"画出来"的方式替代"拍出来"，把重建变成一个结构化的 Agent 工作流，每一步都有截图对比和质量门控。

快速安装

前提条件： - Python 3.10+（纯标准库，无 pip 依赖） - Node.js（用于运行 Three.js 展示页面） - Claude Code / Codex / OpenCode（Agent 驱动层）

克隆本仓库：

git clone https://github.com/hoainho/img2threejs.git
cd img2threejs

克隆展示库（可选，用于预览成品）：

git clone https://github.com/hoainho/img2threejs-showcase.git
cd img2threejs-showcase
npm install
npm run preview   # 本地预览 http://localhost:4173

📌 本仓库本身是 Skill（技能定义）而非应用。运行它的主体是 AI Agent，人类只提供图片和审查判断。

核心用法

典型工作流（完整 8 步）

┌─────────────────┐
│  1. Probe Gate  │  probe_image.py  ── 检查图片元数据
└────────┬────────┘
         ▼
┌─────────────────────────┐
│  2. Pre-Spec Assessment │  new_pre_spec_assessment.py ── 分类+复杂度+质量契约
└────────┬────────────────┘
         ▼
┌─────────────────────────┐
│  3. Detail Inventory    │  build_detail_inventory.py ── 枚举每个细节特征
└────────┬────────────────┘
         ▼
┌─────────────────┐
│  4. Sculpt Spec │  new_sculpt_spec.py ── 写出 object-sculpt-spec.json
└────────┬────────┘
         ▼
┌────────────────────────────┐
│  5. Validate (strict)     │  validate_sculpt_spec.py --strict-quality
└────────┬───────────────────┘
         ▼
┌──────────────────────────┐
│  6. Build Passes (8 阶段) │  orchestrate_passes.py + generate_threejs_factory.py
└────────┬──────────────────┘
         ▼
┌─────────────────────────┐
│  7. Render + Screenshot  │  浏览器预览并截图
└────────┬────────────────┘
         ▼
┌──────────────────────────┐
│  8. Agent Vision Review  │  make_comparison_sheet.py ── 对比评分
└──────────────────────────┘

关键脚本速查

第一步：探测图片

forge/stage1_intake/probe_image.py <image_path>

第二步：预评估（必做）

forge/stage2_spec/new_pre_spec_assessment.py "ObjectName" \
  --image <img> \
  --complexity simple|moderate|complex|ultra-complex \
  --out assessment.json

第三步：细节清单

forge/stage1_intake/build_detail_inventory.py <image> \
  --mode grid-3x3 \
  --out-dir <dir> \
  --out di.json

第四步：生成雕塑规格书

forge/stage2_spec/new_sculpt_spec.py "ObjectName" \
  --image <img> \
  --assessment assessment.json \
  --out object-sculpt-spec.json

质量验证（严格模式）

forge/stage2_spec/validate_sculpt_spec.py object-sculpt-spec.json --strict-quality

生成 Three.js 工厂代码

forge/stage3_build/generate_threejs_factory.py object-sculpt-spec.json \
  --out src/createObjectModel.ts

查看当前 Pass 状态

forge/stage3_build/orchestrate_passes.py status object-sculpt-spec.json
forge/stage3_build/orchestrate_passes.py check object-sculpt-spec.json --pass-id <pass>

生成对比截图表（人工 + Agent 评判用）

forge/stage4_review/make_comparison_sheet.py \
  --reference <img> \
  --render <shot.png> \
  --out cmp.png --json

8 个 Build Passes（按序解锁）

1. blockout — 基础外形/比例
2. structural-pass — 结构件（铰链、分割线）
3. form-refinement — 曲线/倒角细化
4. material-pass — 材质（MeshPhysicalMaterial PBR 参数）
5. surface-pass — 表面细节（纹理、划痕、磨损）
6. lighting-pass — 灯光方案
7. interaction-pass — 交互/动画接口
8. optimization-pass — 性能优化

输出代码示例（来自 Sony WF-1000XM3 案例）

生成的是一个 TypeScript 工厂函数，核心结构：

import * as THREE from 'three';

export interface SonyWf1000xm3Options {
  shadows?: boolean;
}

export function createSonyWf1000xm3Model(options?: SonyWf1000xm3Options): THREE.Group {
  const group = new THREE.Group();

  // Stadium-shaped 充电盒外壳
  const caseGeo = new THREE.ExtrudeGeometry(
    stadiumShape(CASE_LEN, CASE_DEP, R),
    { depth: BODY_H - bevel*2, bevelEnabled: true, bevelSize: bevel, bevelSegments: 4 }
  );
  const caseMesh = new THREE.Mesh(caseGeo, bodyMat);
  group.add(caseMesh);

  // 耳机主体（半球 + 导管）
  const budGeo = new THREE.SphereGeometry(BUD_R, 32, 16, 0, Math.PI*2, 0, Math.PI*0.65);
  const bud = new THREE.Mesh(budGeo, budMat);
  group.add(bud);

  return group;
}

完整代码：https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/sony-wf1000xm3/createSonyWf1000xm3Model.ts

典型适用场景

• 游戏/元宇宙资产：把产品照片变可编程 3D 道具，带 pivot/socket 方便挂载动画
• 电商展示：用照片重建商品 3D 模型，无需 3D 扫描仪
• 机械零件文档：把设备照片转成可测量的 Three.js 模型用于技术文档
• AI Agent 工作流：作为 Computer Use 任务的视觉反馈环节
• 创意概念验证：快速用照片生成"大概像"的 3D 原型，再手工精修

坑与注意

1. 单张照片限制：一张图无法揭示背面几何，管道会明确报告"未知背面"并要求补充视角。强行用单图会得到"风格化重建"而非精确模型。

2. Agent 视觉是核心：脚本只负责流程推进和文件生成，判断重建质量的是 Agent 的视觉审查能力，不是脚本本身。不要让脚本打分。

3. 复杂物体耗时：ultra-complex 物体可能需要 10+ 个 Pass 循环，新手建议从 simple 开始练手。

4. Python 3.10+ 纯标准库：不要 pip install 任何东西到 forge 环境，否则脚本行为可能偏离预期。

5. 人物/人脸专项：人物重建有独立 pipeline（grimoire/character/reconstruction.md），普通物体 pipeline 不适用于角色。

6. Token 效率：强调 token-efficient，但这意味着 Agent 需要较强的推理能力来"脑补"3D 结构，对低能力模型不友好。

7. 严格质量门：--strict-quality 会拒绝浅层规格（只有一个根节点、没有重复系统、没有局部override 的复杂物体），不要绕过它。

与同类对比

核心差异：img2threejs 的产出是代码，不是网格文件。这意味着模型天然是版本可控、可 diff、可复用的，而传统 3D 工具输出的是二进制资产。

一句话推荐结论

如果你想让 AI Agent 从一张照片"画"出一个带 pivot、可挂动画、用代码版本管理的 Three.js 模型，img2threejs 是目前最结构化的重建-by-code 方案——上手门槛高，但输出质量可预期、每步可审查。