img2threejs 架构深度解析：AI 如何高效地从图片“雕刻“3D 模型

本文是 img2threejs 系列的第二篇，深入剖析其管线架构设计、质量门控机制、以及"确定性脚本 + AI 视觉判断"的 Token 高效利用策略。

前言

上一篇我们介绍了 img2threejs 的基本概念和使用方式。这篇文章我们深入它的内部架构------它是如何在保证模型质量的同时控制 Token 消耗的？为什么它选择了"逐 Pass 雕刻"而非"一次性生成"？这些设计决策背后的工程思考是什么？

架构总览：确定性脚本 + AI 视觉判断

img2threejs 的架构哲学可以用一句话概括：

脚本做执行和验证，AI 只做判断和创造

这是它区别于普通"让 AI 一次性生成代码"方式的核心。

┌──────────────────────────────────────────────────────────────┐
│                    确定性脚本层（Python 3.10+）                 │
│                                                              │
│  · JSON Schema 验证        · Pipeline 状态管理                │
│  · 复杂度评估算法           · 对比图拼接                      │
│  · Pass 锁定/解锁          · PBR 参数提取                    │
│  · 细节清单生成框架         · 相机姿态计算                    │
│                                                              │
│  特点：零 Token 消耗、确定性、可复现、纯标准库               │
└──────────────────────────────┬───────────────────────────────┘
                               │ 门控信号（pass/fail/block）
                               │
┌──────────────────────────────▼───────────────────────────────┐
│                       AI Agent 层                             │
│                                                              │
│  · 图片视觉分析（识别结构、材质、细节）                       │
│  · Spec JSON 创作（组件树、材质定义）                         │
│  · Three.js 代码编写                                         │
│  · 渲染截图 vs 参考图的视觉比对判分                          │
│  · 自我修正决策                                              │
│                                                              │
│  特点：消耗 Token、需要视觉能力、创造性工作                  │
└──────────────────────────────────────────────────────────────┘

为什么这样分工？

传统的"让 AI 写 3D 模型"方式通常是：

用户: "帮我用 Three.js 画一个杯子"
AI:   (一次性输出几百行代码)
用户: "不太像，修一下..."
AI:   (重新阅读全部代码 + 重新生成)  ← 每轮都浪费大量 Token

img2threejs 的做法：

脚本: 验证图片 → 合格 ← (0 Token)
AI:   分析图片 + 写 Spec JSON    ← (集中消耗一次)
脚本: 验证 Spec 完整度 → 合格   ← (0 Token)
AI:   写 blockout 代码          ← (只写一小段)
脚本: 拼对比图                  ← (0 Token)
AI:   看对比图 → "轮廓OK"       ← (少量 Token)
脚本: 解锁下一 Pass             ← (0 Token)
AI:   写 material 代码          ← (只写材质部分)
...

Token 效率提升的关键在于：

1. 不重复阅读：每个 Pass 只处理增量代码
2. 不做机械工作：验证、状态管理、图片拼接都交给脚本
3. 早期拦截：规格不够深就不让生成代码，避免浪费

质量门控体系（Gates）

img2threejs 设计了多层门控，确保每一步都达标后才进入下一步：

Gate 1：图片适用性门（Suitability Gate）

# forge/stage1_intake/probe_image.py
# 检查：图片是否能作为 3D 重建的参考？
# 拒绝：模糊、太小、纯平面图案、无法识别为物体的图片

评判标准：

• 是否有明确的 3D 物体
• 分辨率是否足够
• 是否有足够的细节可分析
• 结果：pass / conditional / reject

Gate 2：规格深度门（Strict-Quality Gate）

# forge/stage2_spec/validate_sculpt_spec.py --strict-quality
# 检查：Spec 是否足够详细到可以指导代码生成？

会阻止的情况：

• 复杂物体却只有一个根节点（没有分解子部件）
• 没有定义重复系统（比如栏杆明明是重复结构）
• 没有局部材质覆盖（全部用同一个材质）
• 没有微观细节组件

这个门控的价值是巨大的------一个浅薄的 Spec 会导致后续每个 Pass 都在错误的基础上修修补补，最终白白消耗 Token。不如一开始就拦住，逼 AI 把 Spec 写深。

Gate 3：截图反馈门（Screenshot Feedback Gate）

continue（通过）的条件：

1. 必须有真实的浏览器渲染截图
2. 必须有参考图 vs 渲染图的并排对比
3. AI 视觉判分必须 ≥ 阈值（默认 0.7）
4. 每个关键特征的单独分数也必须达标

这避免了"整体看着像但细节全错"的情况。比如一把刀，整体轮廓分数 0.8，但刀刃形状分数只有 0.3------不通过。

Gate 4：Divine Eye 确定性审核

# forge/stage4_review/divine_eye.py
# 多信号集成审核（不消耗 Token）：
# - IoU（轮廓重叠度）------ 硬门控
# - 比例/对称性 ------ 硬门控
# - pHash / SSIM / edge 匹配 ------ 软信号
# - 只有软信号不确定时才调用 VLM（AI 视觉）

