img2threejs 使用指南

这是一个将单张参考图片重构为纯代码化、程序化且可直接动画交互的 Three.js 3D 模型的开源工具。它属于非传统网格导出或摄影测量，而是采用 “以代码重建（Reconstruction-by-Code）” 的创新方式。

一、平台介绍

1. 定位清晰：项目不是传统网格导出（Mesh Extraction）或摄影测量，而是 “以代码重建（Reconstruction-by-Code）” 的图像转 3D 工具。
2. 核心机制独特：通过 Python 脚本与 AI 视觉模型结合，解析图片后生成干净的 TypeScript / JSON 规范代码，利用 Three.js 原生几何体与材质程序化拼接出 3D 模型。

二、主要功能

1. 纯代码生成（Zero External Mesh）：生成的结果为可直接在浏览器运行的 TypeScript 代码，无须下载大型 .gltf / .obj 静态模型文件。
2. AI 视觉自我纠错与质量把关（Quality-Gated Loop）：在生成过程中自动生成对比图，由 AI 判定渲染结果与原图的匹配度，自动迭代修复材质、光照与几何结构。
3. 带层级结构的动态模型：输出的模型包含完整的层级树、碰撞体（Colliders）、挂载点（Sockets）与旋转轴（Pivots），原生支持动画与拆解功能。
4. Token 节省机制：逻辑校验与状态封装由本地 Python 脚本处理，消耗 AI Token 仅用于视觉比对与代码编写部分。

三、适用人群

1. Web 前端 / Three.js 开发者：适合快速构建轻量化、可代码操控的 3D 网页组件。
2. 独立游戏开发者：可用于生成硬表面道具，如武器、机械、小桌宠、场景小元素等资产。
3. AI Agent 技能使用者：可在 Claude Code、Codex CLI 或 OpenCode 等终端工具中直接调用的专业开发人员。

四、免费 / 付费情况

1. 完全免费且开源：项目采用开源协议，代码托管于 GitHub 仓库 github.com/hoainho/img2threejs。
2. 不存在官方订阅费：作为开源工具，不存在付费订阅或官方定价页面。
3. 成本说明：使用时消耗的仅为您自己调用的 AI 模型 LLM API / Token 成本。

五、如何使用

1. 安装 Skill：将仓库克隆至 AI 助手（如 Claude Code）的技能目录，运行如下命令进行部署：
2. bash

git clone https://github.com/hoainho/img2threejs.git ~/.claude/skills/img2threejs
git clone https://github.com/hoainho/img2threejs.git ~/.claude/skills/img2threejs

1. 环境要求：本地需具备 Python 3.10+（无需额外安装第三方库）。
2. 运行生成命令：在终端或 AI 助手对话框中提供图片路径并输入指令，例如重建特定物体为模型并保持比例与颜色。
3. 自动构建流程：Skill 会自动完成“图像分析 → 编写 Spec 规范 → 分步代码生成 → 比对校准”的全过程，最终输出 TypeScript 源码。

六、注意事项

1. 适用主体类型限制：目前对 “硬表面物体（Hard-surface props）” （如枪械、刀具、耳机、低多边形建筑等）效果最好；复杂人体或生物模型的重构功能仍在陆续完善中。
2. 原图质量要求：请提供轮廓清晰、主体明确的单张参考图片，背景越干净重构精度越高。
3. 代码体积与性能考量：虽然不依赖外部 3D 资产，但非常复杂的模型会生成较长的 TS 代码，建议在项目中进行按需打包处理。