img2threejs：把参考图重建为代码级 Three.js 模型的 AI 工作流（10,323★）

项目简介

img2threejs 是一个 AI 驱动的图像→Three.js 代码重建工作流。给一张参考图，它不会输出 OBJ/GLTF 网格或贴图，而是生成由基元几何体、程序化材质组成的 TypeScript 工厂函数 createObjectModel()，返回一个可直接在浏览器运行、可动画化的 THREE.Group。项目核心理念是“代码即模型”：结果可读、可 diff、可版本控制，而非几兆的静态网格文件。

安装要求与快速开始

环境要求

• Python 3.10+（纯标准库，无需 pip 安装）
• Claude Code / Codex / OpenCode（作为 skill 调用）或任意终端
• Three.js 运行时（浏览器即可）

作为 Claude Code Skill 使用

1. 克隆到 skills 目录：

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

2. 贴入参考图，在对话中运行：

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

独立脚本模式（零依赖）

python3 forge/stage1_intake/probe_image.py <image>
python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json
python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts

所有脚本仅使用 Python 标准库，没有 PIL、numpy、Playwright 等依赖。

核心功能

• 代码即模型（Reconstruction-by-Code）：用 Three.js 基元 + 程序化着色器生成工厂代码，而非摄影测量或网格提取。
• 八阶段雕刻流水线：blockout → structural → form → material → surface → lighting → interaction → optimization，每阶段生成后视觉评审，不达标则返回修正。
• 严格质量门控：--strict-quality 在写第一行 Three.js 代码前拦截规格不足的浅请求，避免浪费 token。
• 极致 Token 高效：Python 标准库脚本负责校验、门控、规格生成和比对打包；模型只做一件事——看“参考图 vs 渲染图”对照表并判定通过/打回。
• Agent 无关：在 Claude Code、Codex、OpenCode 中都能作为 skill 运行，也提供独立终端脚本。
• 动画就绪 + 多主题：输出暴露 pivots、sockets、userData.tick，支持硬表面物体、人形角色、四足/禽类/飞龙/蛇形生物以及 CS2 武器家族。

典型使用场景

• 游戏/3D 资产快速原型：给一张枪械、载具或道具参考图，直接拿到能在浏览器里跑、可交互的 Three.js 模型。
• AI 编码助手工作流：作为 skill 嵌入 Claude Code / Codex，贴图即可在对话中完成“重建为代码”，省掉 Blender 建模或网格下载。
• 教学与可视化演示：官方 Live Demo Gallery 展示了从 Glock-18、BMX 自行车到哆啦A梦房子的纯代码重建案例。

推荐理由

img2threejs 的“重建为代码”思路非常克制而实用：把机械重复工作交给纯标准库 Python，把真正的视觉判断留给大模型，从而在 LLM agent 循环中保持 token 高效。八阶段门控设计让输出可预期，README 也诚实地声明了限制——单图无法保证隐藏面精度，硬表面强、角色偏风格化。今天（2026-08-09）仍活跃推送，v1.4.4 正朝 v1.5 角色重建更新。适合已经使用 Claude Code / Codex 的开发者扩展自己的 AI 工作流。

下载地址

• GitHub：https://github.com/img2threejs/img2threejs
• Live Demo Gallery：https://img2threejs.github.io/img2threejs-showcase/
• 开源协议：Apache License 2.0