img2threejs — 代码重建三维模型
将参考图像中的物体，以纯代码、程序化、质量门控、可动画化的 Three.js 模型重建出来，且高效利用 token。
- Star 数
- ★ 18k
- 最近更新
- 11 天前
- License
- Apache-2.0
- 主语言
- Python
- FA 评分
- 45/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 希望在 Claude Code 中快速从参考图生成可动画化 Three.js 模型（如武器、硬表面物体）的游戏开发者
- 不适合
- 需要精确还原隐藏几何或照片级写实角色的团队
- 希望使用图形界面而非命令行工作流的用户
- 不愿安装 Python 3.10+ 并运行脚本的环境
这个 Agent 能做什么，适合哪些场景？
img2threejs 是一个智能体技能，它从一张参考图像出发，通过程序化建模（而非网格提取或下载美术资源）生成原生 Three.js 模型。它采用分阶段雕刻流程（blockout→structural→form→material→surface→lighting→interaction→optimization），每阶段由确定性 Python 脚本（如 validate_sculpt_spec.py、material_gate.py）进行严格质量门控。输出为 TypeScript 工厂函数，返回 THREE.Group，包含运行时层级（枢轴、插槽、碰撞体）以支持动画。该技能兼容多种智能体宿主（Claude Code、Codex、OpenCode），并利用宿主提供的视觉能力进行视觉审查。其设计目标为 token 高效：将机械性检查交给 Python 标准库脚本，模型 token 仅用于视觉判断与代码生成。项目包含可选的参考保真工具（如 SAM2、Depth Anything V2、MediaPipe）用于增强，但不参与门控决策。
该技能以单张物体图像为输入，通过 Python 脚本（probe_image.py、new_pre_spec_assessment.py、new_sculpt_spec.py）分析图像元数据、分类物体、清点细节清单（detailInventory），并生成 ObjectSculptSpec JSON。然后，generate_threejs_factory.py 根据当前解锁的 pass 生成 TypeScript 工厂代码（createObjectNameModel），并应用严格质量门禁，防止规格过浅时生成代码。每 pass 后，make_comparison_sheet.py 生成参考与渲染对比图，供智能体通过视觉判断通过/失败，并通过 append_review.py 记录。它支持可恢复工作流（forge/state.py、forge/next.py）、CS2 武器专项门控（cs2_review.py）以及可选的相机匹配、去光照、纹理投影（solve_camera_pose.py、delight_albedo.py、bake_projected_texture.py）。最终输出为可 diff 的 TypeScript 和 JSON 规格，而非二进制网格文件。
- 希望在 Claude Code 中快速从参考图生成可动画化 Three.js 模型（如武器、硬表面物体）的游戏开发者
- 需要精细控制模型细节和材质，并希望以代码方式审查和版本控制的 3D 艺术家
- 在 Codex 或 OpenCode 环境中工作，希望跨宿主使用同一技能并保持模型重建一致性的开发者
- 需要重建 CS2 武器（如 Glock-18、M9 Bayonet），并遵循严格结构审查门控的创作者
- 希望以低 token 成本进行图像转 3D 实验，避免高额 API 费用的个人开发者
如何安装或部署这个 Agent？
- 克隆仓库到技能目录：git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs。2. 如使用多个宿主，请保持单一检出，并在各宿主目录下创建符号链接指向该检出（例如~/.codex/skills/img2threejs）。3. 需要 Python 3.10+（仅标准库，无第三方依赖）。
如何使用这个 Agent？
在 Claude Code 中，附加或指向物体图像，并运行：/img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.。技能会自动分类对象、运行细节清单，并逐步引导通过各 pass，展示参考与渲染的并排对比，直到匹配。更多控制可通过附加指令实现，例如指定‘Fidelity’、‘Materials’、‘Runtime’或‘Gates’。对于多会话重建，可先用 python3 forge/state.py init --reference <image> --profile character --spec object-sculpt-spec.json 初始化状态，再用 python3 forge/next.py --state .img2threejs/state.json 恢复。可直接调用脚本，如 python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality。
这个 Agent 有哪些优点和局限？
- token 高效：将机械性任务交给 Python 标准库脚本，模型 token 仅用于视觉判断与代码生成
- 输出为可 diff 的 TypeScript 与 JSON 规格，支持版本控制和代码审查，而非二进制网格文件
- 提供严格质量门控（如 strict-quality、材质门控），确保规格深度，并带有 fail-closed 机制
- 支持多种宿主（Claude Code、Codex、OpenCode），具有良好的可移植性
- 提供可恢复工作流（forge/state.py），适合多会话重建
- 支持角色与 CS2 武器专项管线，并包含诚实的能力限制声明
- 单一参考图像无法保证隐藏细节或精确几何，需要用户接受近似结果
- 角色重建仅为风格化，而非照片级相似度
- 需要 Python 3.10+ 环境，尽管无第三方依赖，但仍需运行脚本
- 主要在 CLI 环境中使用，没有内置 GUI，可视化依赖宿主浏览器工具
- 对于特定物体（如 CS2 武器）的专项门控可能增加复杂度，需要学习曲线
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| img2threejs — 代码重建三维模型 当前 | 45 · 缺口较多 | Agent 插件 / 技能免费 + 模型费 | ★ 18k | 11 天前 | Python | Codex · Claude Code |
| Archimedes 专利工作台 | 证据不足 | — | ★ 104 | 6 天前 | TypeScript | Codex · Claude Code |
| Plannotator | 78 · 表现良好 | 命令行工具免费版 + 付费版 | ★ 9.5k | 今天 | TypeScript | Codex · Claude Code |
| NeuroSquad 终端控制台 | 76 · 表现良好 | 命令行工具免费 + 模型费 | ★ 53 | 5 天前 | TypeScript | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示仓库未提供权限声明、用户确认机制、数据流透明性、敏感数据处理、依赖安全、外部影响、回滚或来源归属的明确信息。所有信任相关标准均未得到满足，因此得分为0。
自一致性：README、架构文档和测试文件在描述上保持一致，例如强调纯标准库、无依赖、严格质量门控。依赖可用性：明确声明零依赖，仅需Python 3.10+，且测试使用标准库unittest，依赖风险低。失败消息：测试和文档中提及失败时返回BLOCKED并附有原因，但未提供具体示例，因此得分为2。
受众与场景：明确面向Claude Code、Codex、OpenCode等代理，并支持多种对象类型。能力边界：文档详细说明了支持的对象、角色、CS2武器等，并指出限制。触发精度：提供了明确的命令示例和参数说明。环境适配：支持多种宿主环境，并提供了安装和符号链接说明。
信息架构：文档结构清晰，有README、ARCHITECTURE、ROADMAP等。安装说明：提供了git clone和符号链接步骤。命名稳定性：版本号明确，有CHANGELOG。示例与FAQ：提供了多个演示和代码示例。已知限制：明确说明单张图片的局限性。许可证：Apache-2.0。版本与变更日志：有CHANGELOG和版本号。维护责任：有贡献指南和赞助链接，但未明确维护者身份，因此得分为1。
输出可用性：生成的TypeScript工厂和JSON规格可直接使用，并附带渲染和比较图。边际价值：提供了独特的代码生成方法，区别于传统网格提取。成本效益：强调token效率，但未提供具体成本数据，因此得分为2。
声明可追溯性：文档中的声明大多有对应文件或文档支持。跨来源佐证：有测试文件和CI配置，但未提供独立验证。事实与推断分离：文档明确区分了推断和事实，例如PBR证据是推断。
- 源码中未见：最小权限约束只授予完成任务所需的权限：用专用账号或只读令牌，并限定可访问的目录和仓库。
- 源码中未见：执行前用户确认开启或自行加上执行前确认；先在沙箱或测试环境跑通，确认行为后再接入真实数据。
- 源码中未见：数据流向说明运行时观察它连接了哪些外部服务（代理或防火墙日志）；弄清数据去向之前不要输入敏感数据。
- 源码中未见：敏感信息处理使用专用、低权限、可随时吊销的 API 密钥，不要复用生产凭据，也不要让密钥出现在日志里。
- 源码中未见：依赖安全审查安装前固定版本并做一次依赖扫描（如 npm audit、pip-audit）；优先放在容器里运行。
- 源码中未见：外部影响披露先弄清它会写入、发送或修改哪些外部系统，用测试账号或测试仓库验证后再接入正式环境。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 源码中未见：来源归属可核验从官方仓库或包源安装，核对发布者和仓库地址，避免同名仿冒包。
- 未提供权限声明或数据流透明性，使用前需自行审查。
- 依赖安全未明确，尽管声称零依赖，但需验证。
- 维护者身份未验证，更新路径不明确。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
v2.0.0 2.0.0: The Plugin Update
发布说明摘录
The Plugin Update. The plugin ecosystem — domain registry, img2 harness, plugin-served domains — ships as its own major, pulled forward from the original Procedural World bundle. Breaking - animated-character is served by the installed [plugin-character](https://github.com/img2threejs/plugin-character) (img2 add img2threejs/plugin-character, harness >= 0.2.3). The in-repo domain module is removed; without the plugin the profile fails loud naming what is available, and an in-flight workspace is refused while the provider is absent, resuming unchanged on reinstall. …在 GitHub 查看 ↗ -
v1.5.2 1.5.2: Support VFX / Animation for character
发布说明摘录
Changelog [1.5.2] — 2026-09-03 Theme: a clip that exists is not a clip that plays, and rigging may only add. Rigging failures in 1.5.1 were total and silent: clips held actions, the mixer held state, buttons dispatched, and nothing moved. This release turns the measured repair pipeline into executable modules, wires it into the workflow, and freezes the source geometry so binding cannot silently damage the model. Workflow integration Added - animated-character workflow profile (forge/_shared/workflow_state.py RIG_STEPS, …在 GitHub 查看 ↗ -
v1.5.1 1.5.1: add the GLB-reference route
发布说明摘录
[1.5.1] — 2026-08-23 Theme: the GLB-reference route. A GLB stops being an informal aid and becomes a measurement instrument with a packaged pipeline, three bounded prompts, and an explicit statement of which parameters it can be held to 1:1 and which it cannot. Added - Add integrations/glb_character_pipeline, an opt-in three-stage reconstruction — cross-section loft, implicit surface, TypeScript encode — carrying its own pyproject.toml and uv.lock so the stdlib-only forge core stays dependency-free. Nothing in forge/ imports it. Stage 1 reproduces …在 GitHub 查看 ↗