@NickDevFE: img2threejs v1.3 现已可用。一张照片 → 程序化 Three.js 代码。无需网格。无需手动建模。GitHub: https:/…

img2threejs v1.3 现已发布。一张照片 → 程序化 Three.js 代码。无需网格。无需手动建模。GitHub: https://github.com/hoainho/img2threejs… v1.3 在几何重建、材质生成、验证和整体输出质量方面带来了重大改进。本演示中，我使用了 CS2 ★ M9 Bayonet | Doppler Phase 3 的参考图: https://tradeit.gg/csgo/trade?search=%E2%98%85+M9+Bayonet+%7C+Doppler+Phase+3+(Factory+New… 如果你刚接触 img2threejs，现在正是尝试的好时机。如果你之前用过，非常希望你能将结果与旧版本进行对比。始终欢迎反馈、bug 报告和 PR。— # hoainho/img2threejs 来源: https://github.com/hoainho/img2threejs # img2threejs 将参考图像中的对象重建为纯代码、程序化的 Three.js 模型。 质量把关、动画就绪、刻意追求 token 高效——通过代码重建，而非摄影测量、网格提取或下载的艺术资源包。许可: Apache 2.0 版本 欢迎 PR 运行时 (https://threejs.org) 工具 img2threejs 演示——一个参考战利品箱图像重建为程序化 Three.js 模型 单个参考图像在代码中重建——准确的比例、颜色、倒角、金色饰边和自发光徽标——在浏览器中实时运行。 ### → 打开在线演示画廊 (https://hoainho.github.io/img2threejs-showcase/) 画廊中的每个模型都是生成的代码，在你的浏览器中运行。没有网格文件，无需下载。— ## 在线演示 完全由基本体、程序化着色器和生成几何体构建的重建。以下片段是在浏览器中实时运行的模型——打开每个模型即可旋转查看并阅读生成的源码。 | 演示 | 预览 | 对象 | 查看 | 源码 | | — | — | — | — | — | | Sony WF-1000XM3 耳机 + 充电盒 | | 硬表面对象 | 在线查看 (https://hoainho.github.io/img2threejs-showcase/#/demo/sony-wf1000xm3) | 代码 (https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/sony-wf1000xm3/createSonyWf1000xm3Model.ts) | | ISSACA 12 号霰弹枪 | | 硬表面对象 | 在线查看 (https://hoainho.github.io/img2threejs-showcase/#/demo/issaca-shotgun) | 代码 (https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/issaca-shotgun/createIssacaShotgunModel.ts) | | Gerber 伞绳刀 | | 硬表面对象 | 在线查看 (https://hoainho.github.io/img2threejs-showcase/#/demo/gerber-knife) | 代码 (https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/gerber-knife/createGerberKnifeModel.ts) | | 哆啦A梦小屋（等距立体模型） | | 硬表面对象 | 在线查看 (https://hoainho.github.io/img2threejs-showcase/#/demo/doraemon-house) | 代码 (https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/doraemon-house/createDoraemonHouseModel.ts) | | War-Hauler “SECTOR 07” | | 硬表面对象 | 在线查看 (https://hoainho.github.io/img2threejs-showcase/#/demo/warhauler) | 代码 (https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/warhauler/createWarHaulerModel.ts) | | 带王冠的战利品箱 | | 硬表面对象 | 在线查看 (https://hoainho.github.io/img2threejs-showcase/#/demo/crown-chest) | 代码 (https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/crown-chest/createCrownChestModel.ts) | 画廊源码位于 hoainho/img2threejs-showcase (https://github.com/hoainho/img2threejs-showcase)。如果这个项目对你有用，在仓库上点个星标可以帮助更多人发现它。— ## 它的功能 你提供一张对象的参考图像。它生成一个用 TypeScript 编写的 THREE.Group 工厂，从基本体、程序化着色器和生成几何体中重建该对象——并附带运行时层次结构（枢轴、插槽、碰撞体），使结果可立即用于动画，而非一个静态的几何块。它在 Claude Code、Codex 或 OpenCode 下运行。与代理无关：只要文档中提到“代理视觉“或“代理浏览器工具“，它就会使用宿主提供的任何能力——原生图像读取、浏览器 MCP、项目预览或用户提供的截图。### 对象与细节精度 - 对象与角色。 每个对象被分类为 object、character 或 hybrid。对象遵循硬表面管线；角色则进入解剖感知轨道（头部单元比例、面部特征点、姿态），相关文档见 grimoire/character/reconstruction.md。 - 细节优先分析。 在代码生成之前，管线会枚举一个 detailInventory（细节清单），包含定义身份的小细节（光泽、倒角/圆角、螺丝/铆钉、雕刻或绘制的线条、轮廓、污渍和磨损）。每个细节必须映射到真实的组件或材质条目，并且严格质量门会阻止生成，直到清单完整。分类法：grimoire/intake/detail_inventory.md。 - 特定人物或角色最大化相似度。 一个可选的投影优先路径将参数化模板拟合到图像特征点，去除照片光照，匹配相机渲染，并将参考投影到网格上。单张图像无法保证 100% 相似度，因此管线会报告每个区域的置信度，并在必要时要求更多视图。详情：grimoire/character/likeness_maximization.md。— ## 工作原理 该技能运行一个分阶段雕刻管线。脚本控制每个阶段的门控；代理的视觉是唯一能批准通过的东西。mermaid flowchart TD A[参考图像] --> B[探测与适用性门控] B --> C[预规范评估：类别、复杂度、质量合同] C --> D[编写 ObjectSculptSpec：组件、材质、插槽] D --> E{验证与严格质量} E -- 太浅 --> D E -- ok --> F[锁定的构建回合] F --> G[生成 Three.js 工厂：仅当前回合] G --> H[在浏览器中渲染并截图] H --> I[打包一张对比图] I --> J{代理视觉检查} J -- 分数低于阈值 --> K[自我修正：细化规范或代码] K --> F J -- 通过 --> L{还有更多回合吗？} L -- 是 --> F L -- 否 --> M[动画就绪的 Three.js 模型] ### 构建回合 模型按固定顺序雕刻；只有在前一个回合被检查并接受后，下一个回合才会解锁：粗模 → 结构回合 → 形态细化 → 材质回合 → 表面回合 → 光照回合 → 交互回合 → 优化回合 每个回合都有自己的验收标准。一个回合被标记为 continue 的条件是：有真实渲染、对比图、代理视觉评分达到或超过阈值，并且每个定义身份的特征都达到或超过其自身的阈值。### 门控 - 适用性——图像是否适合作为 3D 目标。 - 预规范和严格质量——在规范深度达到对象复杂度要求之前阻止代码生成（复合对象不能只有一个根规范）。 - 截图反馈——continue 需要渲染 + 对比图 + 通过的视觉评分。 - 动作就绪——模型通过 root.userData.sculptRuntime 暴露运行时层次结构（枢轴、插槽、碰撞体、破坏组）。 - 附件正确性——子部件（手柄、肢体、管道）声明它们如何连接到父部件，确保没有漂浮在半空中。 - 材质与光照真实感——独立的 PBR 通道和真实光源，永远不要将反照率混入粗糙度。### 自我修正 在每次回合后，代理恰好选择一种操作：continue、refine-spec、refine-code、request-input 或 stop。refine-spec 修复错误或浅薄的规范并重新验证；refine-code 修复与合理规范不匹配的几何体、材质或光照。— ## 快速开始 1. 安装——将此文件夹放到你的技能目录中：bash git clone https://github.com/hoainho/img2threejs.git ~/.claude/skills/img2threejs 2. 调用——在 Claude Code 中，附加或指向一张对象图像，然后运行：/img2threejs 将此对象重建为 Three.js 模型，保持比例、角度和颜色。 3. 遵循管线——技能会验证图像、编写评估和规范、逐回合生成工厂，并在每一步显示对比图，直到渲染匹配。脚本从技能根目录运行，仅需 Python 3.10+ ——无需额外安装。bash python3 forge/stage1_intake/probe_image.py python3 forge/stage2_spec/new_pre_spec_assessment.py "名称" --image --out assessment.json python3 forge/stage2_spec/new_sculpt_spec.py "名称" --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 — ## 为什么 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 证据（推理，非逆渲染）。 | | stage3_build/orchestrate_passes.py | 锁定回合状态：状态、检查、同步。 | | stage3_build/generate_threejs_factory.py | 为当前解锁的回合生成 Three.js Group 工厂。 | | 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 烘焙描述符，用于照片纹理投影。 | grimoire/ 文件夹包含每个门控应用的详细规则（验证、预规范评估、程序化模式、材质与光照真实感、附件正确性、动作就绪模型、自我修正）。— ## 你将获得 - 一个 ObjectSculptSpec JSON：完整的组件树、材质、重复系统、插槽以及每次回合的检查历史记录。 - 一个 TypeScript createObjectNameModel(spec, options) 工厂，返回一个 THREE.Group，并通过 root.userData.sculptRuntime 暴露节点、插槽、碰撞体和破坏组。 - 一个渲染结果以及记录每次回合保真度的对比图。— ## 路线图 - v1.0 —— 对象管线：分阶段雕刻、渲染-参考检查循环、动作就绪层次结构。已发布。 - v1.1 —— 细节优先分析：必需的细节清单、严格质量门。已发布。 - v1.2 —— 人形角色生成器：解剖轨道、比例锁定和特征放置回合。已发布。 - v1.3 —— 最大相似度：投影优先的角色渲染、分区置信度。计划中。 - v1.4 —— 动画就绪骨骼：SkinnedMesh、变形目标、glTF 导出。计划中。 完整细节和后续里程碑：ROADMAP.md。技术规范：docs/UPGRADE_PLAN.md。— ## 诚实说明限制 单张图像无法揭示隐藏面或保证精确几何。技能会明确说明输出何时是近似的、风格化的或低多边形，并通过镜像可见面来推断不可见面，而不是假装有把握。它擅长硬表面对象；角色是风格化的重建，而非照片级真实相似度。“此图像无法达到所要求的保真度“是一个有效且预期的结果。— ## 星标历史 如果 img2threejs 对你有用，点个星标有助于他人发现它。— ## 贡献 欢迎贡献——特别是程序化材质配方、新的门控、主机覆盖和演示。请参见 CONTRIBUTING.md 和 路线图，了解项目未来的方向。## 许可 Apache 许可证 2.0。请参见 LICENSE。