img2threejs

项目简介

img2threejs 是一个开源图像转 3D 项目，可将参考图中的对象重建为用 TypeScript 编写的程序化 Three.js 模型。它从基础几何体、程序化着色器和生成几何生成 THREE.Group 工厂，并加入由枢轴、插槽和碰撞体组成的运行时层级，使模型可直接用于动画。项目画廊展示在浏览器中运行的纯代码演示；确定性 Python 脚本负责校验与门禁，模型 token 主要用于视觉判断和代码生成。

核心功能

• 从单张参考图生成 TypeScript 的 THREE.Group 工厂，使用基础几何体、程序化着色器和生成几何，而不是网格文件。
• 采用从粗模到优化的分阶段雕刻流程，逐轮进行视觉审查，并在身份特征达到阈值前自我修正。
• 支持 object、character 和 hybrid 主题，包含解剖感知角色轨道，以及可选的人脸相似度和多视图轮廓工作流。
• 提供确定性 Python 脚本，用于图像探测、规格校验、材质证据、阶段编排、渲染审查和严格质量门禁。
• 在代码生成前通过细节清单和严格质量门禁，将身份定义细节映射到真实组件或材质。
• 兼容 Hermes、Claude Code、Codex 或 OpenCode，并可通过 character、cs2、environment、hello-cube、img2glb 等领域插件扩展。

适用场景

• 将拍摄对象或角色重建为适用于浏览器 3D 场景、可动画的 Three.js 模型。
• 在实时演示画廊中研究程序化建模示例和生成源码。
• 通过插件增加 CS2 武器皮肤或绑定角色等领域特定重建流程。
• 试验由代理驱动、节省 token 的图像转 3D 流程。

快速开始

• 安装 Node.js 18 或更新版本、Git、Python 3.10 或更新版本，以及 Claude Code、Codex、OpenCode 或 Hermes 等受支持代理之一。
• 运行 npx --yes img2threejs@latest install，将技能链接到检测到的各代理。
• 运行 npx --yes img2threejs@latest doctor，检查受管理安装。
• 重启代理，并向 img2threejs 技能提供参考图，要求按照质量门禁重建为程序化 Three.js 模型。
• 可选：运行 npx --yes @img2threejs/img2@latest install --yes 安装 img2 工具链，再只添加需要的插件，例如 character 或 cs2。

部署与要求

• Node.js 18 或更新版本、Git 和 Python 3.10 或更新版本。
• Claude Code、Codex、OpenCode 或 Hermes 之一作为代理宿主。
• Python 脚本仅使用 Python 3.10+ 标准库，无需额外安装包。
• 插件工作流需要独立的 img2 工具链；私有 environment 插件还需要获得授权的 GitHub 访问权限。

采用前须知

• 许可证：Apache-2.0。在使用、修改或分发项目前，请确认其具体条款。