img2threejs/img2threejs

img2threejs – 将单张参考图像转换为程序化的 Three.js 代码

项目简介

• 这是一个由 Python 驱动的技能，允许大语言模型代理（如 Claude Code、Codex、OpenCode、Hermes 等）将单张照片中的对象或角色重建为用 TypeScript 编写的 THREE.Group 工厂。生成的代码仅使用图元、程序化着色器和生成的几何体，不包含网格文件或下载的资源。

重要性

• 生成动画就绪、token 高效的 3D 模型，可直接放入 Three.js 场景中。由于输出是代码，因此保持轻量、易于版本控制和调整。
• 内置质量门控管道，枚举所有视觉细节，对照材质注册表进行验证，并且仅在需要视觉判断的部分花费 LLM token。

主要特性

• 代理无关的技能 – 适用于任何可以运行技能的 LLM（Claude Code、Codex、OpenCode、Hermes）。该技能安装到代理的技能库中，并通过简单的提示调用。
• 领域插件 – 针对特定用例的可选扩展（角色绑定、Counter-Strike 2 武器皮肤、私有环境插件等）。插件添加额外的输入契约、绑定检查和审查门。
• 确定性管道 – 多阶段雕刻流程（blockout → structural → form → material → surface → lighting → interaction → optimization），Python 脚本强制执行门控并从保存的状态恢复工作。
• 实时演示画廊 – 公共网站（https://img2threejs.io）展示数十个重建示例，每个示例都附有生成的 TypeScript 源代码链接。
• 开源工具 – 核心技能位于此仓库，展示位于配套仓库，插件是可通过 img2 工具链添加的独立包。

安装

# 将技能安装到所有检测到的代理中
npx --yes img2threejs@latest install
# 按代理验证安装
npx --yes img2threejs@latest doctor

• 需要 Node ≥ 18、Git 和 Python ≥ 3.10。
• 对于 Hermes 用户，按照 README 中的说明将技能链接到活动配置文件。

可选插件工具链

# 安装管理插件的工具链
npx --yes @img2threejs/img2@latest install --yes
# 列出可用插件
img2 plugins
# 添加插件，例如角色绑定
img2 add character --yes

默认不安装插件；只选择你需要的插件。

运行重建

1. 安装后重启代理。
2. 在代理聊天中，附加图像（或提供其路径）并发出如下提示：

   /img2threejs Rebuild the object in ./reference.png as a procedural Three.js model.
   Keep its proportions, silhouette and colours. Follow the quality gates.
   

3. 代理将：
   • 验证图像。
   • 构建细节清单和规格文档。
   • 逐遍生成 TypeScript 工厂。
   • 在隐藏的 Three.js 视图中渲染结果并与参考进行比较。
   • 返回生成的源文件、渲染审查证据和任何置信度分数。

输出

• src/model.ts（或类似名称）文件，导出 THREE.Group 工厂。
• 描述层次结构、材质和任何置信度指标的 JSON 规格。
• 用于视觉审查步骤的渲染截图。

文档与资源

• 架构与门控设计：docs/ARCHITECTURE.md
• 安装指南：docs/INSTALL.md
• 插件系统：docs/PLUGINS.md
• 编写自己的插件：WRITING_A_PLUGIN.md
• 实时演示画廊：https://img2threejs.io

许可证

• Apache 2.0（参见 LICENSE）。

适用人群

• 需要轻量级、可动画资源而无需分发大型网格文件的游戏开发者。
• 偏好代码优先 3D 模型的交互式 Web 体验创建者。
• 探索 LLM 驱动的 3D 生成管道的研究人员。
• 任何希望以确定性、质量控制的方式将照片转换为 Three.js 代码的人。