img2threejs 安装与使用指南：通过代码从图像重建 3D 模型 | 极客的赛博空间

img2threejs 是一个将单张参考图像转换为 可动画的、代码化的 Three.js 模型 的工具。它通过一个分阶段的“雕刻”流程（从轮廓到结构、材质、表面、光照等），利用 AI 的视觉判断生成 TypeScript 代码，最终在浏览器中呈现为 3D 模型。其核心特点是 Token 效率高（将机械性工作交给脚本，AI 仅用于视觉判断和代码生成）和 质量门控（每个阶段都需通过对比审核）。

1. 前置要求

在使用 img2threejs 前，请确保您的环境满足以下条件：

AI 编程助手：目前主要支持 Claude Code、Codex 或 OpenCode。您需要在其中一种助手中使用此技能。
Python 3.10+：项目中的验证、门控等脚本依赖 Python 标准库。
Git：用于克隆仓库。
（推荐）Three.js 基础概念：理解场景、组、材质等概念有助于更好地使用生成的代码。

2. 安装步骤

这个项目的“安装”实际上是将其放置到您的 AI 助手能够识别的“技能”目录中。

步骤 1：克隆仓库

选择您希望存放技能代码的位置，然后执行：

1	git clone https://github.com/img2threejs/img2threejs.git

步骤 2：链接到 AI 助手的技能目录

项目推荐的做法是建立一个统一的代码仓库，然后通过符号链接指向各个 AI 助手的技能目录，以确保它们使用同一版本，避免不同步。

对于 Claude Code（默认技能目录在 ~/.claude/skills/）：

1 2	# 假设您将仓库克隆到了 ~/projects/img2threejs ln -s ~/projects/img2threejs ~/.claude/skills/img2threejs

对于 Codex（默认技能目录在 ~/.codex/skills/）：

1	ln -s ~/projects/img2threejs ~/.codex/skills/img2threejs

注意：如果您只使用一种 AI 助手，也可以直接将仓库克隆到对应的技能目录下，但使用符号链接更便于管理更新。

步骤 3：验证安装

在您的 AI 助手（如 Claude Code）中，输入斜杠命令 /img2threejs。如果助手能识别该命令，则说明安装成功。

3. 快速开始：生成您的第一个模型

3.1 在 AI 助手中发起请求

在 Claude Code 或 Codex 中，附加或指向一张物体的参考图片，然后输入以下命令：

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

3.2 跟随自动化流程

智能分类与评估：技能会自动对图片中的物体进行分类（物体/角色/混合），并进行详细的细节盘点。
分阶段生成：它会按照 轮廓(blockout) → 结构(structural) → 形态(form) → 材质(material) → 表面(surface) → 光照(lighting) 的顺序，逐阶段生成代码。
质量审核：每个阶段生成后，技能会提供一个参考图与当前渲染图的对比图，由 AI 判断是否通过。只有通过审核，才会进入下一阶段。
产出结果：最终，您会得到一个 TypeScript 文件（如 src/createObjectModel.ts），其中包含一个返回 THREE.Group 的工厂函数，以及一系列记录重建过程的对比图和规范文件。

3.3 更精确的控制

您可以在初始指令中提供更具体的要求，以引导生成过程。例如：

/img2threejs Rebuild the subject in this image.

Fidelity   Hold proportions and silhouette to the reference. Enumerate the identity-defining
           details first — bevels and rounding, panel seams, fasteners — and drop any detail
           you cannot place on a real component.
Materials  Derive the finish class from the reference pixels.
Runtime    Expose pivots for moving parts and a userData.tick for a looping idle animation.
Gates      Run --strict-quality, and do not advance a pass until the side-by-side review passes.

4. 核心脚本与手动工作流（可选）

虽然主要通过 AI 助手驱动，但项目也提供了一系列 Python 脚本，供您手动执行或进行调试。这些脚本位于 forge/ 目录下，无需安装额外依赖。

一个典型的手动流程示例：

# 1. 探测图像基础信息
python3 forge/stage1_intake/probe_image.py <您的图片路径>

# 2. 生成前置评估（分类、复杂度）
python3 forge/stage2_spec/new_pre_spec_assessment.py "模型名称" --image <图片路径> --out assessment.json

# 3. 根据评估生成雕刻规范 (ObjectSculptSpec)
python3 forge/stage2_spec/new_sculpt_spec.py "模型名称" --image <图片路径> --assessment assessment.json --out spec.json

# 4. 严格验证规范（失败则阻止代码生成）
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality

# 5. 根据规范生成 Three.js 工厂代码（若验证通过）
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts

注意：--strict-quality 标记会强制执行严格的质量门控，如果规范不完整或细节缺失，将阻止代码生成。

5. 您将获得什么

ObjectSculptSpec JSON 文件：包含完整的组件树、材质、层级关系和审核历史。
TypeScript 工厂函数：一个可导入的、生成 THREE.Group 的代码文件。
渲染对比图：每个阶段生成的模型与参考图的视觉对比，用于审核。
可动画的运行时结构：生成的 Group 包含 userData.sculptRuntime，暴露了节点、关节（sockets）等，方便进行动画控制。

6. 注意事项与限制

硬表面 vs. 角色：项目对硬表面物体（如武器、电子设备）的重建效果最好。对于角色，当前版本（v1.5 Beta）正在完善中，输出为风格化重建，而非照片级真实感。
单张图片的固有限制：单张图片无法展示物体的隐藏面。工具会诚实地通过镜像可见部分来推断，并标注低置信度区域，而非“捏造”细节。
“无法达到要求”是有效结果：如果图片质量不足或物体过于复杂，工具会明确报告无法达到要求的保真度，这是一个正常的、预期的结果。