img2threejs：把一张参考图重建为可动画的 Three.js 代码模型

常见的图生 3D 路线是跑摄影测量、抽网格，或者下载现成资产；img2threejs 走的是另一条：给 Agent 一张参考图，让它写出一段 TypeScript，用 Three.js 的基本体、程序化着色器和生成几何把这个物体重新搭出来。产出是可 diff 的代码加一份 JSON 规格，不是几十 MB 的网格文件。仓库截至 2026-10-18 有 18,337 颗星，采用 Apache-2.0 许可，主要语言是 Python。

核心功能

• 输出是工厂函数，不是网格：结果是一个 THREE.Group 工厂，带运行时层级——枢轴、插槽和碰撞体，因此可以继续做动画。官网的演示画廊里每个模型都能在浏览器里旋转、对照原始参考图并直接读生成的源码。
• 分阶段重建，逐段自校正：管线依次走 blockout → structural → form → material → surface → lighting → interaction → optimization，每一段先生成再视觉对比，未过阈值就回到该段修。生成器只输出当前解锁的那一段，模型不用每轮重读整个工程。
• 严格质量门是失败关闭的：生成前先枚举 detailInventory，把高光、倒角、螺丝铆钉、刻线涂装、轮廓和磨损逐项映射到真实部件或材质；映射不全时门禁直接返回 BLOCKED，并附规格、失败指标、原因和下一步动作，不会写出一段凑合的代码。
• 脚本做机械活，模型只做判断：校验、门禁、规格编写、PBR 提取、对比图打包和管线状态都由 Python 脚本完成，脚本不评分；模型的 token 只花在一次看着「参考图 + 渲染图」并排图判过或不过。官方把这条设计称为 token-efficient 的来源。
• 按主题分流：主体会被分类为物体、角色或混合；物体走硬表面管线，角色走解剖感知路线（头身比、面部关键点、姿态）。对具体人物还提供可选的投影优先路径，同时明确说明单张图无法保证 100% 相似，管线会给出分区域置信度并在需要时要求更多视角。

典型使用场景

• 网页里的轻量 3D 展示：产品页想放一个能转、能动的模型，又不愿加载大网格文件时，代码模型天然更小、可版本管理，也方便按需改材质。
• 游戏或交互原型的快速占位：先拿参考图生成可动画的结构，确认比例和剪影，再决定是否投入正式美术。
• 需要可审查产物的团队：产出是 TypeScript 和 JSON 规格，能进 code review、能 diff、能回滚，比二进制资产更适合工程流程。
• 特定风格化对象：仓库附带 CS2 武器皮肤等域插件，把家族识别、涂装区域覆盖率和结构门禁写成可检查的规则。

边界同样明确：安装技能本身不会生成任何模型，必须由 Agent 按门禁逐步执行；主观相似度和动画质量不是 doctor 能证明的，只能看渲染对比与域门禁；私有 environment 插件需要授权的 Git 访问；镜头、光照和材质推断仍可能出错，单图重建对遮挡区域只能给出置信度。它也不是摄影测量工具，不接受「扫描真实物体」这类需求。和 DrawAI 把位图还原成可编辑矢量不同，img2threejs 的目标是重建出可运行的 3D 代码。

快速上手

npx --yes img2threejs@latest install --dry-run
npx --yes img2threejs@latest install

CLI 需要 Node.js 18+ 与 Git，重建脚本需要 Python 3.10+。安装器会检测 Hermes、Claude Code、Codex 等宿主；只想装进其中一个时用 --host claude。装完后在新会话里给 Agent 一张图并调用技能：

/img2threejs Rebuild the object in ./reference.png as a procedural Three.js model.
Keep its proportions, silhouette and colours. Follow the quality gates.
Report the output files, render-review evidence and any inferred regions.

想直接看效果，官网画廊里的每个模型都是生成代码在浏览器里实时运行。

小结

img2threejs 适合需要可编辑、可审查 3D 产物的前端与游戏开发者，以及希望把「图生模型」纳入工程流程而不是一次性出图的团队。它把大量机械工作压进确定性脚本、只在视觉判断上花 token，这个取舍让成本和可复现性都更可控；代价是流程更长，且依赖 Agent 严格执行门禁。项目 2026 年 7 月创建，迭代很快（10-17 仍有推送），README 自己标注部分演示仍是 placeholder 状态。仓库为 Apache-2.0，主要语言 Python，stats checked 2026-10-18。