Rerun

Rerun is visualization infrastructure for computer vision.

This repository contains the Rerun SDK and Rerun Viewer. Use the SDK (currently Python only) to log rich data that is streamed to the viewer, where it is visualized live or after the fact.

Documentation (Coming soon!)

WARNING: The following links don't all work yet

TODO(jleibs): Clean up this section and remove warnign when all links are live

High-level documentation for rerun can be found at http://rerun.io/docs.

The documentation is built from a separate Rerun-Docs Repository

Rust and Python APIs are documented in the code via docstrings.

• The Rust API docs are built via cargo and hosted on docs.rs
• The Python API docs are built via mkdocs and hosted on github:
  • For more information on the python doc-system see: Writing Docs

For our users

We don't have any pre-built binaries yet, so you need to build Rerun from source. There is some setup involved, but most of it should be pretty painless.

Setup

• Install the Rust toolchain: https://rustup.rs/
• git clone [email protected]:rerun-io/rerun.git && cd rerun
• Run ./scripts/setup.sh.
• Make sure cargo --version prints 1.67.0 once you are done

Apple-silicon Macs

If you are using an Apple-silicon Mac, make sure rustc -vV outputs host: aarch64-apple-darwin. If not, this should fix it:

rustup set default-host aarch64-apple-darwin && rustup install 1.67

Build and install the Rerun Python SDK

Set up virtualenv

Mac/Linux:

python3 -m venv venv  # Rerun supports Python version >= 3.7
source venv/bin/activate
python -m pip install --upgrade pip  # We need pip version >=21.3

Windows (powershell):

python -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

From here on out, we assume you have this virtualenv activated.

Build and install

./scripts/setup.sh
pip install ./rerun_py

Note: If you are unable to upgrade pip to version >=21.3, you need to pass --use-feature=in-tree-build to the pip install command.

Getting started with examples

The easiest way to get started is to run and look at examples.

Buffered or live visualization

By default, the examples run in buffered mode. This means they run through the whole example, and then show the viewer (UI) at the end in the same process by calling blocking function rerun.show().

If you'd rather see the visualizations live, as data is being logged. Run the examples with the --connect flag. The Rerun SDK will then try to connect to a Rerun Viewer running in another process and send the data as it is produced.

To visualize an example live, first in one terminal (with the activated virtualenv) run:

python -m rerun  # Opens a Rerun Viewer that will wait for data from the Rerun SDK

Then run the example in a second terminal like:

python examples/car/main.py --connect  # The Rerun SDK will connect and send data to the separate viewer.

Using the Rerun Python SDK

Most documentation is found in the docstrings of the functions in the Rerun. Either check out the docstrings directly in code or use the built in help() function. For example, to see the docstring of the log_image function, open a python terminal and run:

import rerun as rr
help(rr.log_image)

For a description of how to use the SDK, including some of the key concepts, see rerun_py/USAGE.md.

Rerun Viewer without Python

You can also build and install the Rerun Viewer to be used from the terminal without going through Python.

To build and install run:

cargo install --path ./crates/rerun/

You should now be able to run rerun --help in any terminal.

Bounded memory use

You can set --memory-limit=16GB to tell the Rerun Viewer to purge older log data when memory use goes above that limit. This is useful for using Rerun in continuous mode, i.e. where you keep logging new data to Rerun forever.

It is still possible to log data faster than the Rerun Viewer can process it, and in those cases you may still run out of memory unless you also set --drop-at-latency=200ms or similar.

Development

Take a look at CONTRIBUTING.md.