每日开源 img2threejs：一张参考图，一段可运行的 Three.js 代码AI 驱动 3D 建模的新范式 —— 不给你网格文件，直接给你代码
每日开源
img2threejs：一张参考图，一段可运行的 Three.js 代码
AI 驱动 3D 建模的新范式 —— 不给你网格文件，直接给你代码
过去十年，“图生 3D” 赛道挤满了摄影测量、神经辐射场和多视角重建的方案。它们有个共同特点：给你一坨网格。
今天这个项目，偏偏不走这条路。它不要 GLB、不要 OBJ、不要 FBX —— 它给你的是一段TypeScript 工厂函数，一段能在浏览器里直接跑、能进 Git 做版本控制、能拆开改参数的可编辑代码。
**⚠️ 声明：**本工具依赖境外公开数据源（GitHub），部分平台在中国大陆需合规网络环境。
这就是img2threejs，一个诞生不到三周就在 GitHub 斩获近 9k Stars 的开源项目。它的核心哲学只有一句话：
Reconstruction by code, not by mesh.
（代码重建，而非网格重建。）
📋 项目速览
**8.9k+**Stars
685Forks
2026.7.15创建
Apache 2协议
项目名称：img2threejs
GitHub：github.com/img2threejs/img2threejs
作者：Hoài Nhớ (hoainho)
定位：AI Agent 驱动的程序化 Three.js 3D 重建流水线
输出：TypeScript 工厂函数 + ObjectSculptSpec JSON
依赖：Python 3.10+ 标准库（零第三方依赖）
宿主：Claude Code / Codex / OpenCode
展示：在线画廊
🎯 它能解决什么问题？
做网页 3D 展示或浏览器游戏的人，都踩过这些坑：
传统 3D 工作流的三大痛点
**资产黑盒化：**GLB/OBJ 是二进制或专有格式，版本控制形同虚设，Git diff 只能看到"一大坨变了"，不知道哪根线动了。
**迭代成本高：**想改个圆角半径或材质反射率？得回到 Blender/Maya，重新导出、重新压缩、重新上传。
**网页加载重：**一个精细模型动辄几十 MB，首屏加载慢得像在拨号上网。
img2threejs 给出的解法很彻底：既然最终要在浏览器里跑，不如直接用代码把模型"写"出来。
它利用 AI Agent 的视觉能力分析参考图，然后用 Three.js 的基础几何体（立方体、球体、圆柱体）、程序化着色器和生成式几何，一行一行把物体"写"成 TypeScript。最终交付的不是一个 50MB 的模型文件，而是一段可能只有几十 KB 的工厂函数。
这意味着：首屏加载极快、完全可读可 Diff、参数化微调零成本。
✨ 核心亮点
1. 代码即模型 —— Git 里能追踪的 3D 资产
img2threejs 的交付物只有两样：
// 1. ObjectSculptSpec JSON —— 结构说明书// 2. createObjectNameModel() —— TypeScript 工厂函数export function createEarbudsModel(spec, options) { const group = new THREE.Group(); const caseGeo = new THREE.BoxGeometry(2, 1.2, 0.8); const caseMat = new THREE.MeshStandardMaterial({ color: 0x1a1a1a, roughness: 0.4, metalness: 0.8 }); const caseMesh = new THREE.Mesh(caseGeo, caseMat); group.add(caseMesh); group.userData.sculptRuntime = { nodes: { caseLid: caseLidPivot }, sockets: { handle: handleSocket }, colliders: [collider], destructionGroups: [group] }; return group; }
整个模型由 Three.js 原生几何体和数学公式动态生成，不需要加载任何外部模型文件或纹理贴图。你可以在 Git 里精确追踪 Agent 把把手加长了多少、把材质反射率调低了多少。
2. 动画就绪的运行时骨架
与导出即死的静态网格不同，img2threejs 生成的模型天生就是动画就绪的。在root.userData.sculptRuntime中，它预先挂载了完整的运行时层级：
**Pivots（枢轴点）：**箱盖铰链、旋转轴心，开箱动画一行代码搞定。
**Sockets（插槽/挂载点）：**手柄握持点、配件挂载位，武器换装系统即插即用。
**Colliders（碰撞体）：**用于实时物理计算，游戏引擎直接对接。
**Destruction Groups（解体组）：**声明哪些部件可以被击碎，爆炸效果零额外工作。
拿到模型的第一天，不需要进 Blender 绑定骨骼，就能直接加动画、加物理、加交互。
3. 八道工序的质量门控 —— AI 也会"自检"
AI 生成最让人头疼的问题是"幻觉"。img2threejs 为此设计了一套严苛的分阶段雕刻管道（Pass-Gated Pipeline）：
1****Blockout（轮廓搭建）
基础体块比例确认，先解决"像不像"的问题。
2****Structural（结构细化）
组件分割、层级关系，盖子是盖子的，锁扣是锁扣的。
3****Form（形态精修）
曲面过渡、倒角/圆角，避免"方盒子冒充精细模型"。
4****Material（材质赋值）
从参考像素推导 finish class 和梯度断点，不是凭记忆瞎猜。
5****Surface（表面细节）
螺丝、铆钉、面板接缝、涂装线条，细节不到位的阶段不能过。
6****Lighting（光照验证）
色调映射验证、环境匹配，确保渲染图和参考图在同一光照语言下对比。
7****Interaction（交互层级）
暴露 pivots、sockets、userData.tick 动画循环钩子。
8****Optimization（性能优化）
几何体和着色器精简，代码洁癖阶段。
每个阶段必须在浏览器里真实渲染、和原图并排对比、通过视觉评分后，下一个阶段才会解锁。如果某个阶段不达标，Agent 会精确修复该层，而不是推倒重来。
4. 极致的 Token 效率
img2threejs 的设计哲学是**“脚本执行，AI 判断”**。所有机械性工作 —— 验证、门控、规格编写、PBR 提取、对比图打包、流水线状态管理 —— 全由 Python 标准库脚本完成，零模型 Token 消耗。
AI 的 Token 只花在真正需要判断力的地方：看一眼对比图，决定 pass 还是 fail。这种设计比传统"每步重读全模型"的方案节省了大量 Token。
硬表面物体（耳机/宝箱/刀具）：~80k–180k tokens / 对象
人形角色（v1.2）：~150k–350k tokens / 对象
每轮渲染审查：~5k–12k tokens（含 vision 对比图）
Python 脚本开销：~2k–5k tokens（近乎免费）
5. 零依赖的确定性管线
整个工具链只需要Python 3.10+ 标准库。不需要 pip install，不需要 numpy，不需要 Playwright。forge/ 目录下的脚本负责流水线执行，grimoire/ 目录存放评分准则和细节分类学。
这种"零依赖"设计意味着：你把代码 clone 下来就能跑，不会因为某个 npm 包版本冲突而崩溃。
⚖️ 与主流方案对比
img2threejs（代码重建）
输出 TypeScript 工厂 + JSON 规格，完全可编辑、可 Diff、动画就绪。适合网页 3D、游戏原型、程序化资产系统。单图输入，硬表面效果最佳。
Meshy / Tripo（神经网格重建）
输出纹理 GLB，随机性强、不可编辑、不透明。适合快速预览，但进不了版本控制，改个参数要重新生成。
传统摄影测量（Photogrammetry）
需要几十张多角度照片，输出高密度网格。精度高但流程重，不适合单图快速原型。
手动 Blender 建模
完全可控、完全可动画，但成本高、周期长。img2threejs 的目标不是取代它，而是在"草图→可运行代码"这个阶段帮你省掉 80% 的时间。
🎮 实战场景展示
官方展示画廊里已经跑了这些案例，全部是实时在浏览器里运行的生成代码，没有任何网格文件：
已验证案例（均含公开 TypeScript 源码）
Sony WF-1000XM3 耳机— 硬表面产品建模，充电盒开合结构完整保留
ISSACA 霰弹枪— 复杂机械结构，多组件层级关系清晰
Gerber 户外刀具— 金属材质渐变、刀刃反光精确还原
Crowned Loot Chest（皇冠宝箱）— 点击 Explode Parts，盖子、包角、锁扣瞬间分离
War-Hauler 卡车— 载具硬表面，多材质分区
哆啦A梦场景模型— 人形角色风格化重建，解剖标志点正确
这些案例的共同特点是：**硬表面、结构清晰、边缘可读。**这也是 img2threejs 目前最擅长的领域。
最适合的场景
网页产品 3D 展示页（可交互、可配置颜色/材质）
浏览器游戏原型（结构化场景代码，带碰撞体和动画挂载点）
程序化资产系统（一族相关对象共享尺寸和材质逻辑）
AI 辅助创意编码（给 Codex/Claude Code 一个受控的重建工作流）
教学演示（代码即模型，学生可以直接读代码学 3D 图形学）
🚀 上手指南
第一步：安装 Skill
# 克隆到 Claude Code Skill 目录git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs
无需 pip，无需 npm。Python 3.10+ 是唯一的系统要求。
第二步：一键重建
在 Claude Code 中，指向一张物体图片，输入：
/img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.
Skill 会自动完成物体分类、细节清单、规格编写和多阶段生成。
第三步：高级控制（可选）
当你对生成结果有更高要求时，可以手动控制 fidelity、materials、runtime 和 gates：
/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.
第四步：手动脚本执行（进阶）
如果你想逐步控制每个阶段，可以直接调用 forge/ 目录下的 Python 脚本：
# 阶段1：图像探测与分类python3 forge/stage1_intake/probe_image.py # 阶段2：预评估与复杂度评分python3 forge/stage2_spec/new_pre_spec_assessment.py “ObjectName” --image --out assessment.json# 阶段2：编写 ObjectSculptSpec 规格python3 forge/stage2_spec/new_sculpt_spec.py “ObjectName” --image --assessment assessment.json --out spec.json# 阶段2：验证规格（严格质量门控）python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality# 阶段3：生成 Three.js TypeScript 工厂python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts
特定场景指令速查
特定人物/角色：Maximize likeness: fit the parametric template to the landmarks…
动物/生物：This is a creature, not a humanoid — use the quadruped body plan…
糖果色/阳极氧化：The coat is candy-coat, not gem-metal. Keep the hue…
快速评估（低成本）：Stay at low effort and skip the presentation composer…
⚠️ 诚实地说，它不擅长什么
项目作者在 README 里非常坦诚地列出了限制，这种诚实反而增加了可信度：
**单张图像无法揭示隐藏面。**被遮挡的部分通过镜像可见面推断，而非伪造为真值。
**复杂有机形态仍是风格化重建。**面部、布料、头发的照片级真实感，目前仍是神经网格重建的领地。
透明材质、松散头发、重度遮挡是弱项主体。
**“无法从此图像达到所需保真度"是合法且预期的结果。**系统会明确告诉你"我做不到”，而不是硬凑一个错的。
最佳主体：硬表面道具（耳机、宝箱、刀具、载具）。边缘清晰、结构分明、材质可读的对象，效果最惊艳。
🗺️ 版本路线图
v1.0：物体管线、分阶段雕刻、渲染对照审查、动画就绪层级
v1.1：细节优先分析、严格质量门控
v1.2：人形角色生成器、解剖学轨道、比例锁定（已发布）
v1.3：相似度最大化（Likeness Maximization）、逐区域置信度报告
v1.4：SkinnedMesh / Morph Targets / glTF 导出
v1.5–v2.0：环境管线、游戏管线、程序化世界、AI Studio
📌 今日总结
img2threejs 最打动我的，不是它的技术有多炫酷，而是它选择了一条反常识但极务实的路。
当所有人都在卷"谁生成的网格更精细、谁的多视角重建更逼真"时，它退后一步问了一个更基础的问题：对于需要在浏览器里跑、需要迭代、需要进版本控制的 3D 资产来说，网格真的是最好的交付形式吗？
它的答案是：代码才是。
一张参考图进去，一段 TypeScript 工厂函数出来。模型在浏览器里实时生成，能拆、能动、能直接进 Git 做版本管理。这不是未来愿景，这是今天就能跑起来的开源工具。
如果你正在做网页 3D 展示、浏览器游戏原型、或者只是想把一张产品图快速变成可交互的 3D Demo，今晚就值得跑一次。
💬 今日互动
你会把 img2threejs 用在哪里？
网页产品展示 · 游戏原型 · 教学演示 · 其他场景
GitHub: github.com/img2threejs/img2threejs
展示画廊: img2threejs.github.io/img2threejs-showcase
— 每天一个值得深读的开源项目 · 第 100 期 —