设计精妙之处：大多数明显的"不通过"可以被确定性算法捕获，无需消耗 Token 让 AI 来看。AI 视觉只在"边缘情况"时才被调用。

Gate 5：多角度验证门

# forge/stage4_review/diagnose_render_multi_angle.py
# 检查：从另一个角度看，模型是否仍然是 3D 的？
# 目的：防止"一个贴了纹理的平面冒充 3D 模型"

这解决了一个隐蔽的问题：如果模型只是一张 PlaneGeometry 贴上了参考图片的纹理，从正面看和参考图一模一样（分数满分！），但一旋转就露馅了。多角度门确保模型有真实的 3D 体积。

Gate 6：装配门（Assembly Gate）

# forge/stage4_review/check_part_coverage.py
# 检查：Spec 里定义的每个组件是否都被实际构建了？
# 防止：AI 偷懒把多个部件融合成一个 Mesh

这是唯一一个检查结构 而非像素的门控。一个投影了照片纹理的单一 Mesh 能通过所有视觉门控，但过不了装配门------因为它没有独立的可交互部件。

Pass 系统详解

为什么要分 8 个 Pass？

核心原因：关注点分离 + 渐进式精修

如果让 AI 一次性输出完整模型代码：

• 容易顾此失彼（调材质时把形状搞乱）
• 出错时不知道问题在哪一层
• 修改时可能引入新问题

分 Pass 的好处：

Pass	关注点	典型修改内容
blockout	整体轮廓、比例	几何体类型和 scale
structural	子部件拆分	新增 Mesh、调整 parent-child
form-refinement	形体精确	顶点位置、曲线参数
material	材质准确	PBR 参数、颜色
surface	表面细节	凹凸、纹理、磨损效果
lighting	光照环境	灯光、环境贴图
interaction	可交互性	socket、pivot、userData
optimization	性能	合并几何体、降面

Pass 锁定机制

# forge/stage3_build/orchestrate_passes.py

# 查看当前状态
orchestrate_passes.py status spec.json
# 输出: "current: structural-pass, completed: [blockout]"

# 尝试跳过生成 material-pass 的代码
generate_threejs_factory.py spec.json --pass-id material-pass
# 报错: "build pass 'material-pass' is locked; complete 'form-refinement' first"

这保证了不会跳步------形体都没对就去调材质是浪费时间。

自我修正机制

每个 Pass 审核后，AI 必须做出唯一决策：

决策	含义	触发条件
continue	通过，进入下一 Pass	视觉分数达标
refine-spec	Spec 有问题，回去修 Spec	发现结构性设计错误
refine-code	Spec 没问题，代码实现有误	几何/材质不对
request-input	需要更多信息	看不清、需要另一个角度
stop	不可行，放弃	从这张图无法达到要求的精度

关键设计：refine-spec 和 refine-code 的区分。

很多 AI 编码场景中常见的问题是"在错误的设计上反复修补代码"。img2threejs 强制 AI 思考：是代码写错了，还是一开始的 Spec 就不对？如果是 Spec 的问题，回去改 Spec 然后重新验证，而不是在代码层面绕路。

循环终止保护

# forge/stage4_review/correction_loop.py
# 防止无限循环修正（Token 燃烧保护）
# 终止条件：
# - 成功（通过）
# - 重复缺陷（同一个问题修了两次还在）
# - 振荡（A修成B，B修回A）
# - 分数停滞（修了但分数不变）
# - 硬上限（达到最大轮次）

当检测到 AI 陷入循环时，自动升级为 request-input------告诉用户"我搞不定了，需要你提供更好的参考图或更明确的指示"。

实际 Token 消耗分布

以一个中等复杂物体为例（约 120k tokens 总消耗）：

┌─────────────────────────────────────────────────────────┐
│ 确定性脚本（验证/状态/拼图）        ~3k    (2.5%)     │
│ ■                                                      │
│ 图片分析 + Spec 创作               ~20k   (16.7%)    │
│ ■■■■■                                                 │
│ Three.js 代码编写（所有 Pass 累计）  ~35k   (29.2%)    │
│ ■■■■■■■■■                                            │
│ 渲染审核循环（6轮 × ~10k）          ~62k   (51.7%)    │
│ ■■■■■■■■■■■■■■■■                                    │
└─────────────────────────────────────────────────────────┘

可以看到：

• 审核循环占了一半以上的 Token------这是保证质量的代价
• 脚本层近乎免费------所有机械工作都不消耗 Token
• 代码编写只占约 30%------因为是增量式的，每次只写一小段

零依赖的 Python 脚本设计

img2threejs 的所有 Python 脚本都只用标准库：

# 不需要这些：
# pip install pillow numpy opencv-python playwright ...

# 它自己实现了：
# - PNG 读写（用 struct + zlib）
# - 图片比较（基于像素的 IoU/SSIM）
# - JSON Schema 验证
# - 颜色空间转换（CIEDE2000 色差算法）

这个决策看似极端，但好处明显：

1. 零安装成本 ------Clone 下来就能用，不需要 pip install
2. 无环境问题------不会因为 PIL 版本冲突导致 Agent 卡住
3. Context 不浪费------不需要花 Token 让 AI 调试依赖问题

