img2threejs:把参考图重建为纯代码Three.js模型

一句话定位

img2threejs 是一个跑在 Claude Code、Codex、OpenCode 等编码代理里的 Agent 技能:给一张物体或角色的参考图,它把图中的对象重建为纯代码、程序化的 Three.js 模型。它明确拒绝三条路线——摄影测量、网格提取(图生网格模型)、现成资产包——交付物是一个用 primitive、程序化 shader 与生成几何拼出 THREE.Group 的 TypeScript 工厂函数,外加一份记录组件树、材质、插槽与评审历史的 ObjectSculptSpec JSON。模型因此可 diff、可版本控制、可逐行审查。

项目于 2026 年 9 月发布 v2.0.0,Apache-2.0 协议,GitHub 星标超过一万五千。官网 img2threejs.io 的 live demo 画廊里,每个模型都是生成代码在浏览器中实时运行,没有网格文件、没有下载。

八段式雕刻流水线

重建不是一次成型,而是按固定顺序推进:blockout、structural-pass、form-refinement、material-pass、surface-pass、lighting-pass、interaction-pass、optimization-pass。每一段有独立验收标准,上一段的渲染、对比图与视觉评分通过后下一段才解锁;代码生成器只输出当前解锁的那一段,模型不必在每次迭代时重读或重写整个模型。

两个容易被忽略的设计都来自事故:几何门禁跑在浏览器渲染之前——秃斑、自交在点集层面就被发现,不会浪费一段渲染预算去渲染本来就错的几何;流水线路由可以拒绝——当「武器还是角色」的置信度低于 0.82,流程转入 request-input 向用户要更多信息,而不是猜。

门禁系统:让「看着像」不可通过

strict-quality 门禁在代码生成前拦下过浅的 spec:复合物件不允许只有一棵单根组件树。chirality 门禁要求每一对左右部件必须是矢状面镜像而非旋转副本——旋转保持手性,把两个轴取反会得到两只同一只手。针对有头发角色的 scalp-exposure 是硬门禁,且跑在几何上,因为秃斑是内部缺陷,轮廓指标看不见。

评审段要求「真实渲染 + 单张对比图 + 视觉评分达标 + 分带内部差异达标」。加入内部差异是因为一个实测失败案例:轮廓 IoU 只读到角色约 11% 的像素,给删掉脸的版本与完成版打了相同的分数。材质与光照门禁要求独立 PBR 通道与真实光源,不允许把 albedo 混进 roughness 里冒充质感。

脚本与模型的分工:把 token 花在判断上

forge/ 目录约九十个 Python 模块,全部纯标准库:PNG 读写用 struct 与 zlib 手写,不引 PIL、numpy、Playwright。脚本负责校验、门禁、spec 生成、PBR 证据抽取与对比图打包,从不给视觉打分;模型的 token 只用于一件事——看一张「参考图对渲染图」的并排对比图,判定通过与否。工厂生成器 fail-closed:门禁不过就返回 BLOCKED,附上 spec 工件、失败指标与下一步动作,不写一行代码。

材质与角色子系统

材质身份是一条可执行子流水线:命名组件区域、验证裁剪、版本化 Three.js 材质注册表解析、参考图导出的 PBR 证据与有界先验、写入 ObjectSculptSpec、生成后多角度与显微镜级取景、逐区域比较器与有界反馈,最后由 material gate 解锁。注册表从不只凭颜色下结论,低置信区域保持 probe 或 request-input。

角色路线有独立解剖轨道:头身比例、面部 landmarks、姿态;骨骼从组件树推导,骨头无法与几何漂移;蒙皮用穿过实体内部测量的测地距离,让刚性部件留在平滑蒙皮之外;头发是五阶段子系统并带硬秃斑门禁。相似度最大化与多视角轮廓雕刻(visual hull)均为 opt-in:前者把参数化模板拟合到 landmarks、去光照、匹配相机后投影参考图;后者用至少两张正交二值轮廓相交出焊接体素网格,把看不见的区域记为低置信,而不是编造隐藏细节。

v2.0 插件生态

领域知识在 v2.0 被拆出主仓,成为可安装插件,由 img2 harness(install/add/doctor)管理:plugin-cs2 提供 CS2 武器皮肤重建的家族适配器与评审门禁,plugin-character 提供含 Stage R 绑定与动画的完整角色工作流,plugin-img2glb 提供经托管 TRELLIS 的 image 到 GLB 输出目标,plugin-hello-cube 是写自定义插件的最小样板。插件的质量下限合并时只升不降;某个 profile 对应的插件缺失时会大声失败并点名缺什么,绝不静默降级。

边界与诚实

单张图看不到隐藏面,也无法保证精确几何。技能在文档里把这点写明:未见面由可见面镜像推断并标注为近似;角色是风格化重建而非照片级相似;「这张图达不到要求的保真度」是合法且预期的输出。GLB 参考路线把 GLB 只当测量仪器——量尺寸、比例、分段宽度、基色、粗糙度、金属度——交付物仍是程序化 TypeScript,运行时不取任何 .glb 或 .bin。

为什么值得看

主流图生 3D 交付网格:文件大、难改、难进版本控制。img2threejs 交付代码:同一张参考图得到的是可审查、可 diff、可直接绑骨骼动画的 TypeScript 工厂,运行时层级里暴露 pivots、sockets 与 colliders。对游戏道具、网页可视化与数字内容管线,这是另一种资产形态。路线图按版本一主题推进:v2.1 角色域迁入插件、v2.2 环境、v2.3 游戏引擎导出、v2.4 自动绑定,v3.0 目标是从参考图生成可玩世界。