每日开源 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**Stars685Forks2026.7.15创建Apache 2协议项目名称img2threejsGitHubgithub.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 Pipeline1****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.4SkinnedMesh / 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 期 —