English: USER_MANUAL.md
在首页欢迎屏幕点击 "Open ROS File"，或将 .mcap、.bag、.db3、.h5/.hdf5、.bvh 文件拖拽至窗口。支持一次拖入多个文件。
点击 "Open Directory" 选择文件夹，ROS View 将自动扫描目录内所有支持的录制文件，并在侧边栏 Data 标签中列出。
在欢迎屏幕的远程 URL 输入框粘贴链接，或通过 URL 参数直接打开：
https://rosview.com?url=https://your-server.com/recording.mcap
远程服务器需支持 HTTP Range 请求和 CORS 跨域头。大文件无需等待完整下载即可开始播放。
若要从 JSON 清单展示多个可切换的远程录制，请在你自己的页面中嵌入 ROS View，并传入 fileManifest prop（清单 URL 字符串或已解析的行数组）。公开的 rosview.com 独立 SPA 仅在地址栏维护单个 ?url=，不会从查询参数读取 manifest。
清单格式：
[
{ "url": "https://cdn.example.com/run1.mcap", "name": "运行1", "durationSec": 120 },
{ "url": "https://cdn.example.com/run2.mcap", "name": "运行2" }
]- 拖拽：点击面板标签并拖拽以重新排列或停靠面板。
- 关闭：点击标签上的 × 按钮关闭面板。
- 自动排版：文件加载后，系统根据检测到的 Topic 类型自动生成最优布局。
- 分割：将面板标签拖拽到其他面板的边缘即可分割视图。
| 标签 | 说明 |
|---|---|
| Topics | 显示录制文件中的所有话题，包含消息类型、频率和消息计数。点击话题可快速添加对应面板。 |
| Data | 列出已加载的文件/数据集，点击可切换当前播放文件。 |
| Annotations | 管理时间段标注，用于数据审查工作流。 |
通过导航栏右侧的 布局菜单 可以：
- 将当前面板排列导出为 JSON 布局文件
- 导入已保存的布局
- 导入 Foxglove Studio 的布局文件
点击时间轴任意位置即可 Seek 到对应时刻。半透明区域表示已缓存的数据范围（远程文件时有意义）。
在播放栏右侧选择播放倍速：0.1× 0.25× 0.5× 1× 2× 4× 8× 或 最大速度。
使用步进按钮（或键盘方向键）按帧前进或后退。
打开侧边栏 Annotations 标签使用内置的时间段标注功能。
- 创建标注：在时间轴上拖拽选取时间范围，填写标签表单。
- 标记当前时刻：点击 "Add Marker" 标记当前播放位置。
- 跳转到标注：点击标注列表中的任意条目即可跳转到该时刻。
- 导出：点击 "Export" 将所有标注下载为 JSON 文件，与数据处理管线兼容。
- 导入：加载之前导出的标注或来自外部工具的标注文件。
| 按键 | 功能 |
|---|---|
Space |
播放 / 暂停 |
← / → |
后退 / 前进一帧 |
[ / ] |
减慢 / 加快播放倍速 |
Home |
跳到开头 |
End |
跳到末尾 |
| 现象 | 解决方法 |
|---|---|
| 文件加载失败 | 确认文件格式是否支持（.mcap、.bag、.db3、.h5、.bvh）。远程文件请确认服务器已配置 CORS 头和 Range 请求支持（Accept-Ranges: bytes）。 |
| 播放卡顿 | 关闭未使用的面板，或减少 Plot 面板订阅的话题数量。 |
| 3D 视图为空 | 确保录制文件包含 /tf 或 /tf_static 话题，且 3D 面板已订阅相关话题。 |
| WASM 解码器报错 | 部分浏览器在缺少 COOP/COEP 头时会阻止 SharedArrayBuffer。需要服务器返回 Cross-Origin-Opener-Policy: same-origin 和 Cross-Origin-Embedder-Policy: credentialless。 |
| 远程文件启动慢 | 服务器可能不支持 Range 请求，导致需要完整下载才能开始播放。检查响应头中是否包含 Accept-Ranges: bytes。 |