引言

在 AI 生成内容百花齐放的今天，3D 资产的创建仍然是一个高门槛领域。传统的 photogrammetry（摄影测量）需要多视角照片，AI 网格生成往往输出难以编辑的黑盒文件，而手工建模又耗时耗力。

img2threejs 提供了一条不同的路径：给定单张参考图片，它通过"代码重建"（reconstruction-by-code）的方式，生成一个完全由 Three.js 原语（几何体、材质、光源）拼装而成的、可动画化的 3D 模型。没有导入的网格文件，没有下载的美术资源包——所有东西都是代码，可 diff、可版本控制、可直接在浏览器里运行。

img2threejs 项目提供了运行在 Claude Code、Codex 或 OpenCode 等 AI Agent 环境中的 Skill，利用 Agent 的视觉能力做判断，用纯 Python 标准库脚本做验证，把最贵的模型 Token 只花在"看图决策"这一件事上。

核心功能

1. 单图重建，多类别支持

img2threejs 支持对多种对象类型进行重建：

类型	说明
硬表面物体（Object）	武器、电子产品、载具、建筑等
人形角色（Character）	带解剖学比例约束的 stylized 角色
生物/动物（Creature）	四足、鸟类、翼龙、蛇形等身体计划
混合类型（Hybrid）	同时具备物体和角色特征的复合对象

2. 分阶段质量门控

模型不是一次性生成的，而是按固定顺序逐步雕刻，每步都有独立的接受标准：

模型生成遵循一个明确的、分阶段的流程，每个阶段都有其独立的验收标准：

粗模 (Blockout) → 结构 (Structural) → 形体 (Form) → 材质 (Material) → 
表面 (Surface) → 光照 (Lighting) → 交互 (Interaction) → 优化 (Optimization)

每一步生成后，Agent 会对比参考图与渲染结果，只有评分通过才会解锁下一步。如果失败，Skill 会自我修正——要么细化规格（refine-spec），要么修正代码（refine-code）。

3. 材质与 PBR 管线

• 从参考图裁剪出材质区域，提取 PBR 证据（非逆向渲染，而是推断）

• 支持 candy-coat（阳极氧化/PVD 风格）等特殊材质

• 使用 CIEDE2000 (ΔE00) 做感知级颜色比较

• 每个材质区域必须通过多视角对比门控才能被接受

4. 运行时就绪

生成的 THREE.Group 不是静态摆件，而是带有完整运行时层级：

• Pivots（枢轴）：用于动画

• Sockets（插槽）：用于挂载附件

• Colliders（碰撞体）：用于物理交互

• Destruction groups（销毁组）：用于程序化破坏效果

5. Token 效率设计

这是 img2threejs 最鲜明的工程特色：

• 脚本执行，模型判断：Python 脚本负责所有机械工作（验证、门控、规格编写、对比图打包），模型 Token 只花在"看图说像不像"这一件事上

• 零依赖：纯 Python 3.10+ 标准库，无 pip、无 PIL、无 numpy，PNG 读写用 struct + zlib 实现

• 逐阶段生成：每轮只生成当前解锁的构建阶段，模型不必重复读取整个模型

• 失败前置：严格质量门控在生成任何 Three.js 代码之前就拦截浅层规格，避免浪费 Token

针对特定类型的提示词增强

场景	建议补充
动物（如狗）	This is a creature, not a humanoid — use the quadruped body plan.
特定人物/角色	Maximize likeness: fit the parametric template to the landmarks.
糖果/阳极氧化涂层	The coat is candy-coat, not gem-metal. Keep the hue.
严格质量	Run --strict-quality, and do not advance a pass until the side-by-side review passes.

工作流程详解

阶段一：摄入与评估（Intake）

1. 图片探测 (probe_image.py)：检查图片元数据和技术问题

2. 预规格评估 (new_pre_spec_assessment.py)：分类对象、评估复杂度、输出质量合约

3. 细节清单 (build_detail_inventory.py)：将参考图切片，枚举身份定义性细节（倒角、接缝、螺丝、磨损等）

阶段二：规格编写（Spec）

1. 编写规格 (new_sculpt_spec.py)：根据评估结果生成 ObjectSculptSpec JSON

2. 规格验证 (validate_sculpt_spec.py --strict-quality)：拦截浅层规格，阻止代码生成

阶段三：构建（Build）

1. 逐阶段生成 (generate_threejs_factory.py)：每次只生成当前解锁的构建阶段

2. 浏览器渲染 → 对比图打包 (make_comparison_sheet.py)：生成参考图 vs 渲染图的并排对比

阶段四：审查（Review）

1. Agent 视觉审查：Agent 看对比图，打分

2. 自我修正：未通过则回到阶段二或阶段三修正

3. 重复直到所有阶段通过

适用场景与限制

适合做什么

• 从单张产品图快速生成可交互的 3D 展示模型

• 游戏原型阶段的程序化资产生成

• 需要代码级可控、可版本控制的 3D 内容（而非黑盒网格）

不适合做什么

• 100% 照片级写实：单张图无法揭示隐藏面， unseen 区域只能镜像推断或诚实标注为低置信度

• 复杂有机体高精度重建：角色是 stylized 重建，不是 photoreal likeness

• 脱离 AI Agent 环境独立运行：核心依赖 Agent 的视觉判断能力

