# 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 的执行器是 ``,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 小时耐久或不同浏览器的保证。模型和策略许可按原文件与来源说明分别核对。