Files
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

65 lines
5.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`。