ROSView  ·  Live Demo →

简体中文文档 - README.zh.md

High-performance, browser-native robotics data visualization. Built from scratch on React 19, Vite 8, and Web Workers.

Supports MCAP, ROS 1 bag, ROS 2 db3, HDF5, and BVH files. Available as a standalone SPA (zero-install, runs at rosview.com) or as an embeddable npm package.

---

Documentation

Document	Description
Embedding guide	Integrate @ioai/rosview into a React app (bundler, manifest, troubleshooting). Chinese: EMBEDDING.zh.md.
API reference	Public exports: RosViewer props, types, preferences, layout helpers, extensions. Chinese: API.zh.md.
Architecture	Requirements, design, and technical notes (SPA + npm). Chinese: ARCHITECTURE.zh.md.
Development	Local setup, tests, Playwright, fixtures.
Release	Maintainer workflow: versioning, tags, npm & GitHub Releases.
Contributing	Branch workflow, commits, PR checklist.
Security	Supported versions and responsible disclosure.
Docs index	Full map of all documentation files.

Simplified Chinese: README · Embedding · API · Architecture

---

Features

• Multi-format — MCAP · ROS 1 .bag · ROS 2 .db3 · HDF5 .h5/.hdf5 · BVH skeletal animation
• Zero-copy parsing — dedicated Web Workers + Comlink; main thread is never blocked
• HTTP Range streaming — load remote files without downloading them in full
• Multi-panel layout — draggable, dockable panels powered by DockView
• Visualization panels — Image (H.264), 3D (point clouds, URDF, TF), Plot (uPlot), Joints, Map, Audio, RawMessages, TopicGraph, Pose
• Internationalization — English · Simplified Chinese · Japanese
• Dark / light / system theme
• Extension API — register third-party sidebar tabs and playback-track overlay regions

---

Quick Start (SPA)

Open rosview.com in Chrome or Edge — no installation required.

You can deep-link directly to a file via URL parameters:

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

Remote manifests and multiple URLs are supported via the fileManifest / urls props when embedding the npm package.

Self-host

git clone https://github.com/ioai-tech/rosview.git
cd rosview
npm install
npm run dev          # development server at http://localhost:5173
npm run build        # production SPA → dist/

---

Embedding (npm package)

Installation

npm install @ioai/rosview

Peer dependencies: React ≥ 19.2 (including 19.3) and react-dom ≥ 19.2, plus three (≥ 0.173). @react-three/fiber and @react-three/drei are no longer required. If you installed them only for ROSView, uninstall them. Keep them as host dependencies if your app still uses React Three Fiber for its own canvases. Other runtime libraries are bundled inside @ioai/rosview — do not add them as extra host dependencies. See Embedding guide.

Import the stylesheet

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

Basic usage

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

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

Load local files

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" />}
    </>
  );
}

Multiple sources + remote manifest

<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 format:

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

---

Supported File Formats

Format	Extension	Notes
MCAP	.mcap	ROS 2 / robotics standard; zstd and lz4 compression
ROS 1 bag	.bag	ROS 1 recording format
ROS 2 SQLite	.db3	ROS 2 default recording (via sql.js WASM)
HDF5	.h5, .hdf5	Scientific data; partial read via @ioai/hdf5
BVH	.bvh	Skeletal motion capture animation

All formats are parsed entirely in the browser via Web Workers — no server-side processing required.

---

Keyboard Shortcuts

Key	Action
Space	Play / Pause
← / →	Step backward / forward one frame
[ / ]	Decrease / increase playback speed
Home	Jump to start
End	Jump to end

---

URL Parameters (SPA)

Parameter	Example	Description
url	?url=https://…/file.mcap or ?url=/examples/run.mcap	Single remote file; updated on load/switch via pushState
url	?url=file://name.mcap	Local file locator (replay from Recent / IndexedDB handles)
url	?url=folder://MyDataset	Local folder locator (replay from Recent directory handle)
url	?url=sample://franka_stack	Sample id from the build-time manifest (VITE_SAMPLE_DATASETS_MANIFEST_URL / VITE_SAMPLES_BASE_URL)
theme	?theme=dark	light · dark · system
language	?language=zh	en · zh · ja

Multiple remote URLs or a remote manifest JSON URL are supported via the urls / fileManifest props when embedding the library, not via extra query keys in the standalone SPA.

---

API Reference

See docs/API.md for the complete component props, TypeScript types, utility functions, and advanced embedding patterns. Chinese: docs/API.zh.md.

---

Contributing

We welcome issues and pull requests! Please read CONTRIBUTING.md before submitting.

• Bug reports — use the Bug Report template
• Feature requests — use the Feature Request template
• Security vulnerabilities — see SECURITY.md

---

License

MIT © 2026 IO-AI Tech