引言在 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、无 numpyPNG 读写用structzlib实现逐阶段生成每轮只生成当前解锁的构建阶段模型不必重复读取整个模型失败前置严格质量门控在生成任何 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图片探测(probe_image.py)检查图片元数据和技术问题预规格评估(new_pre_spec_assessment.py)分类对象、评估复杂度、输出质量合约细节清单(build_detail_inventory.py)将参考图切片枚举身份定义性细节倒角、接缝、螺丝、磨损等阶段二规格编写Spec编写规格(new_sculpt_spec.py)根据评估结果生成ObjectSculptSpecJSON规格验证(validate_sculpt_spec.py --strict-quality)拦截浅层规格阻止代码生成阶段三构建Build逐阶段生成(generate_threejs_factory.py)每次只生成当前解锁的构建阶段浏览器渲染→对比图打包(make_comparison_sheet.py)生成参考图 vs 渲染图的并排对比阶段四审查ReviewAgent 视觉审查Agent 看对比图打分自我修正未通过则回到阶段二或阶段三修正重复直到所有阶段通过适用场景与限制适合做什么从单张产品图快速生成可交互的 3D 展示模型游戏原型阶段的程序化资产生成需要代码级可控、可版本控制的 3D 内容而非黑盒网格不适合做什么100% 照片级写实单张图无法揭示隐藏面 unseen 区域只能镜像推断或诚实标注为低置信度复杂有机体高精度重建角色是 stylized 重建不是 photoreal likeness脱离 AI Agent 环境独立运行核心依赖 Agent 的视觉判断能力硬件要求不需要本地 GPUAI 分析在云端 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.12026-08-06Beta 预发布非治理基线v1.4.32026-07-30唯一正式治理基线v1.4.4-beta.22026-07-30Beta 预发布打开文件管理器可以看到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.tsTypeScript 模块 —— 可导入任意 Three.js 项目中使用object-sculpt-spec.json完整雕刻规格部件层次结构、材质、光照assessment.json规格预评估复杂度、解剖结构、质量承诺查看模型在浏览器中访问index.html对应链接。可以使用鼠标拖拽旋转轨道控制、滚动缩放、右键平移。模型拆解共 29 个命名部件 —— 躯干、胸部、臀部、颈部、头骨、口鼻部、鼻子、2 只眼睛 高光、2 只耳朵、4 条腿各含上段/下段/爪/趾、尾巴 尾尖、地面。材质身体毛发#F5F0E8、耳部毛发#E8D5B8、粉色鼻子、深色光泽眼睛、爪垫。室外日光三光源照明搭配 ACES 色调映射。说明此模型是根据单张参考图片制作的风格化近似。卧姿、比例和颜色分区与参考图一致但隐藏面背部、远侧肢体为近似处理。毛发为平面材质不包含程序化纤维/丝状几何体。在终端进入生成3D模型的文件夹启动服务方式1node执行npx serve .输入y接着按下回车启动服务生成链接启动服务方式2Python推荐启动速度更快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 可能是目前最工程化的选择。创作不易禁止抄袭转载请附上原文标题及链接