img2threejs 开源：一张参考图换一段 Three.js 代码，3D 资产能进 Git 能拆能动
随着 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，而是：
• 一份ObjectSculptSpecJSON 结构说明书
• 一个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