开源一周斩获 7.4K Star！一张图片，一段代码，一个能跑能动的 3D 世界！

随着 Three.js、WebGL 等技术的普及，在网页中嵌入 3D 交互已经成为产品展示、在线教育、游戏预览的标配。

但 3D 资产的制作成本和交付方式，仍然停留在传统的工作流里：专业建模师、复杂的软件、体积庞大的二进制文件、难以版本管理的黑盒资产。

整个链条中最贵的不是渲染计算，而是"人"——每一次修改都得回到建模软件，每一次迭代都是一次手动劳动。

有没有可能让 3D 资产变得像普通代码一样？可以被版本控制、可以被参数化调整、可以被 AI 自动生成？

7 月，一个叫 img2threejs 的开源项目在 GitHub 上悄然引爆。它的做法完全颠覆了我们对"图生 3D"的认知：不给你网格文件，直接给你代码。

一张参考图进去，一段可运行的 TypeScript Three.js 代码出来，模型在浏览器里实时生成，能拆、能动、能直接进 Git 做版本管理。

创建不到两周，Star 数已突破 7400+。

项目简介

img2threejs 是由开发者 Hoài Nhớ（hoainho）创建的 AI Agent 驱动的 3D 重建流水线。

它运行在 Claude Code、Codex、OpenCode 等 AI 编程助手之上，利用 Agent 的视觉能力分析一张参考图片，然后用 Three.js 的基础几何体（立方体、球体、圆柱体）、程序化着色器和生成式几何，把图片里的物体写成一段 TypeScript 工厂函数。

核心定位可以用一句话概括：

Reconstruction by code, not by mesh.（代码重建，而非网格重建。）

它不是摄影测量（photogrammetry），不是网格提取（mesh extraction），也不是下载现成的素材包。

它是真正意义上的"代码即模型"——整个 3D 对象都是用代码一行一行构建出来的。

访问它的在线 Demo 画廊 img2threejs-showcase.pages.dev

你会看到耳机、霰弹枪、刀具、宝箱、甚至哆啦A梦小屋等模型。所有模型都是实时在浏览器里运行的，没有任何网格文件需要下载。

点一下"Explode Parts"，宝箱的盖子、金色包角、锁扣和皇冠徽标会立刻分开——因为它们本来就是独立的代码组件，而不是一整坨不可编辑的三角形网格。

核心亮点

亮点一：代码即模型

img2threejs 最革命性的设计，是它的交付物不是 .glb、.obj 或 .fbx，而是：

• • 一份 ObjectSculptSpec JSON 结构说明书
• • 一个 createObjectNameModel() 的 TypeScript 工厂函数

模型完全通过 Three.js 原生几何体和数学公式动态生成，不需要加载任何外部模型文件或纹理贴图。这意味着：

• • 首屏加载极快：没有几十兆的网格需要下载
• • 完全可读可 Diff：可以在 Git 里追踪代码变动，精确知道 Agent 把把手加长了多少
• • 参数化微调：直接修改代码就能调整圆角、颜色、材质反射率

亮点二：动画就绪的运行时骨架

与静态 3D 模型不同，img2threejs 生成的模型天生就是动画就绪的。在生成的 THREE.Group 实例中，root.userData.sculptRuntime 挂载了完整的运行时对象，包含：

• • 枢轴（Pivots）：比如箱子的盖子轴心，能直接控制开合动画
• • 插槽（Sockets）：手柄、握持点、配件挂载点
• • 碰撞体（Colliders）：用于实时物理计算
• • 解体组（Destruction Groups）：声明哪些部件可以在游戏中被击碎

这意味着你拿到模型的第一天，不需要进 Blender 重新绑定骨骼，就能直接给它加动画、加物理、加交互。

亮点三：八道工序的质量网关

AI 生成最让人头疼的问题之一是"幻觉"——生成的模型缺少细节、比例失调、结构错位。img2threejs 为此设计了一套严苛的多阶段质量网关：

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

每一个阶段必须在浏览器里真实渲染、和原图对比、通过视觉评分后，下一个阶段才会解锁。脚本负责执行检查和状态管理，AI 只需要做一件事：看着对比图判断"过还是不过"。

亮点四：极致的 Token 效率

