img2threejs

img2threejs 是由开发者 Hoài Nhớ（hoainho）发起并持续维护的开源 Agent Skill，核心定位是“不把图片直接变成一坨黑盒网格，而是让 AI Agent 像程序员一样写代码，把一张参考图逐阶段重建成可审阅、可修改、可动画的程序化 Three.js TypeScript 模型”——它不满足于做“图生 3D”的抽卡式工具，而是将分阶段雕刻流水线、AI 视觉自校正循环、几何门禁、确定性脚本校验、ObjectSculptSpec 规格、运行时层级（Pivot/Socket/Collider）、角色骨骼绑定整合于一套完整的工程化体系中。全部配有 npx img2threejs@latest 一行安装、Claude Code / Codex / OpenCode / Hermes 多宿主兼容、官方在线 Demo Gallery，以及 Apache-2.0 开源协议。

一、img2threejs 是什么

img2threejs 采用 “Agent 判断 + 脚本强制 + 分阶段雕刻” 的三层架构，通过 GitHub 完全开源发布，采用 Apache-2.0 许可证。项目由 Hoài Nhớ（hoainho）发起，当前 Skill 版本 2.0.0，在 GitHub 上获得约 8.7k Star、659 Fork。它的核心主张极其明确：reconstruction-by-code，而不是摄影测量、网格提取或下载美术包。你给它一张物体或角色的参考图，它产出的不是 .glb 或 .obj 文件，而是一个用 TypeScript 编写的 THREE.Group 工厂函数——从基础几何体、程序化着色器和生成几何体出发，把图中的对象用代码一行一行重新构建出来。

它的运作机制与市面上所有“图生 3D”工具都有本质区别。大多数图生 3D 工具的输出是一个黑盒网格——你得到的结果很难回答三个问题：它为什么长这样？哪一部分错了？下一步应该改哪里？。img2threejs 把“建模”拆成一组有门槛的 pass：blockout（整体轮廓与比例）→ structural（主要部件与连接关系）→ form / material / surface（形体、PBR 材质、表面细节）→ lighting / interaction（可信渲染、Pivots/Sockets/Colliders）→ optimization（轻量化与 LOD）。每一关都必须有真实浏览器渲染、与参考图的并排对比、Agent 视觉判断——没通过就只能 refine-spec、refine-code、request-input 或停止，不会假装已经完成。

二、img2threejs 能做什么

分阶段雕刻流水线与硬门禁（雕） ——不是“一次生成一个网格”，而是“像雕塑一样一层一层剥出来”。流水线先跑适合性判断（视角、清晰度、遮挡是否合适），再做Pre-Spec 评估（对象类别、复杂度、质量契约），写出 ObjectSculptSpec（部件层级、材质、连接关系、可动节点），然后逐 pass 生成代码、渲染、对比、评审。几何门禁在浏览器渲染之前就跑——秃斑（bald patch）或自相交（self-intersection）在点云阶段就被发现，绝不为已经错的几何浪费一次渲染。

Agent 视觉自校正与确定性脚本强制（校） ——不是“让模型自由发挥然后祈祷”，而是“脚本强制，模型判断（Scripts enforce, the model judges）”。Python 脚本负责状态推进、规格校验、几何门禁、证据打包和对比表生成；Agent 只负责解释参考图、生成当前阶段代码和评审渲染结果。路由在置信度低于 0.82 时会主动拒绝，而不是猜“这是武器还是角色”。确定性检查与视觉评审组合成流程门，避免仅凭一次生成就把模型判为完成。

ObjectSculptSpec 与可审阅的代码产物（规） ——不是“黑盒二进制”，而是“规格 JSON + TypeScript 工厂 + 分阶段对比证据”。ObjectSculptSpec 记录组件、材质、重复结构、连接点等信息；TypeScript 工厂返回 THREE.Group，包含运行时层级（Pivot、Socket、Collider），使结果直接可用于动画，而不是一团死物。规格和代码都可以进入常规代码审阅与版本管理，适合迭代图形资产。

角色骨骼绑定与动画就绪（动） ——不是“只能做静态道具”，而是“从组件树派生 rig，绑定到共享 Skeleton”。流水线在完成所有 pass 后，会从组件层级自动推导骨架，将 SkinnedMesh 绑定到同一个 Skeleton，输出可直接驱动动画的 Three.js 模型。官方 Demo Gallery 中包含 Rigged Character 和 Dual-Sword Warrior 等角色示例，均可旋转、查看源码。

多宿主兼容与 Token 高效（用） ——不是“只支持某一个 Agent”，而是“Claude Code、Codex、OpenCode、Hermes 都能跑”。通过符号链接让不同宿主共享同一份 checkout，避免代码漂移。项目刻意保持 token 高效——把确定性工作推给脚本，模型 token 只花在真正需要判断的地方。官方还提供了 Live Demo Gallery，每一个模型都是生成代码在浏览器中实时运行，没有网格文件、没有下载，你可以直接 orbit、查看参考图、阅读生成的源码。

三、img2threejs 适合谁用

Web 3D 开发者与 Three.js 使用者 ——需要把一个物体或角色变成浏览器里可交互的 3D 模型，但不想引入外部网格文件或依赖黑盒资产。img2threejs 输出的是 TypeScript 代码，可以直接集成进现有的 Three.js 项目，参与构建和版本管理。

