ROSView  ·  在线演示 →  ·  npm: @ioai/rosview  ·  English

高性能、浏览器原生的机器人数据可视化。从零构建的 Foxglove Studio 现代替代方案 —— 基于 React 19、Vite 8 与 Web Workers。

支持 MCAP、ROS 1 bag、ROS 2 db3、HDF5 与 BVH 文件。可作为独立 SPA（零安装，访问 rosview.com）或作为可嵌入的 npm 包使用。

文档

| 文档 | 说明 | |------|------| | 嵌入指南（中文） | 将 @ioai/rosview 集成到 React 应用（打包器、清单、排错）。 | | API 参考（中文） | 公开导出：RosViewer props、类型、偏好、布局工具、扩展。 | | 架构（英文） | 需求、设计与技术说明（SPA + npm）；中文版。 | | 开发（英文） | 本地环境、测试、Playwright、fixture。 | | 发版（英文） | 维护者流程：版本号、tag、npm 与 GitHub Release。 | | 贡献指南 | 分支流程、提交规范、PR 自检。 | | 安全策略 | 支持版本与负责任披露。 | | 文档索引（英文） | 全部文档路径一览。 |

English: README · Embedding · API · Architecture

功能特性

• 多格式 — MCAP · ROS 1 .bag · ROS 2 .db3 · HDF5 .h5/.hdf5 · BVH 骨骼动画
• Worker 解析 — 专用 Web Worker + Comlink；主线程尽量不被阻塞
• HTTP Range 流式加载 — 无需整文件下载即可开始回放
• 多面板布局 — 基于 DockView 的可拖拽、可停靠面板
• 可视化面板 — 图像（H.264）、3D（点云、URDF、TF）、Plot（uPlot）、关节、地图、音频、RawMessages、TopicGraph、位姿
• Foxglove 布局兼容 — 导入 / 导出 Foxglove Studio 布局
• 国际化 — English · 简体中文 · 日本語
• 明 / 暗 / 跟随系统 主题
• 扩展 API — 注册第三方侧边栏 Tab 与播放条上方叠加区域

快速开始（SPA）

在 Chrome 或 Edge 中打开 rosview.com，无需安装。

可通过 URL 参数直达文件：

https://rosview.com?url=https://your-server.com/recording.mcap
https://rosview.com?url=/examples/run.mcap
https://rosview.com?url=file://run.mcap
https://rosview.com?url=folder://MyDataset
https://rosview.com?url=sample://franka_stack
https://rosview.com?url=https://your-server.com/recording.mcap&theme=dark&language=zh

远程 manifest 与多 URL 请在 npm 集成时使用 fileManifest / urls props。

自托管

git clone https://github.com/ioai-tech/rosview.git
cd rosview
npm install
npm run dev          # 开发服务器 http://localhost:5173
npm run build        # 生产 SPA → dist/

嵌入（npm 包）

安装

npm install @ioai/rosview

Peer dependencies：项目中需已安装 React ≥ 19、react-dom ≥ 19、three、@react-three/fiber 与 @react-three/drei。

引入样式表

import '@ioai/rosview/style.css';

基本用法

import { RosViewer } from '@ioai/rosview';

export function MyApp() {
  return (
    <RosViewer
      url="https://your-server.com/recording.mcap"
      theme="dark"
      language="en"
    />
  );
}

加载本地文件

import { RosViewer } from '@ioai/rosview';

export function FileLoader() {
  const [file, setFile] = React.useState<File>();

  return (
    <>
      <input type="file" accept=".mcap,.bag,.db3,.h5,.hdf5,.bvh"
        onChange={e => setFile(e.target.files?.[0])} />
      {file && <RosViewer file={file} theme="system" />}
    </>
  );
}

多数据源 + 远程清单

<RosViewer
  urls={['https://cdn.example.com/run1.mcap', 'https://cdn.example.com/run2.mcap']}
  fileManifest="https://cdn.example.com/manifest.json"
  theme="dark"
  language="zh"
  onFatalError={(err) => console.error('Fatal:', err)}
/>

manifest.json 格式：

[
  { "url": "https://cdn.example.com/run1.mcap", "name": "Run 1", "sizeBytes": 1073741824 },
  { "url": "https://cdn.example.com/run2.mcap", "name": "Run 2", "durationSec": 120 }
]

支持的文件格式

| 格式 | 扩展名 | 说明 | |------|--------|------| | MCAP | .mcap | ROS 2 / 机器人常用；zstd、lz4 压缩 | | ROS 1 bag | .bag | ROS 1 录制格式 | | ROS 2 SQLite | .db3 | ROS 2 默认录制（sql.js WASM） | | HDF5 | .h5, .hdf5 | 科学数据；@ioai/hdf5 WASM 读取 | | BVH | .bvh | 动作捕捉骨骼动画 |

所有格式均在浏览器内通过 Web Worker 解析，无需服务端转码。

键盘快捷键

| 按键 | 作用 | |------|------| | Space | 播放 / 暂停 | | ← / → | 上一帧 / 下一帧 | | [ / ] | 减速 / 加速 | | Home | 跳到开头 | | End | 跳到结尾 |

URL 参数（SPA）

| 参数 | 示例 | 说明 | |------|------|------| | url | ?url=https://…/file.mcap 或 ?url=/examples/run.mcap | 单个远程文件；加载/切换时用 pushState 更新 | | url | ?url=file://name.mcap | 本地文件定位符（从「最近打开」/IndexedDB 句柄恢复） | | url | ?url=folder://MyDataset | 本地文件夹定位符 | | url | ?url=sample://franka_stack | 示例 id（依赖构建时 manifest：VITE_SAMPLE_DATASETS_MANIFEST_URL / VITE_SAMPLES_BASE_URL） | | theme | ?theme=dark | light · dark · system | | language | ?language=zh | en · zh · ja |

多远程 URL 或远程 manifest 请使用 npm 嵌入时的 urls / fileManifest props，独立 SPA 查询串只维护单个 url。

API 参考

完整组件 props、TypeScript 类型、工具函数与高级嵌入模式见 docs/API.zh.md（或英文 docs/API.md）。

参与贡献

欢迎 Issue 与 Pull Request。提交前请先阅读 CONTRIBUTING.md。

• 缺陷报告 — 使用 Bug Report 模板
• 功能建议 — 使用 Feature Request 模板
• 安全漏洞 — 见 SECURITY.md

许可

MIT © 2026 IO-AI Tech