a8be5e0134
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.
65 lines
5.2 KiB
Markdown
65 lines
5.2 KiB
Markdown
# 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`。
|