img2threejs

img2threejs 是一款专为 AI 智能体（如 Claude Code, Codex, OpenCode）设计的强大技能，它能够将单张参考图像分析并重建为纯代码生成的 Three.js 3D 模型。与传统的摄影测量或网格提取不同，img2threejs 生成的是基于基本几何体、程序化着色器和生成几何体的 TypeScript 工厂函数。这意味着生成的模型不仅轻量、令牌高效，而且完全可编辑、可制作动画，并能直接在浏览器中运行。

核心理念：代码即资产

• 🚫 拒绝黑盒网格：不生成静态的 .obj 或 .gltf 文件，而是生成可读、可维护的 TypeScript 代码 (THREE.Group 工厂)。
• ⚡ 令牌高效：通过程序化重建而非像素级复制，大幅减少上下文占用，适合在 LLM 环境中高效运行。
• 🎬 运行时友好：生成的模型自带层级结构和暴露的枢轴点（Pivots），可直接用于骨骼绑定、idle 动画或交互逻辑，而非一个死板的静态块。

核心功能与技术亮点

🎯 细节优先分析与质量关卡

• 身份细节清单：在生成代码前，系统会列举决定物体身份的关键细节（如螺丝位置、倒角角度、材质过渡）。每个细节必须映射到真实的组件或材质条目，否则严格的质量关卡会阻止生成。
• 分阶段雕刻流程：遵循 体块 → 结构 → 形态 → 材质 → 表面 → 光照 → 交互 → 优化 的严谨流程。每一步都进行视觉审查和自我修正，确保最终渲染结果与参考图高度匹配。
• 确定性验证：使用 Python 脚本进行验证和关卡控制，LLM 仅负责视觉判断和代码生成，确保流程的稳定性和可重复性。

🧬 多主体类型支持

• 硬表面物体：遵循严格的几何构建流程，适用于机械、电子产品、家具等。
• 类人角色：通过解剖学感知的路径处理，支持参数化模板拟合、去光照处理和特征点投影，最大化相似度并报告置信度。
• CS2 武器专项：针对刀具和 Glock-18 等特定系列，使用组件契约进行精确重建，记录绘制区域、投影覆盖率及版本化元数据。
• 生物与动物：支持四足动物身体结构的重建（路线图 v1.4+）。

🛠️ 强化驱动与自定义控制

用户可以通过简单的自然语言指令精细控制生成过程：

• Fidelity（保真度）：强制保持比例和剪影，枚举身份细节。
• Materials（材质）：从参考像素推导 finish class 和渐变，而非依赖模型记忆。
• Runtime（运行时）：暴露移动部件的枢轴点和 socket，添加 userData.tick 用于 idle 动画。
• Gates（关卡）：启用 --strict-quality，只有当并排审查通过时才进入下一阶段。

快速开始

1. 安装

将技能文件夹放入您的智能体技能目录：

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

2. 调用

在 Claude Code 或其他支持的智能体中，附加一张物体图像并运行：

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

3. 手动运行（Python 环境）

如果您希望直接通过脚本运行，需确保已安装 Python 3.10+：

# 1. 图像探测
python3 forge/stage1_intake/probe_image.py <image>

# 2. 规格评估
python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json

# 3. 生成雕刻规格
python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image <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

路线图：从资产到世界

img2threejs 的发展愿景是成为一个从参考图像生成可游玩世界的 AI 游戏资产平台：

• 已发布 (v1.0 – v1.4.1)：覆盖物体、角色、CS2 武器及生物生成器，完善细节分析与质量关卡。
• 近期计划 (v1.5 – v1.6)：增强角色重建（面部、绑定拓扑、混合形状），扩展至环境重建（建筑、街道、植被）。
• 中期目标 (v1.7 – v1.8)：集成 Unity/Unreal 导出器、Blender 桥接，实现自动绑定、蒙皮权重及 Mixamo 兼容。
• 长期愿景 (v1.9 – v2.0)：推出 Web UI 工作室，支持多视图重建、程序化城市生成及语义世界理解，构建完整的插件生态系统。