BAIZE AI RESOURCE

把参考图片中的物体重建为纯代码生成的 Three.js 程序化模型

img2threejs

面向 AI Agent 的 3D 重建 Skill，可根据参考图分阶段生成并校正可动画的 Three.js 程序化模型。

获取资源
img2threejs

资源介绍

img2threejs 是一个以 SKILL.md 为入口的 AI Skill，目标是把参考图片中可见的物体或角色重建为纯代码的程序化 Three.js 模型，而不是走摄影测量、网格提取或下载美术资源的路线。它把重建拆成有序阶段：先校验图片是否适合作为 3D 目标，再评估物体类别与复杂度并写出质量契约，随后产出包含组件层级、材质、灯光、轴心与动作锚点的雕刻规格，最后按 blockout、结构、形体、材质、灯光、交互、优化逐遍构建，每一遍都用截图与参考图比对验证。它通过本地状态文件维护检查清单与纠正循环计数，支持 character、cs2、animated-character 等领域插件扩展强制门禁，并可在 Claude Code、Codex、OpenCode 等宿主中运行。适合需要从单张图片得到可交互、可动画、细节可控的网页 3D 资产的开发者与设计者。

Skill 能力

分阶段雕刻流程

把重建拆为校验、评估、规格、逐遍构建与验证等有序阶段，禁止一次性生成网格，每遍都需截图比对参考图。

本地状态门禁

通过 .img2threejs/state.json 记录步骤、证据与纠正循环次数，next.py 给出下一步命令，硬停止时要求报告原因并请求输入。

领域插件扩展

character 等内置模块与 cs2、animated-character 等已安装插件以相同方式注册，为特定领域追加强制门禁与参考材料。

材质参考库

提供 Three.js 材质与 PBR 的起始先验查找表，要求先分类可见材质区域，再结合图像证据拟合并在受控渲染下验证。

可选视觉适配器

可选用 SAM2 掩码、Depth Anything V2 相对深度与 MediaPipe 面部/姿态关键点作为证据，但需人工确认后才进入规格。

纯标准库核心

forge 核心仅依赖 Python 3.10+ 标准库，PNG 贴图与对比图直接由 struct/zlib 写出，不强制引入第三方依赖。

资源配置

适用平台

Claude CodeCodex通用 Agent

支持模型

模型无关

调用方式

手动调用命令调用Agent调用

安装与调用

  1. 在宿主中把仓库检出目录通过符号链接接入，例如 ~/.claude/skills/img2threejs 或 ~/.codex/skills/img2threejs，使不同宿主执行同一份代码。

  2. 准备一张物体或角色参考图片，并明确用途（道具、游戏物体、主视觉渲染、可交互或可破坏物体、动画绑定等）。

  3. 运行 python3 forge/state.py init 初始化本地状态文件，指定参考图、profile 与雕刻规格文件。

  4. 每次开始、恢复或纠正迭代前运行 python3 forge/next.py --state .img2threejs/state.json，按输出的下一步命令执行。

  5. 完成步骤后用 python3 forge/state.py mark 标记并附上证据路径；不适用步骤需带 --reason 标记为 skipped。

  6. 按 blockout 到优化的顺序逐遍构建，每遍用截图与参考图比对，未通过则进入有上限的纠正循环。

使用案例

从照片重建道具

使用场景需要为网页场景制作一个可交互道具

提供道具参考图并声明用途为实时浏览器道具，按阶段生成程序化 Three.js 模型，逐遍比对截图修正形体与材质。

角色形象重建

使用场景希望尽量还原参考图中的人物形象

选用 character 领域配置，追加角色契约与关键点证据门禁，在材质与比例上按参考图证据逐步拟合。

动画就绪角色

使用场景模型后续需要绑定骨骼并播放动作

安装 animated-character 插件后启用，在角色门禁之外追加九个就绪步骤，先修复网格、冻结、再加性绑定并验证一致性。

材质专项研究

使用场景需要确认某区域材质在 Three.js 中的合理参数

先对可见材质区域分类，再查材质参考库取得有界先验，结合去光照后的图像证据拟合颜色与 PBR 参数，并用受控渲染验证。

包含内容

img2threejs-source.zip
LICENSE-Apache-2.0.txt
README-中文安装说明.md
SHA256.txt

常见问题

img2threejs 会直接输出可下载的模型文件吗？
它的核心承诺是以代码方式重建，生成的是程序化 Three.js 代码而非下载的美术资源；资料显示可通过显式选择的导出目标对已构建模型做整体转换，但该转换不是第二条构建路径。
单张参考图能保证还原出隐藏面的几何吗？
不能。技能要求明确说明输出可能是近似、风格化或低模的，单张图片无法揭示隐藏侧面或保证精确几何，遇到不确定时应如实说明而不是假装有把握。
它需要安装哪些依赖？
forge 核心仅使用 Python 3.10+ 标准库，没有第三方依赖；可选的 GLB 角色管线与视觉适配器属于独立可选集成，需要额外安装 numpy、Pillow、playwright 等。
支持哪些 AI 宿主？
文档说明它与具体 Agent 无关，可在 Claude Code、Codex 或 OpenCode 下运行，图像读取与浏览器工具使用宿主自身提供的能力。
纠正循环有次数限制吗？
有。默认每个阶段 3 次纠正、总计 6 次，计数来自评审历史中的 refine-spec 与 refine-code 动作，而不是依赖对话记忆。