Files

82 lines
6.8 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.
# Microban 浏览器 Package
## 首期功能
- 在工具栏 Robot 中选择 Microban;默认使用平台统一 `arena` 模板,按名义站立高度 0.33 m 相对 Microduck 0.27 m 等比适配:内部 **5.5 × 5.5 m**,墙高约 **0.306 m**、厚约 **0.061 m**,四边为真实碰撞盒。
- 内部仍是平地,无高度场;复用 Microduck 的暗色橙色网格、围墙视觉、comic/CRT 和背后相机。重力、驱动、policy 参数不变;不是用坐标夹紧伪造边界。
- 有界默认场地的运动验收为三轮各 70 s;另用显式 `flat` 诊断场地保留三轮各 84 s 原长距离协议,二者不能混称。
- 导入/切换后默认在机器人背后跟随;鼠标拖拽切换到自由环绕,按 **C** 恢复背后跟随和默认距离。C 在暂停时也有效,重复按不会关闭跟随。
- 方向键 / WASD 前后走和转向;H 独立开关转头;Esc 暂停;Space 重置。
- 按键面板中的转头条目也可点击。转头不会切断行走,暂停时技能计时停止。
- 跌倒显示 `Robot fallen`,停止策略更新,使用 Space / Reset 手动重置。没有自动起身或 Placo 下蹲。
## 资产与来源
`app/public/robots/microban/` 包含:
- `model.xml` 与它实际声明的 25 个 STL;原模型不修改,运行时组合空地与 timestep。
- `policies/walk.onnx`。
- `visuals/*.glb`:用户提供的新版 `microban2.zip` 中 20 个原始 GLB,保留 PBR 材质和 46 张内嵌纹理(45 张法线贴图及 1 张屏幕颜色贴图);替代白模显示,不替换物理网格。
- `visual-source-manifest.json`:视觉压缩包和逐文件 SHA-256,与原物理 / 策略来源记录分开。压缩包没有许可说明,公开分发前需向资产所有者确认。
- `source-manifest.json`:源 remote、HEAD、dirty 标志、逐文件 SHA-256、行为参考代码哈希。
- `SOURCE.md` 和 `LICENSES/`:原项目混合许可文本、XML 的 Apache-2.0 许可文本和归属说明。
源仓库为 `https://github.com/Rhoban/microban.git`,导入时 HEAD 为 `d0a128d180ecfce69eaaf31b295a0fce31280bfd`,**工作区含未提交修改**。因此不能只凭 HEAD 复现参考行为,须同时保留 manifest 的实际文件哈希。导入命令:
```bash
python3 app/scripts/import-microban.py /path/to/microban
npm --prefix app run validate:packages
```
导入是显式离线维护操作,不是运行或构建的依赖;日常运行不读取源仓库、不要求 Python / BAM / Placo。导入后需检查是否有实质变化,不自动接受策略 / 行为更新。
## 带纹理外观
刷新页面后选择 Microban 即使用新外观:浅紫外壳、蓝色金属支架、黑色电机及带颜色贴图的屏幕。新版 20 个 GLB 的顶点位置和节点变换与上一版一致,保留现有部件绑定。`render.body_visuals` 将 BASE、LINK1–19 映射到已有的 20 个 MuJoCo body,显式记录米制平移和 xyzw 单位四元数。坐标变换经原几何对齐检查;部件包围盒端点差异最大约 3 mm,包含新外观的螺丝等细节,不是运行时自动猜测比例或改变关节姿态。
所有部件每帧读取原 `xpos/xquat`,包括独立转头;原 visual geom 隐藏,碰撞、质量、惯量、关节、策略和 PD 均保留。GLB 加载失败会放弃候选机器人并恢复旧机器人,不会以静默白模掩盖缺失资源。切换时释放几何、材质、纹理和 ImageBitmap。
```bash
python3 app/scripts/import-microban-visuals.py /path/to/microban2.zip
npm --prefix app run validate:packages
npm --prefix app run test:e2e -- microban-visuals.spec.js microban-walking.spec.js runtime-leaks.spec.js
```
`microban-visuals.spec.js` 验证 20 个 body 的材质/纹理、原 visual 隐藏、非零根 yaw 和关节角下的对齐、失败回退,以及开关新视觉后 80 个控制周期的 qpos / qvel / ONNX action 逐项完全一致。截图保存于该测试的 `test-results/` 输出目录。行走原有三轮有界 70 s、三轮无界诊断 84 s 和 H / reset / 近 50 Hz 验证通过;20 次跨 Microduck / Microban / RP1 切换后,Microban 的 GPU 纹理数稳定为 48(46 张模型纹理加场景资源),无增长。
## 策略接口
| 项目 | 数值 |
|---|---|
| 输入 | `obs`,float32 `[1,63]` |
| 输出 | `actions`,float32 `[1,18]` |
| 模型 / metadata 关节 | 19,包含 head |
| actor 关节 | 18,显式顺序见 robot.json,不含 head |
| 观测 | gyro 3 + trunk projected gravity 3 + joint pos rel 18 + joint vel 18 + lastAction 18 + twist 3 |
| 时钟 | 物理 0.005 s;每 4 子步推理一次(50 Hz) |
| 参考相位 | 当前策略不含额外 cos / sin 项 |
metadata 的 `joint_names/default_joint_pos` 按名字筛选,不能直接按 19 项顺序分发给 18 维输出。head 的初始目标为 0,由 overlay 管理,不进入 actor 的 lastAction。
IMU 安装四元数为 `(0.5,-0.5,-0.5,0.5)`。gyro 保留 MJCF IMU site frame;重力采用 trunk frame,等价于从 orientation sensor 的四元数扣除安装旋转再做重力逆旋转。测试以非零角速度和 45° 倾角验证这两个坐标系没有被错误合并。
head 使用源项目的正弦运动:0.35 Hz、幅值 ±π/4;进入与退出各 0.5 s 插值,关闭后回到 0。计时取仿真时间,不依赖墙钟。
## 简化执行器
原始 MJCF 的执行器是 `<motor>`,ctrl 表示力矩,不是目标角。浏览器 actor 输出首先生成关节目标,然后每个物理子步计算:
```text
tau = clamp(0.3 * (target - q) - 0.02 * dq, -0.65, 0.65)
```
这是实验选择的简化参数,**不是 ONNX metadata stiffness 的直接套用,也不是 BAM 或实机等价模型**。保留模型原有阻尼与惯性参数;不模拟电压下降、电流限制、非线性摩擦和通信 / 传感器延迟。
默认命令为前进 0.15 m/s、后退 −0.1 m/s、转向 ±0.6 rad/s。这是通过当前验收的默认命令,不保证精确速度或航向跟踪。持续前进仍可能发生航向 / 横向漂移;不能把稳定不跌倒等同于导航精度。
## 验证与限制
`microban-walking.spec.js` 从重置状态完成三轮,每轮 84 s 仿真:站立、前后走、左右转、停顿、行走中转头、关闭转头。检查实际位移方向、展开的 yaw、head 幅度 / 回正、无跌倒 / 重置,并记录 PD 饱和统计。另有真实墙钟下近 50 Hz 测试、H 按键、跌倒手动 reset 与 IMU 坐标系测试。
初始策略接入详见 [验收记录](../superpowers/verification/2026-10-27-multi-robot-platform.md);当前场地尺寸与碰撞验证见 [按机器人尺寸缩放场地](../superpowers/verification/2026-10-28-robot-scaled-arena.md)。只对记录的桌面 Chromium / WASM 组合做过验证;没有实机、移动端、手柄 / 触屏、15 小时耐久或不同浏览器的保证。模型和策略许可按原文件与来源说明分别核对。