img2threejs 的设计哲学是"脚本执行，AI 判断"。所有机械性的工作——验证、门控、规格编写、PBR 提取、对比图打包、流水线状态管理——全由 Python 脚本完成，而且用的是纯 Python 3.10+ 标准库，零第三方依赖。

AI 的 Token 只花在真正需要判断力的地方：看一眼对比图，决定 pass 还是 fail。这种设计让它比传统的"每步重读全模型"的方案节省了大量 Token。

快速上手

安装方式

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

就这么简单。因为所有脚本都用的是 Python 标准库，克隆下来直接能用。

基本使用

在 Claude Code 中，指向一张物体图片，运行：

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

这行命令就够了。Skill 会自动完成物体分类、细节清单、规格编写和多阶段生成。

进阶使用

当你对生成结果有更高要求时，可以用更详细的指令：

/img2threejs Rebuild the subject in this image as a procedural Three.js model.

Fidelity   Hold proportions and silhouette to the reference. Enumerate the identity-defining
           details first — bevels and rounding, panel seams, fasteners, engraved or painted
           linework, gloss vs matte zones, wear — and drop any detail you cannot place on a
           real component instead of faking it.
Materials  Derive the finish class and gradient stops from the reference pixels, not from
           memory. Flag any colour that will not survive tone-mapping.
Runtime    Expose pivots and sockets for whatever should move, plus a userData.tick for a
           looping idle animation.
Gates      Run --strict-quality, and do not advance a pass until the side-by-side review
           passes. Report per-region confidence for anything the image cannot show.

特殊场景指令

特定人物/角色：

Maximize likeness: fit the parametric template to the landmarks, de-light and camera-match the reference, then project it. Tell me which regions are inferred.

动物/生物：

This is a creature, not a humanoid — use the quadruped body plan and the body-unit proportion system.

糖果色/阳极氧化：

The coat is candy-coat, not gem-metal. Keep the hue; do not let the environment steal it.

快速评估（跳过演示）：

Stay at low effort and skip the presentation composer; I only need the evaluation render.

手动脚本调用

如果你想手动执行每个步骤，可以直接调用 Python 脚本：

# 第一步：图片探针检测
python3 forge/stage1_intake/probe_image.py <image>

# 第二步：预评估与复杂度评分
python3 forge/stage2_spec/new_pre_spec_assessment.py "物体名称" --image <image> --out assessment.json

# 第三步：编写规格文档
python3 forge/stage2_spec/new_sculpt_spec.py "物体名称" --image <image> --assessment assessment.json --out spec.json

# 第四步：验证规格（使用 --strict-quality 启用严格门控）
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality

# 第五步：生成 Three.js 代码
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts

生成的代码示例

生成的 TypeScript 代码结构类似这样：

export function createEarbudsModel(spec: ObjectSculptSpec, options?: any): THREE.Group {
  const group = new THREE.Group();

  const caseGeometry = new THREE.BoxGeometry(2, 1.2, 0.8);
  const caseMaterial = new THREE.MeshStandardMaterial({
    color: 0x1a1a1a,
    roughness: 0.4,
    metalness: 0.8
  });
  const caseMesh = new THREE.Mesh(caseGeometry, caseMaterial);
  group.add(caseMesh);

  group.userData.sculptRuntime = {
    nodes: { caseLid: caseLidPivot },
    sockets: { handle: handleSocket },
    colliders: [collider],
    destructionGroups: [group]
  };

  return group;
}

写在最后

img2threejs 的真正价值，远不止图片转 3D这个噱头。

它向我们证明了一件事：3D 资产可以像普通代码一样被审查、被版本控制、被参数化微调。

对于网页产品展示、浏览器游戏、教学演示、交互原型等场景，这种代码资产比一坨不可读的网格文件更有生命力。

当然，它也有明确的边界：单张图片无法还原被遮挡的面，复杂有机形态目前仍是风格化重建，而非专业级写实。

项目作者毫不回避这些限制——"This cannot reach the requested fidelity from this image" 是一个合法且预期的结果。

但正是这种诚实，加上严谨的质量门控和极致的 Token 效率设计，让 img2threejs 在众多图生 3D 方案中脱颖而出。

一张图片，一段代码，一个能跑能动的 3D 世界——就从这里开始。

GitHub：https://github.com/img2threejs/img2threejs

如果本文对您有帮助，也请帮忙点个 赞👍 哈！❤️