ObjectSculptSpec 数据结构

Spec 是整个管线的中枢，以下是其核心结构：

{
  "targetName": "Concrete Bridge",
  "objectClass": {
    "primaryDomain": "object",
    "category": "infrastructure"
  },
  "complexityTier": "complex",
  "qualityContract": {
    "targetMinDetails": 12,
    "fidelityFloor": 0.7
  },
  "componentTree": [
    {
      "id": "deck",
      "label": "Bridge Deck",
      "primitive": "box",
      "level": "macro",
      "dimensions": { "width": 20, "height": 0.5, "depth": 8 },
      "transform": { "position": [0, 5, 0] },
      "materialRef": "concrete_weathered"
    },
    {
      "id": "pier_1",
      "label": "Main Pier",
      "primitive": "cylinder",
      "level": "macro",
      "parent": "deck",
      "dimensions": { "radius": 0.8, "height": 5 },
      "transform": { "position": [-6, -2.5, 0] },
      "materialRef": "concrete_smooth"
    }
  ],
  "materials": [
    {
      "id": "concrete_weathered",
      "baseColor": "#7A7A72",
      "metalness": 0.0,
      "roughness": 0.85,
      "surfaceFrequencyBands": [
        { "frequency": 4, "amplitude": 0.3, "pattern": "stain", "role": "weathering" }
      ]
    }
  ],
  "buildPasses": [
    { "id": "blockout", "componentRefs": ["deck", "pier_1", "pier_2"] },
    { "id": "structural-pass", "componentRefs": ["railing_left", "railing_right"] }
  ],
  "reviewHistory": []
}

这个 Spec 是可人工编辑的------你可以在 AI 生成后手动调整参数，然后重新跑 build。

与其他图片转 3D 方案的对比

维度	img2threejs	TripoSR / InstantMesh	NeRF / 3D Gaussian	Photogrammetry
输入	1 张图片	1 张图片	多张图片/视频	大量照片
输出	TypeScript 代码	.glb/.obj 网格	隐式表示/点云	网格+纹理
文件大小	5-50 KB（代码）	1-10 MB	10-100 MB	10-500 MB
可编辑性	极高（代码级）	中（网格编辑）	低	中
动画支持	内置（socket/pivot）	需后处理	不支持	需后处理
精度	风格化/近似	中等	高（多视图时）	最高
运行时性能	最优（原语渲染）	良好	较重	取决于面数
成本	Token 费用	GPU 算力	GPU 算力	时间+设备
离线可用	是（代码生成后）	需要推理	需要推理	是

img2threejs 的独特定位是：代码优先、轻量部署、可编辑可动画。它不追求照片级真实感，而是追求"程序化可控的高质量 3D 资产"。

实际应用场景探讨

场景 1：游戏/Web 轻量 3D 资产

不想引入 .glb 文件（增加打包体积），用 img2threejs 生成纯代码模型，Tree-shaking 后极其轻量。

场景 2：数字孪生大屏中的设备模型

工业场景中，需要在大屏上展示设备的 3D 视图。用设备照片生成 3D 模型代码，比找建模师建模快得多。

场景 3：电商产品 3D 预览

商品图片 → 3D 可旋转预览，不需要每个商品都拍 360° 照片或建模。

场景 4：教育/演示

快速把概念图转为可交互的 3D 示意模型，用于教学演示。

局限性与诚实声明

img2threejs 在文档中多次强调自己的局限：

1. 单视图局限：一张图看不到背面，背面靠推测（镜像可见面），可能不准
2. 不是照片级：程序化原语组合本质上是"风格化重建"，不是扫描级精度
3. 需要 AI Agent ：不是一个可以 npm install 然后调 API 的库，需要 AI 交互式运行
4. 硬表面为主：对有机形态（人脸、动物毛发）效果有限（v1.5 改进中）
5. 耗时：完整管线 20-40 分钟，不是实时的

项目文档中明确写道：

"This cannot reach the requested fidelity from this image" is a valid, expected result.

这种诚实的态度值得称赞------比起那些宣称"一键生成完美 3D"的工具，img2threejs 选择了透明地告诉你什么能做、什么做不到。

总结

img2threejs 的架构设计体现了几个值得借鉴的工程思想：

1. 分层分工：机械工作交给确定性脚本（免费），创造性工作交给 AI（收费但值得）
2. 渐进式构建：8 个 Pass 逐步精修，比一次性生成更可控
3. 门控驱动质量：在每一步设置关卡，早期拦截问题，避免后期浪费
4. 自我修正但有边界：允许修正但防止无限循环，知道什么时候该"放弃并求助"
5. 零依赖哲学：脚本层不引入任何外部依赖，消除环境问题

这些设计模式不仅适用于图片转 3D，对任何"AI 辅助的多步骤工程管线"都有参考价值。

---

系列完。如果你对 img2threejs 感兴趣，推荐直接在 Claude Code 或 Codex 中试一试------给它一张你手边物品的照片，看看 AI "雕"出来的效果。