不只是生成模型，更是可动画的资产
你给它一张物体的参考图，它生成一个 TypeScript 编写的 THREE.Group 工厂函数， 附带运行时层级结构——枢轴、插槽、碰撞体、销毁组。
物体与角色
每个主题会被分类为 object（物体）、character（角色）或 hybrid（混合）。物体走硬表面流水线；角色则进入一个具备解剖学意识的轨道——头身比例、面部关键点、姿态。
了解角色重建质量门控
适用性、严格质量、截图反馈、可交互就绪、连接正确性、材质与光照真实感——六道门在代码前后拦截不合格输出。
纯代码，零依赖
结果是可 diff 的 TypeScript 代码加 JSON 规格。每个脚本都是纯 Python 3.10+ 标准库，没有 pip，没有 PIL，没有 numpy，无需安装。
Agent 无关
可运行于 Claude Code、Codex 或 OpenCode 之上。凡是提到 agent 视觉或浏览器工具的地方，都会使用宿主所提供的任意能力——原生图像读取、浏览器 MCP、项目预览或用户截图。
分阶段雕刻流水线
脚本负责管控每个阶段；只有 agent 的视觉判断才能批准一个阶段通过。 模型按固定顺序雕刻，一个阶段只有在前一个被评审并接受后才会解锁。
适用性门控
这张图到底是不是一个可行的 3D 目标，在最早期就做出判断。
规格预评估与严格质量
在规格足够深入、匹配物体复杂度之前阻止代码生成。复合物体不允许只有一个根的规格。
截图反馈
continue 需要一次渲染、一张对比图，外加一个通过的视觉评分。
可交互就绪
模型通过 root.userData.sculptRuntime 暴露运行时层级：枢轴、插槽、碰撞体、销毁组。
连接正确性
子部件（把手、四肢、管道）需声明它们如何连接到父级，从而没有任何东西悬空漂浮。
材质与光照真实感
独立的 PBR 通道与真实灯光，绝不让 albedo 被混入 roughness。
昂贵的上下文只留给视觉判断
大多数图像转 3D 的 agent 循环都在浪费 token：让模型做机械性工作——重读整个模型、给像素打分、手工校验 JSON。 img2threejs 把这一切都推进确定性的脚本里，只在真正需要判断力的地方消耗模型 token。
脚本负责执行，模型负责判断
Python 脚本处理校验、门控、规格编写、PBR 提取、对比图打包及流水线状态。它们从不给视觉打分。模型 token 只花在看一张对比图并决定通过与否上。
零依赖，零安装折腾
每个脚本都是纯 Python 3.10+ 标准库。没有 pip，没有 PIL，没有 numpy，没有 Playwright。PNG 的读写用 struct 和 zlib 完成。无需安装，意味着上下文中没有需要调试的东西。
阶段门控生成
代码生成器只输出当前已解锁的构建阶段。模型不会在每次迭代中重新生成或重读整个模型——每一步都很小且范围明确。
快速失败，在代码生成之前
一道严格质量门会在生成任何一行 Three.js 代码之前，挡住过于浅显的规格，因此你永远不会把 token 浪费在渲染一个从一开始就规格不足的模型上。
每次评审只看一张图
每个阶段的评审都基于恰好一张打包好的对比图（参考图与渲染图并排），而不是一堆零散的截图。
文本输出，而非二进制
结果是一份可 diff 的 TypeScript 代码，外加一份 JSON 规格——体积小、可审阅、可纳入版本控制，而不是几兆字节的网格文件。
单次物体重建的 Token 分布
工程估算，非实测基准。实际成本随模型层级、图像分辨率、物体复杂度及评审轮次变化。
单轮渲染-评审循环
截图（~0）+ 打包对比图（~0）+ 视觉检查（~2k-3k）+ 撰写评审（~1k-2k）
角色重建成本
角色成本更高（更多评审轮次 + 关键点与投影检查）：使用 v1.2 角色生成器， 完整的风格化或最大相似度重建约 ~150k-350k tokens。
三步即可运行
这样就够了：skill 会自行分类主题、运行细节清单，并对每个阶段进行门控。
安装
把这个文件夹放到你的 skills 目录下：
git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs
调用
在 Claude Code 中，附上或指向一张物体图像，然后运行：
/img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.
跟随流水线
skill 会校验图像、撰写评估与规格、逐阶段生成工厂函数，并在每一步都向你展示一张并排对比图，直到渲染与参考图一致。
更进一步使用
上面那句简短指令把判断权交给了 skill。当你已经清楚自己主题中「正确」的定义时，就明确说出来—— 下面每一行都对应流水线中一道真实的门控或产物：
/img2threejs 将这张图像中的主题重建为一个程序化的 Three.js 模型。
保真度 保持与参考图一致的比例与轮廓。先枚举出身份定义性的
细节 —— 倒角与圆角、面板接缝、紧固件、雕刻或喷涂的
线条、光泽与哑光区域、磨损 —— 并丢弃任何无法落实到
真实部件上的细节，而不是去伪造它。
材质 从参考图像素中推导表面类别与渐变节点，而不是凭记忆。
标记任何无法在色调映射中保留的颜色。
运行时 为所有应当活动的部分暴露枢轴与插槽，并附带一个用于
循环待机动画的 userData.tick。
门控 运行 --strict-quality，并且在并排评审通过之前不推进
任何阶段。对图像无法呈现的区域报告分区置信度。脚本从 skill 根目录运行，仅需 Python 3.10+
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 3.10+ 标准库，负责校验、门控、规格编写、PBR 提取与流水线状态。
| 脚本 | 职责 |
|---|---|
stage1_intake/probe_image.py | 图像元数据与明显的技术问题（非视觉检查）。 |
stage2_spec/new_pre_spec_assessment.py | 对物体分类、评估复杂度，并产出质量契约。 |
stage2_spec/new_sculpt_spec.py | 基于评估编写 ObjectSculptSpec。 |
stage2_spec/validate_sculpt_spec.py | 校验规格；--strict-quality 会在代码生成前挡住浅显的规格。 |
stage1_intake/extract_pbr_evidence.py | 针对每个裁剪区域，从参考图推导 PBR 证据（推断，而非逆向渲染）。 |
stage3_build/orchestrate_passes.py | 锁定的阶段状态：状态、检查、同步。 |
stage3_build/generate_threejs_factory.py | 为当前已解锁阶段生成 Three.js Group 工厂。 |
stage4_review/make_comparison_sheet.py | 打包一张参考图 vs 渲染图对比图供评审。 |
stage4_review/append_review.py | 记录每次阶段的评审：评分、决策、证据。 |
_shared/feature_acceptance_policy.py | 内部辅助脚本，强制执行每个特征的评分阈值。 |
stage1_intake/build_detail_inventory.py | 将参考图切分为若干区域，并搭建细节清单。 |
stage1_intake/extract_landmarks.py | 叠加关键点网格，并为角色搭建解剖学区块。 |
stage1_intake/solve_camera_pose.py | 产出参考相机区块，使渲染能进行相机匹配。 |
stage1_intake/delight_albedo.py | 在纹理投影前，从照片中近似出中性反照率。 |
stage3_build/bake_projected_texture.py | 为照片纹理投影产出投影/UV 烘焙描述符。 |
grimoire 文件夹保存着每道门控所依据的详细评分准则——校验、规格预评估、程序化模式、 材质与光照真实感、连接正确性、可交互就绪模型、自我修正。
三份可审阅的交付物
ObjectSculptSpec JSON
完整的部件树、材质、重复系统、插槽，以及每个阶段被记录的评审历史。
TypeScript 工厂函数
createObjectNameModel(spec, options) 返回 THREE.Group，并通过 root.userData.sculptRuntime 暴露节点、插槽、碰撞体与销毁组。
渲染图与对比图
一份渲染图，外加记录每个阶段保真度的并排对比图——参考图 vs 渲染图。
每次发布一个主题
发展脉络：资产（v1.4–v1.5）→ 世界（v1.6–v1.7）→ 生产（v1.8–v1.9）→ 一个能从参考图生成可玩世界的 AI 游戏资产平台（v2.0）。
物体流水线
分阶段雕刻、渲染对比参考图的评审循环、可交互就绪的层级结构。
细节优先分析
强制性的细节清单、严格质量门。每道门控所依据的详细评分准则。
人形角色生成器
解剖学轨道、比例锁定与特征放置阶段。世界空间人形组件树模板。
质量与效率 + 生物生成器
Divine Eye 确定性评审框架、输入完整性与几何真实性门控、CIEDE2000 色彩数学。4 种身体结构方案（四足 / 鸟类 / 翼龙 / 蛇形）。
武器更新
面向 CS2 级别硬表面资产的 1:1 照片级、非风格化流水线——严格的 PBR 标准与纹理投影、针对装配的机械推理，以及真实的金属 / 聚合物 / 木材响应。
角色更新
角色重建、面部特征、可绑定拓扑、blendshape 预备、毛发与衣物。包含实测 Token 基准。
环境更新
建筑、房间、街道、植被、地形感知与多物体重建。
游戏流水线更新
Unity 与 Unreal 导出器、Blender 桥接、LOD 与碰撞网格生成。
动画更新
自动绑定、自动蒙皮权重、Mixamo 兼容、面部绑定。
AI 工作室更新
Web UI、批量处理、可视化提示词构建器、云端渲染。
程序化世界更新
多视角重建、程序化城市生成、语义化世界理解、插件生态与 API。
关于局限性的坦诚说明
单张图像无法揭示被遮挡的侧面，也无法保证精确的几何。当输出是近似的、风格化的或低多边形的时候， skill 会直白说明，并通过镜像可见面来推断不可见的面，而不是伪造置信度。 它在硬表面物体上表现出色；角色则是风格化的重建，而非照片级的相似。
「从这张图像无法达到所要求的保真度」是一个有效且可预期的结果。