img2threejs/img2threejs

Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

解决的问题

img2threejs 可以将单个物体或角色的参考图像转换为程序化的 Three.js 模型。与摄影测量或网格提取不同，它使用纯代码几何、基元和程序化着色器重新构建物体，确保结果可直接用于动画，并且对 AI 代理具有极高的 Token 效率。

工作原理

该项目使用了一个将 AI 代理（如 Claude Code）与确定性 Python 脚本相结合的分阶段雕刻流水线。过程遵循严格的构建阶段序列：

  1. Analysis: 系统对主体（物体、角色或混合体）进行分类，并创建定义身份特征（倒角、螺丝、光泽等）的 detailInventory。
  2. Specification: 编写 ObjectSculptSpec JSON，用于定义组件树和材质。
  3. Iterative Sculpting: 模型通过多个阶段构建（轮廓 $ ightarrow$ 结构 $ ightarrow$ 形状精修 $ ightarrow$ 材质 $ ightarrow$ 表面 $ ightarrow$ 光照 $ ightarrow$ 交互 $ ightarrow$ 优化）。
  4. Review Loop: 在每个阶段之后，Python 脚本会生成一份并排对比表（参考图 vs 渲染图）。AI 代理会根据视觉评分审查渲染结果，并决定是 continue、refine-spec 还是 refine-code。
  5. Output: 最终结果是一个 TypeScript 工厂函数，返回一个带有运行时层级结构（枢轴、插槽和碰撞体）的 THREE.Group，用于动画制作。

适用对象

希望无需依赖沉重的网格文件或手动建模，直接从图像生成 3D 资产的开发人员和技术美术师，特别是那些使用 AI 代理来自动化 3D 创建工作流的人员。

亮点

  • Code-only Reconstruction: 生成 TypeScript 代码而非二进制网格文件，使资产具备可对比性（diffable）和版本控制能力。

  • Agent-Agnostic: 适用于任何具有视觉和浏览器工具的代理（例如 Claude Code, Codex）。

  • Token-Efficient: 将机械性任务（验证、PBR 提取、对比打包）卸载到 Python 脚本中，以节省模型 Token。

  • Animation-Ready: 包含带有枢轴和插槽的运行时层级结构，而不是生成静态网格。

  • Strict Quality Gates: 在规范足够详细以匹配物体复杂程度之前，防止进行代码生成。