本页目录

图像转 Three.js 程序化模型工具(img2threejs)

img2threejs · img2threejs/img2threejs

img2threejs 将参考图中的物体重建为纯代码、程序化的 Three.js 模型:它不走摄影测量、网格提取或下载美术资源的路线,而是通过编写代码来重建,并强调质量门控、动画可用与节省 token。仓库工具链为 Python 3.10+ 标准库(forge/script...

★ Stars 21,465 Forks 1,831 License Apache-2.0 更新 2026-11-17

国内开发环境适配

Windows
未知
Linux
未知
macOS
未知
引擎 / 框架:Unity 暂无中文教程标记 未标记站长实测
工具链仅依赖 Python 3.10+ 标准库,无重型编译依赖;但项目需宿主 agent(Claude Code、Codex、OpenCode、Hermes 等)驱动,国内访问相应模型服务与在线画廊可能需自备网络方案。实际环境要求待核验。

中文项目介绍

img2threejs 是一个把参考图里的物体“用代码重建”为 Three.js 模型的开源项目。给它一张物体参考图,它输出的不是一个网格文件,而是一个用 TypeScript 编写的 THREE.Group 工厂函数:模型完全由基础几何体(primitives)、程序化着色器和生成式几何体拼装而成,并附带运行时层级结构(pivot 枢轴、socket 挂点、collider 碰撞体),因此结果天生是“可动画”的,而不是一坨静态模型。

项目的立场很明确:它不走摄影测量、网格提取,也不下载现成美术资源包,而是 reconstruction-by-code(用代码重建)。仓库同时把“质量门控”“动画可用”“刻意节省 token”写进了自己的定位里。许可证为 Apache 2.0,当前版本号 2.0.1,主页与在线画廊是 img2threejs.io。

核心功能

单图输入、代码输出

输入一张参考图,产出 TypeScript 的 `THREE.Group` 工厂函数,模型由基础体、程序化着色器与生成几何组成。

为动画而生

生成结果自带运行时层级(pivots、sockets、colliders),可直接接入动画,而不是一个惰性实体。

与 agent 无关

可在 Hermes、Claude Code、Codex、OpenCode 等宿主中运行。文档中所谓 “agent vision”“agent browser tool”,实际使用的是宿主自身提供的能力——原生图像读取、浏览器 MCP、项目预览,或用户自己提供的截图。

补充说明

在线演示与示例画廊

画廊里每一个模型都是生成的代码,直接在浏览器中运行,没有网格文件,也不需要下载。README 列出的示例覆盖了物体与角色两类主体,例如:

  • Tropical Island —— 纯代码热带岛屿立体模型
  • Man Robot · Segment Color Studio —— 分区配色工作室
  • Snowbound Crossing —— 雪村小游戏
  • Ocean Blue PRS Guitar —— 按实测曲面流动的吉他
  • Groot、Raz(技能特效)、Lee Sin、双剑女角色等角色类重建
  • Starship + Super Heavy、AWP | Medusa V2、★ Talon Knife | Doppler Ruby 等硬表面物件

打开任意一个模型,可以环绕观察、对照它的参考图、并直接阅读生成的源码。画廊源码独立放在 img2threejs/img2threejs-showcase 仓库;README 中的示例表格由 scripts/ci/showcase_table.py 根据画廊的 demos.json 自动生成,“Built with”一栏标注的是每个示例自己 generatedWith 记录中的版本号(没有则显示为“—”)。画廊中也包含仍在开发中的作品。

主体分类与细节准确度

  • 主体分类:每个主体会被归为 object、character 或 hybrid。物体走硬表面管线;角色走解剖感知轨道,关注头身单位比例、面部关键点与姿态,说明文档位于 grimoire/character/reconstruction.md。
  • 细节优先分析:在生成代码之前,流水线会枚举一份 detailInventory,列出真正决定辨识度的小细节——光泽、倒角与圆角、螺丝与铆钉、雕刻或涂装的线条、轮廓、污渍与磨损。每个细节都必须落到一个真实组件或材质条目上,严格质量门控会在清单完整之前阻止生成。分类规范见 grimoire/intake/detail_inventory.md。
  • 对特定人物/角色的相似度:README 还提到存在针对具体人物或角色追求最大相似度的选项,具体机制以仓库文档为准。

工作流程概览

从参考图出发,先做主体识别与细节盘点,通过质量门控后再进入代码生成,最终交付可运行的 Three.js 模型代码。仓库的 “How it works” 章节给出了完整阶段划分与门控标准,grimoire/ 目录下的文档是各阶段的规范来源。需要说明的是,生成效果会受所用 agent 与模型影响,README 未给出量化评测,建议以示例画廊的实际表现作为参考,并在自己的 agent 环境中验证。

快速开始

README 的 Quick start 把上手过程拆成五步:

  1. 安装基础 skill;
  2. 如有需要,再安装插件 harness;
  3. 挑选需要的插件——不要默认全量安装;
  4. 在你的 agent 中执行一次重建;
  5. 审计并维护已安装的内容。

工具链一侧使用 Python 3.10+ 标准库(forge / scripts),运行时一侧是 Three.js,产物为 TypeScript。

进阶用法与 token 效率

“Driving it harder” 章节提供了可直接复制粘贴的提示词,其中包括基于 GLB 参考的路线。仓库把 token 效率作为显式设计目标(“Token-efficient image-to-3D”),并在 “Why it is token-efficient” 一节解释具体做法;由于该部分细节较多,建议直接阅读仓库对应章节,而不是依赖二手描述。

学习建议

这个项目适合三类读者:想了解程序化建模(用基础体与着色器还原物体)的前端/图形开发者;研究 Three.js 场景组织与运行时层级设计的工程师;以及想搭建“agent 驱动的代码生成 + 质量门控”流水线的开发者。建议路径是先打开画廊挑一个与你目标接近的示例,读它的生成源码,再按 Quick start 在自己的 agent 里跑一次最小重建,最后按需组合插件,避免一次性装全套。

开源许可证与版权说明

许可证标识:Apache-2.0。源码、资源与依赖许可可能不同,请以官方仓库为准。本站仅做索引,不托管源码。

相似项目