游戏开发者与道具/角色原型设计者 ——需要快速生成可动画的游戏对象、道具或风格化角色原型。官方 Demo 覆盖了刀剑、枪械、耳机、自行车、角色等多种品类，流水线支持从 blockout 到 interaction 的完整 pass，产出带有 Pivot、Socket 和 Collider 的运行时层级。

AI 编码 Agent 的重度用户 ——已经在用 Claude Code、Codex 或 OpenCode，希望给 Agent 增加一项“从图片重建 3D 模型”的能力。安装只需一行 npx，技能本身是 agent-agnostic 的，不绑定单一宿主。

对“黑盒网格”不满意的 3D 创作者 ——受够了图生 3D 工具“给一个看起来像的结果就结束”，但无法审查、无法定位错误、无法增量修改。img2threejs 的规格 JSON、分阶段证据和代码工厂，让每一步都可以被检查和修正。

需要注意的是它不适合谁：如果你需要的是物理校准的机器人仿真资产，img2threejs 明确说明它不等同于此——外观与物理参数必须分开验证；如果你期望“上传图片，等待魔法，下载模型”的一站式黑盒体验，它的分阶段评审和门禁会让你觉得流程过重。

四、img2threejs 的应用场景是什么

Web 页面中的可交互 3D 物体重建场景 ——你有一个产品的参考图，想在官网或落地页里放一个可旋转、可交互的 3D 展示。img2threejs 走完适合性判断 → 规格 → 逐 pass 生成 → 渲染对比 → 通过后交付，你得到的是一段可以嵌进页面的 Three.js 代码，而不是一个需要额外加载的 .glb 文件。

游戏道具与角色原型快速生成场景 ——你需要一个风格化的武器、道具或角色原型，但不想从零手工建模。img2threejs 的 character profile 支持骨骼绑定和 skinning，产出带有运行时层级（Pivots、Sockets、Colliders）的 THREE.Group，可以直接进入动画流程。

“为什么错了、下一步改哪里”的可审查建模场景 ——传统图生 3D 给出一个网格，你不知道哪一步引入了错误。img2threejs 保留完整的 ObjectSculptSpec、每一 pass 的渲染对比表和 state.json 检查清单——你可以回溯到具体 pass，refine-spec 或 refine-code，而不是推倒重来。

Agent 驱动的程序化 3D 资产生成工作流场景 ——你希望把“从图片重建 3D 模型”嵌入到一个更大的 Agent 工作流中，比如自动生成资产、批量处理参考图、与代码审阅流程集成。img2threejs 的脚本门禁、状态文件和规格输出，让它天然适合作为流水线中的一个可检查、可暂停、可恢复的环节。

教学与 Three.js 学习场景 ——官方 Demo Gallery 提供了多个完整示例，每个都可以在浏览器中实时运行、查看参考图和生成源码。对于想学习“如何用基础几何体和程序化着色器构建复杂对象”的开发者来说，这些 Demo 本身就是一份活的教材。

五、img2threejs 为什么值得关注

从“黑盒网格”到“可审阅的代码资产”的认知升维。图生 3D 工具的核心问题不是“生成得不像”，而是生成得无法审查。你拿到一个网格，不知道它为什么长这样，不知道哪一步错了，也不知道改哪里。img2threejs 把产物从“不可读的二进制”换成“可读、可改、可版本管理的 TypeScript + JSON 规格 + 分阶段证据”。在一个“AI 生成即抽卡”的环境里，这种“产物即代码”的设计本身就是稀缺品。

“脚本强制、模型判断”——把确定性工作从模型 token 中剥离。大多数 Agent 工作流让模型做所有事——理解、生成、校验、修复——token 消耗高且不稳定。img2threejs 把状态推进、规格校验、几何门禁、证据打包全部交给 Python 脚本，模型只负责“看图、写当前 pass 的代码、评审渲染”。这种“能交给脚本的绝不交给模型”的工程分工，是它做到 token 高效且行为可预测的核心原因。

几何门禁先于渲染——在错误几何上不浪费一次渲染。这是 img2threejs 架构中最容易被忽略但极其关键的一步：秃斑和自相交在点云阶段就被拦截，而不是等到浏览器渲染出一张图之后再“看感觉”。这意味着每一个 pass 的渲染预算都花在“几何上已经成立”的候选上，失败反馈的定位也更精确。

路由可以拒绝——低于置信度不猜。大多数工具在不确定时会“选一个最可能的”继续往下走。img2threejs 在主体分类置信度低于 0.82 时直接路由到 request-input，明确拒绝在不确定的情况下自由发挥。在一个“AI 倾向于给出自信答案”的时代，这种“敢停下来问”的克制，是可信度的来源。

Apache-2.0 + 8.7k Star + 活跃 Demo Gallery——社区验证与低摩擦可及性。项目采用 Apache-2.0 协议，GitHub 约 8.7k Star、659 Fork。官方 Demo Gallery 中每一个模型都是生成代码在浏览器里实时运行，可 orbit、可查看源码，不是静态效果图。安装只需 npx img2threejs@latest，支持 Claude Code、Codex、OpenCode 和 Hermes 多宿主。