img2threejs：从图片描述走到可运行的 Three.js 场景
该项目围绕「img2threejs/img2threejs」构建，面向真实业务场景提供可复用的开源实践方案，支持稳定落地与可扩展的项目实践。
秒懂
- 它是什么？
- 一个技能，将参考图像中的物体重建为具有质量门控和令牌效率的程序化、可动画的Three.js模型。
- 适合谁用？
- img2threejs 适合做概念验证：输入一张图片，借助图像理解和生成流程产出 Three.js 代码或场景草稿。它不等同于从照片得到精确的三维测量模型，README 未提供几何误差、纹理质量或复杂场景的基准，因此建筑、工业逆向等任务不能直接套用这个结论。
- 能商用吗？
- 可以。Apache-2.0 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 2 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
从图像到Three.js的纯代码路径
img2threejs 接收一张物体的参考图像，并生成一个返回 THREE.Group 的 TypeScript 工厂。该组完全由图元、程序化着色器和生成的几何体构建；不导入网格文件，也不使用下载的美术包。输出带有运行时层次结构，包含枢轴、插座和碰撞体，因此模型已准备好动画化，而不是静态形状。该流水线可在 Claude Code、Codex 或 OpenCode 下运行，并使用宿主提供的任何图像读取能力，无论是原生图像读取、浏览器 MCP、项目预览还是用户提供的截图。
img2threejs 适合做概念验证：输入一张图片，借助图像理解和生成流程产出 Three.js 代码或场景草稿。它不等同于从照片得到精确的三维测量模型，README 未提供几何误差、纹理质量或复杂场景的基准，因此建筑、工业逆向等任务不能直接套用这个结论。
图片到场景的过程包含语义猜测，因此结果是否有用取决于代码能否继续编辑。检查时可以把生成结果拆成相机、几何体、材质、光源和交互五项，确认每一项是否在 Three.js 项目中有明确对应。单张图无法提供被遮挡面的真实信息，生成器只能补出假设；README 没有给出尺寸标定、拓扑修复或动画重建的承诺。把输出放进一个最小网页并打开控制台，能比静态截图更快发现导入、依赖和运行时错误。 本段对应小节“从图像到Three.js的纯代码路径”，核验时应把该小节提到的对象单独记录。
带确定性门控的分阶段雕刻循环
流水线按顺序经历八个阶段：封堵、结构、形态、材质、表面、光照、交互和优化。每次通过后，将生成的渲染与参考图像进行比较，系统自我纠正，直到每个定义身份的细节都达到阈值。确定性 Python 脚本处理验证和门控，而模型令牌仅用于视觉判断和代码生成。这种分离保持了过程的令牌效率，完整架构（包括流水线图和脚本参考）记录在 docs/ARCHITECTURE.md 中。
评估时应查看仓库的提示词、生成代码入口和示例资产，固定同一张图片反复运行，重点观察摄像机、材质、灯光和模型层级是否可编辑。还要确认所需模型服务、API 凭据与前端运行方式，素材没有说明的部分不能补写成默认行为。
图片到场景的过程包含语义猜测，因此结果是否有用取决于代码能否继续编辑。检查时可以把生成结果拆成相机、几何体、材质、光源和交互五项，确认每一项是否在 Three.js 项目中有明确对应。单张图无法提供被遮挡面的真实信息，生成器只能补出假设；README 没有给出尺寸标定、拓扑修复或动画重建的承诺。把输出放进一个最小网页并打开控制台，能比静态截图更快发现导入、依赖和运行时错误。 本段对应小节“带确定性门控的分阶段雕刻循环”，核验时应把该小节提到的对象单独记录。
细节清单和特定主题的审查门控
在生成任何代码之前，流水线将主题分类为对象、角色或混合体。对象遵循硬表面流水线；角色则通过解剖学感知路径处理，该路径记录在 grimoire/character/reconstruction.md 中。细节优先分析构建一个 detailInventory，列出身份定义的小细节，如光泽、倒角、螺丝、线条和磨损。每个细节必须映射到真实的组件或材质条目，严格的质量门控会阻止生成，直到清单完成。对于 CS2 武器，特定于家族组件契约强制明确覆盖，审查门控防止逼真纹理替代真实几何结构。
图片到场景的过程包含语义猜测，因此结果是否有用取决于代码能否继续编辑。检查时可以把生成结果拆成相机、几何体、材质、光源和交互五项，确认每一项是否在 Three.js 项目中有明确对应。单张图无法提供被遮挡面的真实信息，生成器只能补出假设；README 没有给出尺寸标定、拓扑修复或动画重建的承诺。把输出放进一个最小网页并打开控制台，能比静态截图更快发现导入、依赖和运行时错误。 本段对应小节“细节清单和特定主题的审查门控”，核验时应把该小节提到的对象单独记录。
快速入门：克隆、调用并生成
通过将仓库克隆到技能目录来安装技能，例如 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. 该技能会分类主题、运行细节清单，并对每次通过进行门控。如需更多控制，你可以直接从技能根目录使用 Python 3.10+ 运行确定性脚本：probe_image.py、new_pre_spec_assessment.py、new_sculpt_spec.py、validate_sculpt_spec.py（带 --strict-quality）以及 generate_threejs_factory.py。README 显示了每个步骤的确切命令行。
图片到场景的过程包含语义猜测，因此结果是否有用取决于代码能否继续编辑。检查时可以把生成结果拆成相机、几何体、材质、光源和交互五项，确认每一项是否在 Three.js 项目中有明确对应。单张图无法提供被遮挡面的真实信息，生成器只能补出假设；README 没有给出尺寸标定、拓扑修复或动画重建的承诺。把输出放进一个最小网页并打开控制台，能比静态截图更快发现导入、依赖和运行时错误。 本段对应小节“快速入门：克隆、调用并生成”，核验时应把该小节提到的对象单独记录。
已发布版本和路线图
该项目已发布 v1.0（对象流水线）、v1.1（细节优先分析）、v1.2（人形角色生成器）、v1.3（Divine Eye 审查框架和 CIEDE2000 颜色数学）、v1.4（武器更新，用于 CS2 图像匹配重建）以及 v1.4.1（强化 CS2 路径）。还发布了包含四种身体计划的生物生成器。路线图继续包括 v1.5 角色更新、v1.6 环境更新、v1.7 游戏流水线更新（Unity 和 Unreal 导出器）、v1.8 动画更新、v1.9 AI 工作室更新以及 v2.0 程序化世界更新。完整路线图在 ROADMAP.md 中。
图片到场景的过程包含语义猜测，因此结果是否有用取决于代码能否继续编辑。检查时可以把生成结果拆成相机、几何体、材质、光源和交互五项，确认每一项是否在 Three.js 项目中有明确对应。单张图无法提供被遮挡面的真实信息，生成器只能补出假设；README 没有给出尺寸标定、拓扑修复或动画重建的承诺。把输出放进一个最小网页并打开控制台，能比静态截图更快发现导入、依赖和运行时错误。 本段对应小节“已发布版本和路线图”，核验时应把该小节提到的对象单独记录。
诚实的限制和 Apache 2.0 许可证
README 明确指出，单张图像无法揭示隐藏侧面或保证精确几何。输出可能近似、风格化或低多边形，未知面通过镜像可见面来推断，而不是伪造。该技能会报告每个区域的置信度，并可能返回"此图像无法达到请求的保真度"作为有效结果。角色是风格化重建，不是照片级相似。项目采用 Apache License 2.0，该许可证授予永久、全球、非独占、免费、免版税、不可撤销的版权许可，允许复制、准备衍生作品和分发。许可证文本未提及任何保证、支持或安全保证。
图片到场景的过程包含语义猜测，因此结果是否有用取决于代码能否继续编辑。检查时可以把生成结果拆成相机、几何体、材质、光源和交互五项，确认每一项是否在 Three.js 项目中有明确对应。单张图无法提供被遮挡面的真实信息，生成器只能补出假设；README 没有给出尺寸标定、拓扑修复或动画重建的承诺。把输出放进一个最小网页并打开控制台，能比静态截图更快发现导入、依赖和运行时错误。 本段对应小节“诚实的限制和 Apache 2.0 许可证”，核验时应把该小节提到的对象单独记录。
编辑结论
img2threejs 适合做概念验证：输入一张图片，借助图像理解和生成流程产出 Three.js 代码或场景草稿。它不等同于从照片得到精确的三维测量模型，README 未提供几何误差、纹理质量或复杂场景的基准，因此建筑、工业逆向等任务不能直接套用这个结论。评估时应查看仓库的提示词、生成代码入口和示例资产，固定同一张图片反复运行，重点观察摄像机、材质、灯光和模型层级是否可编辑。还要确认所需模型服务、API 凭据与前端运行方式，素材没有说明的部分不能补写成默认行为。
社区笔记