硬件要求

• 不需要本地 GPU：AI 分析在云端 LLM 完成，Python 验证脚本纯 CPU 运行

• 浏览器预览需要 WebGL：任何现代电脑的显卡都足够

• 图片格式：JPEG/JPG、PNG（标准库直接解析，无需外部依赖）

前期准备

执行mkdir %USERPROFILE%\.agents\skills\创建通用agent的全局skills目录，%USERPROFILE%是你的用户目录

执行cd %USERPROFILE%\.agents\skills\进入全局skills目录

执行git clone --branch v1.4.3 --depth 1 https://github.com/img2threejs/img2threejs.git克隆1.4.3版本的img2threejs项目，因为1.4.3版本是目前最新的正式治理基线，即经过完整验证流程、可作为生产依赖的正式版本

当前版本状态（截至 2026 年 8 月 20 日）

版本	日期	性质
v1.5.0-beta.1	2026-08-06	Beta 预发布，非治理基线
v1.4.3	2026-07-30	唯一正式治理基线
v1.4.4-beta.2	2026-07-30	Beta 预发布

打开文件管理器可以看到img2threejs项目放在全局skills目录

从网上下载个图片作为测试素材

下载的跨维智能机器人图片

Agent工具使用skills（以opencode为例，其他类似）

在终端执行opencode，然后输入/skills，按下回车

可以看到img2threejs被添加

按下箭头，按下回车键选择img2threejs

会在对话框出现/img2threejs，输入 提示词，比如根据下载/dog.jpg的图片建立3D模型，开始执行

如果出现这种权限框，按下回车选择Allow once，或右箭头选择Allow always，然后回车，因为要读取对应的图片

注意到这个ai模型没有视觉能力，所以需要执行/model选择具备视觉能力的vlm模型，比如MiMmo-2.5、Kimi-3等

切换模型，然后告诉ai继续执行，ai检查到有Python后继续操作

可以看出这个skills不是直接读取jpg图片，需要转png，不过ai会自动处理

部分执行过程

执行结束告诉创建的3D模型的位置及文件说明

文件	用途
index.html	浏览器查看器 —— 直接在浏览器中打开即可查看 3D 模型
createGoldenRetriever.ts	TypeScript 模块 —— 可导入任意 Three.js 项目中使用
object-sculpt-spec.json	完整雕刻规格（部件层次结构、材质、光照）
assessment.json	规格预评估（复杂度、解剖结构、质量承诺）

查看模型：在浏览器中访问index.html对应链接。可以使用鼠标拖拽旋转（轨道控制）、滚动缩放、右键平移。

模型拆解：共 29 个命名部件 —— 躯干、胸部、臀部、颈部、头骨、口鼻部、鼻子、2 只眼睛 + 高光、2 只耳朵、4 条腿（各含上段/下段/爪/趾）、尾巴 + 尾尖、地面。材质：身体毛发（#F5F0E8）、耳部毛发（#E8D5B8）、粉色鼻子、深色光泽眼睛、爪垫。室外日光三光源照明，搭配 ACES 色调映射。

说明：此模型是根据单张参考图片制作的风格化近似。卧姿、比例和颜色分区与参考图一致，但隐藏面（背部、远侧肢体）为近似处理。毛发为平面材质，不包含程序化纤维/丝状几何体。

在终端进入生成3D模型的文件夹，

启动服务方式1（node）：执行npx serve .，输入y，接着按下回车

启动服务，生成链接

启动服务方式2（Python，推荐，启动速度更快）：python -m http.server 3000

访问http://localhost:3000查看3D模型，可以拖动鼠标转换视角，滚轮控制大小，可以看到这次生成结果与原图有较大差别，看起来更像单峰骆驼...

可以通过截图给ai模型反馈，让它继续修改，中间出现过关节错位或断开、嘴巴太长和身体太长等情况，修改了很多次，下面是比较像狗的结果，虽然仍与预期有偏离，可能是模型不够智能或原图中狗的姿势比较特殊难以表现

根据网上下载的跨维智能机器人图来画机器人的3D模型

这是最开始的两张图（第二个点击wireframe可以看清结构2）

中间其中一次调整，头部变成椭球体，还给身体添加logo

 部分执行情况

最后一次比较接近的结果，中间多次纠正腰部问题，比如一个45度俯仰角双关节杆变成两个杆交叉45度、杆的数量变成4、多余的中间圆盘等问题，手部问题也出现过，比如手臂断开、手指异常等，还出现看不到机器人的情况，是因为使用了Object.assign 给灯光设置位置，这可能在Edge等浏览器中失败导致整个脚本崩溃

总结

img2threejs 代表了一种"重建即代码"的 3D 生成范式。它不追求输出一个完美的网格文件，而是输出一段可维护、可审查、可动画化的 TypeScript 代码。通过将机械工作下沉到零依赖的 Python 脚本，把昂贵的模型 （建议用比较智能的多模态模型）Token 保留给真正的视觉判断，它在 Agent 工作流中实现了同寻常的 Token 效率。

如果你已经在使用OpenCode、Claude Code 等 AI 编程助手，并且需要把一张参考图变成浏览器里可旋转、可交互的 3D 模型——img2threejs 可能是目前最"工程化"的选择。

创作不易，禁止抄袭，转载请附上原文标题及链接