Files
VibemakerSandbox/docs/superpowers/verification/rp1-glb-materials.md
T
chenlin a8be5e0134 feat: release v0.5 with shared interactive arenas and textured RP1
Unify lighting and line-colour controls across robots, replace the football with a shared layout of draggable physical props, and import the supplied RP1 GLBs without changing trained physics or policies.

Include reproducible visual import/provenance, regression coverage and verification records. Verified 66 unit tests, 55 browser tests and production-build checks.
2026-10-30 14:14:03 +08:00

5.2 KiB
Raw Blame History

RP1 用户 GLB 材质替换

输入与范围

  • 输入:/home/cen/Downloads/RP1机器人glb.zip,63 个自包含 GLB,未包含许可文件。
  • ZIP SHA-256:8610aac8432203bf68d0efe234062c551ca805ebbe72a92d5fc7350730ebdea2。
  • 仅新增 RP1 render.body_visuals 和可视资源;原 model.xml、STL、惯性、碰撞体、24 个驱动关节、ONNX、motion 文件均未修改。它们仍通过原 source-manifest.json 哈希验证。
  • 复用已有 BodyVisuals 渲染替换层,没有为本次替换修改共享渲染器、物理引擎或控制器。其他机器人材质、共享环境及色板不受影响。

坐标与部件适配

GLB 来自 Blender,顶点为 Y-up;现有 body 帧为 MuJoCo Z-up。所有挂载使用绕 X 轴 +90° 四元数。对全部 63 个输入 GLB,按此变换得到的包围盒与原始描述仓库对应 STL 包围盒逐项比较,最大差为 0。

当前训练模型是 25 个 body / 24 个受控关节,而该可视包包括完整的手腕和灵巧手:

  • 23 个普通 body 使用输入 GLB 原始字节,不改颜色或贴图。
  • 每侧手腕合并 20 个输入部件:wrist roll / yaw / pitch 三段、手掌及 16 个手指部件。
  • 按原始 rp1_hand_fixed.urdf 的相对原点和固定指节姿态组合;原 24-DOF 手腕对应 wrist-roll,额外 yaw/pitch 轴固定在中立位。
  • 合成 GLB 仅追加可视变换节点并重映射 GLTF 索引;顶点、索引、图像二进制数据以及 PBR 材质内容保留。
  • 最终为 25 个挂载 GLB,共覆盖 63 个输入部件,且每个部件只使用一次。没有新增手指/手腕物理自由度,也不声称支持独立手指控制。
  • 新手部的可视细节不会自动改变原训练模型的碰撞包络。

app/scripts/import-rp1-visuals.py 是可复现导入器;不会解压任意 ZIP 路径,在完成输入和合成输出验证后才写入包目录。visual-source-manifest.json 保存所有输入/输出 SHA-256、部件映射和复制的固定手 URDF 哈希。

已测定量结果

真实 Chromium / MuJoCo WASM / Three.js 中:

指标 结果
可视 body 挂载 25
手腕/手部源变换节点 40(每侧 20)
新可视 mesh 79
加载的法线贴图材质 77
面部屏幕颜色贴图 1
保留发光强度的标识材质 1
隐藏的原 STL 可视 mesh 25
body 姿态跟随误差 0
23 个原形状的三维包围盒最大误差 1.3124658082563911e-8 m
双手变换相对独立 URDF 计算最大误差 5.551115123125783e-16
行走观测 / 动作维度 243 / 24(不变)
MuJoCo actuator 数 24(不变)

根朝向及所有 24 个关节改变后再次验证上述坐标关系,不仅验证绑定初始姿态。

rp1-visuals.spec.js 还在同一会话、同一几何体布局和相同输入下,逐项精确比较替换前/后 walk / wave / dance 的 qpos、qvel、ctrl、观测、lastAction、状态机及参考帧;无任何容差放宽。部分 GLB 加载失败时旧机器人继续保留,释放候选资源后可直接 retry 成功。

测试与限制

  • 新增三个纯逻辑/资源测试与三个真实浏览器测试;首轮全部通过。
  • 所有 PBR 参数及贴图遵循用户原包,不另行重着色或简化。约 93 MB GLB、约 113 万三角形,首次加载量和 GPU 负担增加;不声称在所有设备具有相同帧率。
  • 资源未附许可,继续仅供本地评估;没有推断公开再分发授权,也没有公开发布。

最终执行结果

  • npm test:66/66 通过。
  • npm run validate:packages:四个 Package 均通过;RP1 为 58 条资源路径,原始物理/策略及新增 GLB 的来源哈希全部通过。
  • npm run format:check、npm run build、Python 语法检查、git diff --check:通过。
  • npm run test:e2e:55/55 通过(20.3 分钟)。含原有所有动作、共享环境、实时控制频率、新材质、加载失败恢复、20 次资源释放检查。
  • 20 次机器人切换时,RP1 GPU 资源保持 125 geometries / 80 textures / 21 listeners,各次完全相同;旧 model/data 均删除,未增加资源泄漏容差。该用例冷加载约三分钟,为避免新 93 MB 材质包在慢设备上贴近旧超时上限,测试时限单独由 180 秒调为 240 秒,资源断言原样保留。
  • 最终 dist/ 生产包复验:TEST_BASE_URL=http://127.0.0.1:5175 npm run test:e2e -- rp1-visuals shared-environment deployment --output=/tmp/rp1-material-production-artifacts,7/7 通过(3.9 分钟)。再次验证坐标/材质、替换前后逐项数值一致性、错误恢复、三机器人共享环境以及静态资源路径。
  • 人工查看前侧材质截图:蓝白灰配色、脸部屏幕、发光标识和双手外观正常;截图为 /tmp/rp1-material-production-artifacts/rp1-visuals-all-63-RP1-mat-8a18f-ith-original-shapes-aligned/rp1-material-front.png。对应开发测试截图亦在 app/test-results/rp1-visuals-all-63-RP1-mat-8a18f-ith-original-shapes-aligned/rp1-material-front.png。

日志:/tmp/rp1-visuals-unit.log、/tmp/rp1-material-full-e2e.log、/tmp/rp1-material-production-e2e.log;全量 JSON 结果另存 /tmp/rp1-material-full-results.json。