img2threejs
将参考图片中的物体重建为纯代码、程序化、质量受控且可用于动画的 Three.js 模型。刻意追求 token 高效------这是通过代码进行重建，而非摄影测量、网格提取或下载美术资源包。
许可证 ：Apache 2.0 | 版本 | 欢迎 PR | 运行时工具 | 赞助 | 脚本
由 Atlas Cloud 赞助 | 由 Tripo 赞助 | 由 Hyper3D 赞助
每日 / 每周趋势
Python: hoainho%2Fimg2threejs | Trendshift | img2threejs%2Fimg2threejs | Trendshift
全语言: img2threejs%2Fimg2twojs | Trendshift | img2threejs%2Fimg2threejs | Trendshift
通过代码将参考图片重建为可在浏览器中实时运行的动画就绪 Three.js 模型。
→ 打开实时演示画廊
画廊中的每个模型都是生成的代码，在您的浏览器中运行。没有网格文件，无需下载。
实时演示
完全由图元、程序化着色器和生成的几何体构建的重建模型。打开任何模型进行轨道旋转，检查其参考图并阅读生成的源代码。
| 演示 | 主题 | 构建版本 | 查看 | 源码 |
|---|---|---|---|---|
| 双剑战士 --- TypeScript 程序化表面 ⚠︎ | 角色 | v1.5.1 | 实时 | 代码 |
| 低多边形人形 --- 绑定角色 ⚠︎ | 角色 | v1.5.0 | 实时 | 代码 |
| ★ 爪子刀 | 多普勒红宝石 (崭新出厂) | 物体 | v1.4.4 | 实时 | 代码 |
| AWP | 美杜莎 (略有磨损) · V2 重建 | 物体 | V2 | 实时 | 代码 |
| 皮卡丘 10K Star 庆祝 ⚠︎ | 角色 | v1.5-beta | 实时 | 代码 |
| Glock-18 | 幽灵协议 (战痕累累) | 物体 | v1.4.1 | 实时 | 代码 |
| 经典刀 | 渐变之色 (略有磨损) | 物体 | v1.3 | 实时 | 代码 |
| BMX 耐力自行车 | 物体 | v1.3 | 实时 | 代码 |
| M9 刺刀 | 多普勒第二阶段 | 物体 | v1.3 | 实时 | 代码 |
| 索尼 WF-1000XM3 耳机 + 充电盒 | 物体 | v1.2 | 实时 | 代码 |
| ISSACA 12 号霰弹枪 | 物体 | v1.2 | 实时 | 代码 |
| Gerber 伞绳刀 | 物体 | v1.2 | 实时 | 代码 |
| 哆啦A梦的房子 (等距立体模型) | 物体 | v1.2 | 实时 | 代码 |
| 战争运输车 "SECTOR 07" | 物体 | v1.2 | 实时 | 代码 |
| 加冕战利品箱 ⚠︎ | 物体 | v1.2 | 实时 | 代码 |
⚠︎ 标记表示该演示的注册状态仍是占位符而非最终版本------它可以渲染，但不是已完成的工作。"构建版本"列是每个演示自己的注册条目在
generatedWith中记录的版本，而不是从日期推断的；awp-medusa-v2记录为 V2，这是该演示的重建版本而非发布号。行按添加演示的提交时间从新到旧排序。
画廊源码位于 img2threejs/img2threejs-showcase。如果这个项目对你有用，请在此仓库上点个 Star 帮助他人发现它。
项目功能
你给它一张物体的参考图片。它会生成一个用 TypeScript 编写的 THREE.Group 工厂函数，该函数通过图元、程序化着色器和生成的几何体来重建该物体------并带有运行时层级结构（枢轴、插槽、碰撞体），因此结果是可用于动画的，而不是一个静止的块。
它运行在 Claude Code、Codex 或 OpenCode 下。它是代理无关的：无论文档在哪里提到"代理视觉"或"代理浏览器工具"，它都使用宿主提供的任何工具------原生图像读取、浏览器 MCP、项目预览或用户提供的截图。
主题与细节精度
- 物体与角色 ：每个主题被分类为物体、角色或混合体。物体遵循硬表面管道；角色通过解剖学感知轨道（头部单元比例、面部特征点、姿势）进行路由，详见
grimoire/character/reconstruction.md。 - 细节优先分析 ：在代码生成之前，管道会枚举一个
detailInventory（细节清单），列出定义身份的小细节（光泽、倒角/圆角、螺丝/铆钉、雕刻或绘制线条、轮廓、污渍和磨损）。每个细节必须映射到真实的组件或材质条目，并且在清单完成之前，严格的质量门控会阻止生成。分类法见grimoire/intake/detail_inventory.md。 - 特定人物或角色的最大相似度 ：一个可选择加入的投影优先路径将参数化模板拟合到图像特征点上，对照片进行去光照、相机匹配渲染，并将参考图投影到网格上。单张图像无法保证 100% 的相似度，因此管道会报告每个区域的置信度，并在重要时要求更多视角。详情见
grimoire/character/likeness_maximization.md。 - 多视图轮廓雕刻 ：一个可选择加入的
geometryDescriptor.visualHull将至少两个确定的正交二值轮廓相交到一个有边界、已焊接的体素网格中。它将未见区域记录为低置信度，而不是凭空捏造隐藏细节。模式和运行时检查：grimoire/scripts.md。 - CS2 武器审查门控 ：刀和 Glock-18 路线使用特定系列的组件契约。审查记录精确层级、系列身份、绘制区域和投影覆盖率、每个区域的置信度、近似说明和版本化的审查场景元数据；组件覆盖率和去贴图线框门控防止用令人信服的纹理代替真实结构。随 CS2 领域插件一起提供；参见其
docs/cs2/review-gates.md。 - 可恢复的本地工作流 ：
forge/state.py为通用配置文件和每个已注册的领域（仓库内的角色，以及来自plugin-character等插件安装的角色）记录一个有序的、有证据支持的 intake/pass 检查清单。forge/next.py --state从该检查清单恢复，同时现有的规范、渲染和审查门控保持权威性。 - 材质参考管道 ：每个可见材质区域都可以被裁剪、分析、针对版本化的 Three.js 材质注册表进行解析、拟合到
ObjectSculptSpec中、从受控相机视图渲染，并且只有在每个区域比较门控通过后才被接受。参见docs/materials/README.md。 - Python 辅助的浏览器渲染 ：Python 可以编排相机批次、哈希、清单和确定性诊断，但目标浏览器 Three.js 路由仍然是渲染的权威。参见
grimoire/build/python_threejs_render_bridge.md。
工作原理
一个分阶段的雕刻管道将参考图片转化为规范（spec），然后一次生成并视觉审查一个构建阶段（build pass）------线框（blockout）→ 结构（structural）→ 形态（form）→ 材质（material）→ 表面（surface）→ 光照（lighting）→ 交互（interaction）→ 优化（optimization）------自我纠正，直到每个定义身份的特征通过其阈值。
→ 完整的管道图、门控、自我纠正逻辑和 token 效率设计：docs/ARCHITECTURE.md
一个分阶段的雕刻管道将参考图片转化为规范，然后一次生成并视觉审查一个构建阶段------线框 → 结构 → 形态 → 材质 → 表面 → 光照 → 交互 → 优化------自我纠正，直到每个定义身份的特征通过其阈值。确定性的 Python 脚本处理验证和门控；模型 token 只花在视觉判断和代码上。
→ 完整的管道图、门控、自我纠正逻辑、脚本参考和 token 效率设计：docs/ARCHITECTURE.md
快速开始
安装 --- 将此文件夹放在你的技能（skills）目录下：
git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs如果你使用多个宿主，请保留一个单独的签出版本，并将每个入口点通过符号链接指向它，这样它们就不会分叉：
~/.claude/skills/img2threejs -> <你的签出目录>
~/.codex/skills/img2threejs -> <你的签出目录>**添加领域插件（可选）** --- 领域知识（目前是 CS2 皮肤）存在于已安装的插件中，而不是在这个签出目录中。安装 img2 工具一次，然后向其中添加插件：
npx github:img2threejs/img2 install # ~/.img2，插件注册表和 `img2` 启动器
img2 add img2threejs/plugin-cs2 # 克隆最新标签，固定 SHA，链接宿主技能
img2 doctor # 对每个已安装插件进行故障响亮的静态审计已安装的领域插件贡献其自己的检查清单步骤、证据收集、规范增强（质量下限仅提升），以及一个阻塞性的审查门控------并通过 forge/state.py init --profile <id> 注册其配置文件。未安装插件时，通用（generic）和角色（character）可用；缺少插件（cs2、animated-character）的配置文件会响亮地失败，并指明已安装的内容，绝不会静默降级。img2 remove <id> 可以干净地反向操作。编写自己的插件：工具仓库的 docs/WRITING_A_PLUGIN.md。
调用 --- 在 Claude Code 中，附加或指向一个物体图片并运行：
/img2threejs 将此物体重建为 Three.js 模型，保持比例、角度和颜色。这就足够了：技能会对主题进行分类，运行细节清单，并自行控制每个阶段的门控。
遵循管道 --- 技能验证图片，编写评估和规范，逐阶段生成工厂函数，并在每一步向你展示并排比较，直到渲染匹配。
对于多会话重建，首先创建一个本地状态索引：
python3 forge/state.py init --reference <image> --profile character --spec object-sculpt-spec.json
python3 forge/next.py --state .img2threejs/state.json更严格地驱动它
单行命令将判断权留给技能。当你已经知道你的主题"正确"意味着什么时，请明确说明------下面每一行都映射到管道中的真实门控或工件，因此它会改变被强制执行的内容，而不仅仅是添加形容词：
/img2threejs 将这张图片中的主题重建为程序化 Three.js 模型。
保真度 保持比例和轮廓与参考一致。首先枚举定义身份的细节------倒角和圆角、
面板接缝、紧固件、雕刻或绘制的线条、光泽与哑光区域、磨损------并丢弃
任何无法放置在真实组件上的细节，而不是伪造它。
材质 从参考像素中推导表面处理类别和渐变停止点，而不是凭记忆。标记任何
无法在色调映射中存活的颜色。
运行时 为任何应该移动的部分暴露枢轴和插槽，加上用于循环空闲动画的 userData.tick。
门控 运行 --strict-quality，在并排审查通过之前不要推进阶段。对图像无法
显示的任何内容报告每个区域的置信度。根据主题有用的补充：
- 特定人物或角色 --- 最大化相似度：将参数化模板拟合到特征点，对参考进行去光照和相机匹配，然后投影。告诉我哪些区域是推断的。
- 动物或生物 --- 这是一个生物，不是人形------使用四足身体计划和身体单元比例系统。
- 饱和阳极氧化或糖果色涂层 --- 涂层是糖果涂层，不是宝石金属。保持色调；不要让环境偷走它。
- 成本上限 --- 保持低工作量并跳过演示合成器；我只需要评估渲染。
脚本从技能根目录运行，只需要 Python 3.10+ ------ 无需安装任何东西。
python3 forge/stage1_intake/probe_image.py <image>
python3 forge/stage2_spec/new_pre_spec_assessment.py "名称" --image <image> --out assessment.json
python3 forge/stage2_spec/new_sculpt_spec.py "名称" --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工厂生成器会重复严格的质量门控，并且是故障封闭的（fail-closed）：失败时返回 BLOCKED，附带规范工件、失败指标、原因和下一步操作，并且不写入工厂。--allow-nonstrict 仅用于显式遗留测试夹具，绝不用于生产输出。
GLB 参考路线的复制粘贴提示
从 GLB 参考而不是照片重建角色是一条不同的路线，有自己的门控------GLB 是一种测量工具，永远不会被发布。三个提示涵盖了它，每个都在自己的复制块中：
| 提示 | 使用场景 | 不使用场景 |
|---|---|---|
| Build | 你有 GLB 且尚未构建表面 | 没有 GLB，或者构建已完成但看起来不对 |
| Polish | 构建完成但结果看起来不像 GLB | 表面从未构建------那是构建重跑，不是润色 |
| Animation | 人物静止时看起来正确且已通过构建门控 | 表面未受门控，或 joint_loops.py 失败------那是表面发现，权重调整无法解决 |
它们强制 GLB 真正携带的每个参数------尺寸、比例、每带宽度和质心、基础颜色、粗糙度和金属度------达到测量值，并附带证明它已着陆的检查。有三件事不是 1:1 的，每个提示都说明了：绑定和动画通常不存在于资源中（skinCount: 0, animationCount: 0），纹理图像和法线贴图根据此技能的纯代码契约被故意不复制，并且任何比节点单元格大小更精细的东西根本无法携带。
这些是参考资料，不是保证。它们被写成通用的，因此其中的测量值来自一个角色，只是为了展示要测量什么------而不是要复制的值。运行与您情况匹配的那个，而不是按顺序运行所有三个；每个都注明了不合时宜使用的成本。
有关逐脚本参考、完整脚本表和预期工件，请参阅 docs/ARCHITECTURE.md。
为什么它是 token 高效的
大多数图像转 3D 代理循环通过要求模型执行机械工作来消耗 token------每次都重新读取整个模型、对像素评分、手动验证 JSON、重新运行已经做过的步骤。img2threejs 将所有这些推入确定性脚本，并且只在实际需要判断的地方花费模型 token。
- 脚本执行，模型判断：Python 脚本处理验证、门控、规范编写、PBR 提取、比较表打包和管道状态。它们从不给视觉评分。模型的 token 只用于一件事：查看单个并排表并决定通过或失败。
- 零依赖，零安装混乱 ：每个脚本都是纯 Python 3.10+ 标准库。没有 pip，没有 PIL，没有 numpy，没有 Playwright。PNG 读写使用
struct和zlib完成。无需安装意味着无需在上下文中调试。 - 阶段门控生成：代码生成器只发出当前解锁的构建阶段。模型不会在每次迭代时重新生成或重新读取整个模型------每个步骤都是小而有限的。
- 在代码生成之前快速失败：严格的质量门控在生成一行 Three.js 代码之前阻止浅层规范，因此你永远不会花费 token 去渲染一个从一开始就被低估的模型。
- 每次审查一张图片：每个阶段仅从打包的比较表（参考图与渲染图并排）进行判断，而不是一堆零散的截图。
- 文本输出，而非二进制：结果是可差异比较的 TypeScript 加上 JSON 规范------小巧、可审查、可版本控制，而不是多兆字节的网格文件。
净效果：你仍然可以从图像中获得忠实的 3D 模型，但昂贵的模型上下文被保留用于视觉判断和代码，而不是簿记。有关每个阶段和每个周期的完整 token 细分，请参阅 docs/TOKEN_COST.md。
脚本
| 脚本 | 作用 |
|---|---|
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 证据（推理，不是逆向渲染）。 |
stage1_intake/material_region_analysis.py |
裁剪材质区域，运行纹理/PBR 证据，并解析注册表配置文件。 |
stage2_spec/apply_material_analysis.py |
将区域分配、先验、贴图和来源连接到 ObjectSculptSpec。 |
stage3_build/orchestrate_passes.py |
锁定的阶段状态：状态、检查、同步。 |
stage3_build/generate_threejs_factory.py |
为当前解锁的阶段发出 Three.js Group 工厂。 |
stage4_review/material_views.py |
发出多角度、缩放、显微镜、环境和捕获回读契约。 |
stage4_review/material_comparator.py |
比较可见材质裁剪并分类每通道不匹配。 |
stage4_review/material_feedback.py |
通过现有的停止策略应用有界的、材质范围的纠正。 |
stage4_review/material_gate.py |
在注册表、裁剪、渲染、兼容性和比较证据通过之前阻止材质阶段。 |
stage4_review/make_comparison_sheet.py |
打包一个用于审查的参考与渲染对照表。 |
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 烘焙描述符。 |
stage5_rig/rig_spec.py |
从组件树派生并验证骨架，使骨骼不能偏离几何体。 |
stage5_rig/geodesic_skinning.py |
通过实体测量的距离计算顶点权重；使刚性角色远离平滑蒙皮。 |
stage5_rig/validate_rig_payload.py |
在绑定 THREE.Skeleton 之前的阻塞负载完整性门控。 |
stage1_intake/extract_hair_evidence.py |
头发/皮肤分割、带状覆盖、发际线、高光带、根到尖端的差异。 |
stage4_review/scalp_exposure.py |
硬性门控：在几何体上找到秃斑，在任何渲染之前。 |
stage4_review/hair_gate.py |
软性门控：头发覆盖、发际线和高光偏移与参考的比较。 |
stage4_review/interior_difference.py |
轮廓内的外观差异，按高度分带。每个视觉阶段都需要。 |
_shared/chirality.py |
可导入的左右约定，以及两个手性缺陷需要的两个门控。 |
_shared/pipeline_routing.py |
故障封闭的武器/角色路由；低置信度解析为请求输入。 |
这是一个精选的选择------forge/ 包含大约 90 个模块。带有每个标志的可执行参考是 grimoire/scripts.md，逐门控契约是 grimoire/review/gates_reference.md。其余的 grimoire/ 包含每个门控应用的标准（验证、预规范评估、程序化模式、材质和光照真实感、附件正确性、动作就绪模型、自我纠正）。
可选的参考保真度工具
纯标准库核心可以使用隔离的证据层，而无需承担运行时依赖：SAM2 组件蒙版、Depth Anything V2 相对深度先验、MediaPipe 面部/姿势特征点、Chrome DevTools 诊断、Three.js 场景检查、Playwright 跨浏览器后备和版本感知的 Context7 检索。这些工具从不批准阶段或静默提供几何体。安装、路由、来源规则和确切命令：docs/integrations/reference_fidelity_tooling.md。
可选的 GLB 基线角色管道
integrations/glb_character_pipeline 从用作测量工具的多部分 GLB 及其漫反射图像重建角色，并发出演示实际发布的程序化 TypeScript------运行时不会获取任何 .glb 或 .bin。它带有自己的 pyproject.toml/uv.lock，因此纯标准库的 forge 核心保持无依赖，并在伴随的展示签出上通过 IMG2THREEJS_SHOWCASE_ROOT 操作。
它仅适用于构建有 GLB 可测量的情况------否则完全跳过它，改用核心图像驱动管道。精确复现 girl-character 发布的 crossSections.ts（748 个环，86,240 个环点）。方法和每个阶段的原理：PIPELINE.md。
你将获得什么
- 一个
ObjectSculptSpecJSON：完整的组件树、材质、重复系统、插槽以及每个阶段记录的审查历史。 - 一个 TypeScript
createObjectNameModel(spec, options)工厂函数，返回THREE.Group，其中root.userData.sculptRuntime暴露节点、插槽、碰撞体和销毁组。 - 对于角色构建，
root.userData.rig：骨骼、一个共享的 Skeleton、骨骼顺序和索引映射，以及根据每个蒙皮网格是否实际绑定计算出的绑定标志。 - 渲染和比较表，记录每个阶段的保真度。有关逐脚本参考和输出工件的完整列表，请参阅
docs/ARCHITECTURE.md。
路线图
已发布：
- v1.0 --- 物体管道：分阶段雕刻、渲染与参考审查循环、动作就绪层级。
- v1.1 --- 细节优先分析：必需的细节清单，严格的质量门控。
- v1.2 --- 人形角色生成器：解剖学轨道、比例锁定和特征放置阶段。
- v1.3 --- 质量和效率：Divine Eye 确定性审查工具、输入完整性和几何真实性门控、参考基础的纹理和渐变分析、CIEDE2000 色彩数学。
- v1.4 --- 武器更新 --- CS2 图像匹配重建：来源感知的 intake、投影优先的表面处理、特定系列的武器适配器以及结构审查门控。
- v1.4.1 --- CS2 强化：显式组件覆盖、专用的 Glock-18 装配契约、去贴图线框证据和更严格的几何完整性检查。
- 生物生成器 --- 4 种身体计划（四足 / 鸟类 / 有翼龙 / 蛇形）、
animalAnatomy规范、脊柱放样几何体、ΔE00 色彩门控。 - v2.0 --- 插件更新 --- 领域注册表、基于拉取的规范增强（仅提升质量下限）、带有来源的发射目标套接字、每个插件的阻塞门控，以及 img2 工具（
img2 install/add/doctor）。CS2 提取到plugin-cs2，animated-character由plugin-character服务；基础名称不指定领域。最初为"程序化世界包"预留的"插件生态系统和 API"作为自己的主要版本率先发布。 - v1.5 --- 角色更新 --- 从组件树派生并绑定到 SkinnedMesh 几何体的骨架、测地线蒙皮、作为五阶段子系统的头发（带有硬性头皮暴露门控）、手性门控、内部差异审查、锥形扫描图元、带有阻塞接受门控的材质管道，以及可恢复的工作流状态。不包括 ：
hairProfile编译器、IK、姿势扫描门控、服装。
下一步 --- 每个版本一个主题：
- v2.1 --- 环境更新：建筑物、房间、街道、植被、地形感知和多物体重建。
- v2.2 --- 游戏管道更新：Unity 和 Unreal 导出器、Blender 桥接、LOD 和碰撞网格生成。
- v2.3 --- 动画更新：自动绑定、自动蒙皮权重、Mixamo 兼容性、面部绑定。
- v2.4 --- AI Studio 更新：Web UI、批处理、视觉提示生成器、云渲染。
- v3.0 --- 程序化世界更新：多视图重建、程序化城市生成、语义世界理解。
发展弧线：资产（v1.4--v1.5）→ 插件生态系统（v2.0）→ 世界（v2.1--v2.2）→ 生产（v2.3--v2.4）→ 从参考图像生成可玩世界的 AI 游戏资产生成平台（v3.0）。
→ 完整路线图 --- 每个版本的详细信息、四阶段长期展望和跟踪的能力差距：ROADMAP.md。技术规格：docs/UPGRADE_PLAN.md。
关于局限性的诚实说明
单张图片无法揭示隐藏面或保证精确的几何体。该技能会明确说明输出何时是近似的、风格化的或低多边形的，并通过镜像可见面来推断不可见面，而不是伪造置信度。它对于硬表面物体很强；角色是风格化的重建，不是照片级的相似。如果技能认为"从这张图片无法达到请求的保真度"，这是一个有效的、预期的结果。
Star 历史
如果 img2threejs 对你有用，请点个 Star 帮助他人找到它。
Star History Chart
支持项目
img2threejs 是免费和开源的。如果它节省了你的时间或进入了你的项目，请考虑支持持续开发：
ko-fi
VietQR / MoMo / PayPal 也适用 ------ 请参阅捐赠页面。