img2threejs/img2threejs

img2threejs – 将单张参考图转换为过程化 Three‑js 模型

是什么

• 一个技能型库，允许大语言模型（Claude, Codex 等）通过单张物体或角色的照片，输出用于在 Three.js 中仅使用基元、过程化着色器和生成的几何体来构建相同内容的 TypeScript 代码。输出是一个准备好进行动画制作的 THREE.Group 工厂——无需网格文件，无需下载。

工作原理

1. 输入 – 将图像输入到 LLM（或任何“agent‑vision”工具）。模型对主体（object, character, …）进行分类，并构建身份特征（倒角、螺丝、磨损、颜色等）的细节清单。
2. 规范生成 – 一个确定性的 Python 脚本（forge/state.py）记录证据清单并创建一个描述几何体、材质和层级的 JSON 规范。
3. 代码合成 – LLM 生成一个 TypeScript 工厂，使用 Three.js 基元、自定义着色器以及可选的体素雕刻轮廓来重建规范。
4. 视觉审查循环 – 在每一轮（布局 → 结构 → 材质 → 表面 …）之后，将渲染结果与参考图进行对比；任何缺失的细节块都会继续推进，直到满足门禁条件。
5. 运行时输出 – 最终代码在浏览器中运行，暴露枢轴点、插槽和 userData，以便模型可以立即进行动画制作。

核心特性

• Token 效率高：只有视觉判断和代码生成会消耗 LLM token；繁重的工作由确定性的 Python 验证完成。
• 领域插件：插件系统（plugin‑cs2, plugin‑character, plugin‑img2glb, …）为特定的资产家族添加了专门的清单和重建规则。
• 质量门禁：每个细节都必须映射到真实的组件；流水线拒绝“发明”隐藏的几何体。
• 多视图轮廓雕刻（可选）：当提供多个视图时，用于基于体素的外壳。
• 实时演示库：一个公开网站展示了数十个生成的模型及其源代码链接。

典型使用场景

• 需要从概念图中获取轻量级、可动画化的 Three.js 模型的游戏资产流水线。
• 快速原型设计 3D UI 元素或产品可视化，无需导出沉重的网格。
• 关于过程化几何体如何逼近真实世界物体的教育演示。
• 扩展 AI agent（Claude Code, Codex, OpenCode）的“重建此物体”的能力。

入门指南

# 将技能克隆到你的 Claude/Codex 技能目录
git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs

# (可选) 安装插件框架和领域插件
npx github:img2threejs/img2 install          # 创建 ~/.img2 并生成 `img2` 启动器
img2 add img2threejs/plugin-cs2               # CS2 武器皮肤规则
img2 add img2threejs/plugin-character         # 动画角色流水线

运行技能（在 Claude Code 或任何可以调用技能的 LLM 中）：

/img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.

该技能将：

1. 分析附带的图像，
2. 产生一个逐步的规范，
3. 生成 TypeScript 工厂，并
4. 显示与原始参考图并排的实时预览。

高级控制 – 你可以在提示词中嵌入显式约束来引导门禁，例如：

/img2threejs Rebuild the subject in this image as a procedural Three.js model.
Fidelity   Hold proportions and silhouette, enumerate bevels, seams, fasteners, wear.
Materials  Derive finish and gradient stops from the pixels, flag colours that won’t tone‑map.
Runtime    Expose pivots ands sockets for moving parts.

每一行都映射到流水线中真实的验证门禁。

查看位置

• 实时演示库：https://img2threejs.io/（每个演示都链接到生成的源代码）。
• 展示库仓库：https://github.com/img2threejs/img2threejs-showcase。
• 架构细节：仓库中的 docs/ARCHITECTURE.md。

许可证 & 社区

• Apache 2.0。
• 欢迎贡献（参见 CONTRIBUTING.md）。
• 由 Atlas Cloud, Tripo, Hyper3D 以及 Ko-fi 页面赞助。

---

简而言之，img2threejs 是一个 AI 增强型流水线，它将单张图片转换为干净、可动画化的 Three.js 代码，并侧重于确定性的验证和可扩展的领域插件。