Metadata-Version: 2.4
Name: ros-rerun-bridge
Version: 0.18.0
Summary: Config-driven, pluggable ROS2 -> Rerun bridge
Author-email: Saif Sidhik <mail@saifsidhik.page>
License-Expression: MIT
Project-URL: Homepage, https://github.com/justagist/ros_rerun_bridge
Project-URL: Documentation, https://github.com/justagist/ros_rerun_bridge#readme
Project-URL: Repository, https://github.com/justagist/ros_rerun_bridge
Project-URL: Issues, https://github.com/justagist/ros_rerun_bridge/issues
Project-URL: Changelog, https://github.com/justagist/ros_rerun_bridge/blob/main/CHANGELOG.md
Keywords: ros,ros2,rerun,visualisation,robotics,rviz
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rerun-sdk==0.40.0
Requires-Dist: numpy>=2
Requires-Dist: pyyaml
Requires-Dist: scipy
Requires-Dist: pydantic>=2.0
Requires-Dist: empy
Requires-Dist: lark
Dynamic: license-file

<div align="center">

# ros-rerun-bridge

**Your ROS 2 topics in Rerun, from one YAML file. No code.**

[![CI](https://github.com/justagist/ros_rerun_bridge/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/justagist/ros_rerun_bridge/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/ros-rerun-bridge.svg)](https://pypi.org/project/ros-rerun-bridge/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/justagist/ros_rerun_bridge/blob/main/LICENSE)
[![ROS 2 Jazzy](https://img.shields.io/badge/ROS%202-Jazzy-22314E.svg)](https://docs.ros.org/en/jazzy/)
[![ROS 2 Lyrical](https://img.shields.io/badge/ROS%202-Lyrical-22314E.svg)](https://docs.ros.org/en/lyrical/)
[![Rerun 0.40](https://img.shields.io/badge/Rerun-0.40-0B8CE9.svg)](https://rerun.io)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)

</div>

Show live ROS 2 data in the [Rerun](https://rerun.io) viewer, as you would in rviz. All you write is a config file listing the topics you want to see: the bridge subscribes to them and sends each message to Rerun, drawing spatial data in its TF frame. The [built-in modules](#modules) need no code.

```yaml
global_frame: map
modules:
  - name: camera
    module: image
    topic: /camera/image_raw
    entity_path: camera/image
  - name: scan
    module: laserscan
    topic: /scan
    entity_path: scan
```

```bash
ros-rerun-bridge --config my_robot.yaml
```

Or skip the config, and let the bridge find the topics it can show:

```bash
ros-rerun-bridge --auto --global-frame world  # use the global frame you would set in rviz
```

> **Status:** I created this repository mainly to get familiar with Rerun and to use it in my own ROS projects. It is under active development, so features, interfaces and behaviour may change. Tested with Rerun 0.40.0 and ROS 2 Jazzy and Lyrical.

## Demos

**Nav2:** the [Nav2 getting started demo](https://docs.nav2.org/jazzy/getting_started/quickstart/quickstart/) with [this config](https://github.com/justagist/ros_rerun_bridge/blob/main/examples/nav2_turtlebot3/config.yaml).

[![ros_rerun_tb3_sim.mp4](https://media.githubusercontent.com/media/justagist/_assets/main/ros_rerun_bridge/ros_rerun_tb3_sim.gif)](https://media.githubusercontent.com/media/justagist/_assets/main/ros_rerun_bridge/ros_rerun_tb3_sim.mp4)

**MoveIt:** `ros2 launch moveit_resources_panda_moveit_config demo.launch.py` with [this config](https://github.com/justagist/ros_rerun_bridge/blob/main/examples/moveit_panda/config.yaml).

[![ros_rerun_franka_moveit.mp4](https://media.githubusercontent.com/media/justagist/_assets/main/ros_rerun_bridge/ros_rerun_franka_moveit.gif)](https://media.githubusercontent.com/media/justagist/_assets/main/ros_rerun_bridge/ros_rerun_franka_moveit.mp4)

## Features

* **Config, not code:** one YAML file says which topics to show and how, and is checked when the bridge starts.
* **TF and URDF aware:** data is drawn in its TF frame. The robot model is loaded from its URDF and moves with TF or joint states.
* **rviz's common displays:** robot model, images, point clouds, laser scans, range sensors, markers, maps and costmaps, and more (see [Modules](#modules)).
* **Remote viewing:** any number of native or browser viewers can connect to a bridge running on a robot.
* **Extensible:** support a new message type with a small module class, in this package or in your own.

## Quick start

You need ROS 2 (Jazzy or Lyrical), and [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/). Install the bridge from PyPI in an environment of its own, which both create, as Rerun needs NumPy 2 and Jazzy ships NumPy 1:

```bash
uv tool install --python-preference only-system ros-rerun-bridge  # or: pipx install ros-rerun-bridge
```

Do not `pip install` it into the system Python: on Jazzy, its NumPy 2 would break other ROS nodes.

You can start straight away, with no config. With your robot or simulator running, the bridge shows every topic it can draw, as it appears:

```bash
source /opt/ros/jazzy/setup.bash  # or lyrical
ros-rerun-bridge --auto --global-frame world  # use the global frame you would set in rviz
```

To choose what is shown, and how, list the topics in a [config](#configuration). To see one in action, try an example from a clone of this repo:

```bash
git clone https://github.com/justagist/ros_rerun_bridge.git && cd ros_rerun_bridge
source /opt/ros/jazzy/setup.bash  # or lyrical
ros-rerun-bridge --config examples/robot_arm/config.yaml
# In a second terminal, from the repo root with ROS sourced: publish a small arm's URDF and joint states
python3 examples/robot_arm/publisher.py
```

This opens the Rerun viewer, showing the arm moving and its joint positions plotted. The publisher only provides demo data: with a real robot, the bridge needs just a config listing its topics. [examples](https://github.com/justagist/ros_rerun_bridge/blob/main/examples) has more, each runnable the same way.

![robot_arm](https://media.githubusercontent.com/media/justagist/_assets/main/ros_rerun_bridge/examples/robot_arm.gif)

See [INSTALLATION.md](https://github.com/justagist/ros_rerun_bridge/blob/main/docs/INSTALLATION.md) for other ways to install, e.g. running from a clone without installing, and why the bridge needs its own environment.

## Usage

```bash
ros-rerun-bridge --config <config.yaml> [options] [-- <ROS arguments>]
ros-rerun-bridge --auto [--config <config.yaml>] [options] [-- <ROS arguments>]
```

| Option | |
| --- | --- |
| *(no option)* | Open a Rerun viewer. |
| `--auto` | Also show the topics the config does not list, as they appear ([automatic discovery](https://github.com/justagist/ros_rerun_bridge/blob/main/docs/CONFIGURATION.md#automatic-discovery)). |
| `--global-frame <frame>` | The TF frame the 3D view is drawn in. Overrides the config's `global_frame`. |
| `--connect [--url <url>]` | Send to a Rerun viewer that is already running. |
| `--serve [--allow-origin <pattern>]` | Let viewers on other machines connect ([REMOTE_VIEWING.md](https://github.com/justagist/ros_rerun_bridge/blob/main/docs/REMOTE_VIEWING.md)). |
| `--save <file.rrd>` | Record to a file, to open later with `rerun <file.rrd>`. |
| `--stdout` | Stream to standard output, to pipe into `rerun -`. |
| `--headless` | Run without a viewer. |
| `--version` | Print the version. |

Arguments after `--` are passed to ROS, e.g. `-- --ros-args -p use_sim_time:=true`.

### Recordings and bags

Recording, with `--save`, and opening recordings are Rerun's features: see [Rerun's docs](https://rerun.io/docs/getting-started/data-in/open-any-file). To view a ROS bag as a live robot would be shown, play it into the bridge on the bag's clock:

```bash
ros-rerun-bridge --config <config.yaml> -- --ros-args -p use_sim_time:=true
ros2 bag play <bag> --clock
```

Rerun can also open an `.mcap` bag directly, without the bridge, converting [common ROS 2 messages](https://rerun.io/docs/reference/mcap/message-formats) itself. The bridge covers more, such as markers, laser scans, the robot model and diagnostics, and keeps a config's layout.

## Configuration

A config lists the topics to show. Each topic is handled by a module, which decides how it is drawn:

```yaml
global_frame: map            # the TF frame the 3D view is rendered in
modules:
  - name: tf
    module: tf
    topic: /tf
    entity_path: tf
  - name: scan
    module: laserscan
    topic: /scan
    entity_path: scan
    qos: { reliability: best_effort }   # most sensor drivers publish best effort
    params:
      mode: points
```

[CONFIGURATION.md](https://github.com/justagist/ros_rerun_bridge/blob/main/docs/CONFIGURATION.md) describes every field, and covers frames, QoS and saving a viewer layout. The [examples](https://github.com/justagist/ros_rerun_bridge/blob/main/examples) are a good starting point: each has a config, an optional viewer layout, and a publisher of demo data that only stands in for a real robot.

## Modules

Built-in modules cover rviz's common displays: `tf`, `robot_description`, `joint_states`, `image`, `compressed_image`, `depth_image`, `compressed_depth_image`, `camera_info`, `pointcloud2`, `laserscan`, `range`, `marker_array`, `pose`, `pose_array`, `wrench`, `occupancy_grid` and `particle_cloud`. The `scalars` module plots numeric fields of any message as time series, `bar_chart` draws an array field as bars, and `states` shows a field as states over time. `rosout` shows ROS log entries, and `diagnostics` each component's diagnostic status over time. `segmentation_image` draws segmentation masks with their class names and colours, and `detections_2d` and `detections_3d` draw detection boxes labelled with their class, tracking id and score. See [MODULES.md](https://github.com/justagist/ros_rerun_bridge/blob/main/docs/MODULES.md) for what each shows and its parameters, and [EXTENDING.md](https://github.com/justagist/ros_rerun_bridge/blob/main/docs/EXTENDING.md) to add your own.

## Known limitations

The bridge shows one robot, and some message types have no module yet. Automatic discovery infers what it can from topic names and types, so a few topics need configuring by hand. [LIMITATIONS.md](https://github.com/justagist/ros_rerun_bridge/blob/main/docs/LIMITATIONS.md) lists them, with what to do instead.

## Development

```bash
source /opt/ros/jazzy/setup.bash  # or lyrical
uv run pytest            # tests (no running ROS nodes needed)
uv run ruff check        # lint
uv run ruff format       # format
```

Tests drive each module with real ROS messages and check what it logs to an in-memory Rerun recording. CI runs them in the `ros:jazzy-ros-base` and `ros:lyrical-ros-base` images.

## License

[MIT](https://github.com/justagist/ros_rerun_bridge/blob/main/LICENSE)
