Skip to content

Other classes and functions

rerun

class RecordingStream

A RecordingStream is used to send data to Rerun.

You can instantiate a RecordingStream by calling either rerun.init (to create a global recording) or rerun.new_recording (for more advanced use cases).

Multithreading

A RecordingStream can safely be copied and sent to other threads. You can also set a recording as the global active one for all threads (rerun.set_global_data_recording) or just for the current thread (rerun.set_thread_local_data_recording).

Similarly, the with keyword can be used to temporarily set the active recording for the current thread, e.g.: 

with rec:
    rr.log(...)

See also: rerun.get_data_recording, rerun.get_global_data_recording, rerun.get_thread_local_data_recording.

Available methods

Every function in the Rerun SDK that takes an optional RecordingStream as a parameter can also be called as a method on RecordingStream itself.

This includes, but isn't limited to:

For an exhaustive list, see help(rerun.RecordingStream).

Micro-batching

Micro-batching using both space and time triggers (whichever comes first) is done automatically in a dedicated background thread.

You can configure the frequency of the batches using the following environment variables:

  • RERUN_FLUSH_TICK_SECS: Flush frequency in seconds (default: 0.05 (50ms)).
  • RERUN_FLUSH_NUM_BYTES: Flush threshold in bytes (default: 1048576 (1MiB)).
  • RERUN_FLUSH_NUM_ROWS: Flush threshold in number of rows (default: 18446744073709551615 (u64::MAX)).

class LoggingHandler

Bases: Handler

Provides a logging handler that forwards all events to the Rerun SDK.

Read more about logging handlers.

def __init__ (path_prefix=None)

Initializes the logging handler with an optional path prefix.

PARAMETER DESCRIPTION
path_prefix

A common prefix for all logged entity paths. Defaults to no prefix.

TYPE: str | None DEFAULT: None

def emit (record)

Emits a record to the Rerun SDK.

class MemoryRecording

A recording that stores data in memory.

def as_html (*, width=DEFAULT_WIDTH, height=DEFAULT_HEIGHT, app_url=None, timeout_ms=DEFAULT_TIMEOUT, other=None)

Generate an HTML snippet that displays the recording in an IFrame.

For use in contexts such as Jupyter notebooks.

⚠️ This will do a blocking flush of the current sink before returning!

PARAMETER DESCRIPTION
width

The width of the viewer in pixels.

TYPE: int DEFAULT: DEFAULT_WIDTH

height

The height of the viewer in pixels.

TYPE: int DEFAULT: DEFAULT_HEIGHT

app_url

Alternative HTTP url to find the Rerun web viewer. This will default to using https://app.rerun.io or localhost if rerun.start_web_viewer_server has been called.

TYPE: str DEFAULT: None

timeout_ms

The number of milliseconds to wait for the Rerun web viewer to load.

TYPE: int DEFAULT: DEFAULT_TIMEOUT

other

An optional MemoryRecording to merge with this one.

TYPE: MemoryRecording | None DEFAULT: None

def num_msgs ()

The number of pending messages in the MemoryRecording.

Note: counting the messages will flush the batcher in order to get a deterministic count.

def reset_blueprint (*, add_to_app_default_blueprint=False)

Reset the blueprint in the MemoryRecording.

def reset_data ()

Reset the data in the MemoryRecording.

def show (*, other=None, width=DEFAULT_WIDTH, height=DEFAULT_HEIGHT, app_url=None, timeout_ms=DEFAULT_TIMEOUT)

Output the Rerun viewer using IPython IPython.core.display.HTML.

PARAMETER DESCRIPTION
width

The width of the viewer in pixels.

TYPE: int DEFAULT: DEFAULT_WIDTH

height

The height of the viewer in pixels.

TYPE: int DEFAULT: DEFAULT_HEIGHT

app_url

Alternative HTTP url to find the Rerun web viewer. This will default to using https://app.rerun.io or localhost if rerun.start_web_viewer_server has been called.

TYPE: str DEFAULT: None

timeout_ms

The number of milliseconds to wait for the Rerun web viewer to load.

TYPE: int DEFAULT: DEFAULT_TIMEOUT

other

An optional MemoryRecording to merge with this one.

TYPE: MemoryRecording | None DEFAULT: None

def get_data_recording (recording=None)

Returns the most appropriate recording to log data to, in the current context, if any.

PARAMETER DESCRIPTION
recording

Specifies the rerun.RecordingStream to use. If left unspecified, defaults to the current active data recording, if there is one. See also: rerun.init, rerun.set_global_data_recording.

TYPE: RecordingStream | None DEFAULT: None

RETURNS DESCRIPTION
Optional[RecordingStream]

The most appropriate recording to log data to, in the current context, if any.

def get_global_data_recording ()

Returns the currently active global recording, if any.

RETURNS DESCRIPTION
Optional[RecordingStream]

The currently active global recording, if any.

def get_recording_id (recording=None)

Get the recording ID that this recording is logging to, as a UUIDv4, if any.

The default recording_id is based on multiprocessing.current_process().authkey which means that all processes spawned with multiprocessing will have the same default recording_id.

If you are not using multiprocessing and still want several different Python processes to log to the same Rerun instance (and be part of the same recording), you will need to manually assign them all the same recording_id. Any random UUIDv4 will work, or copy the recording id for the parent process.

PARAMETER DESCRIPTION
recording

Specifies the rerun.RecordingStream to use. If left unspecified, defaults to the current active data recording, if there is one. See also: rerun.init, rerun.set_global_data_recording.

TYPE: RecordingStream | None DEFAULT: None

RETURNS DESCRIPTION
str

The recording ID that this recording is logging to.

def get_thread_local_data_recording ()

Returns the currently active thread-local recording, if any.

RETURNS DESCRIPTION
Optional[RecordingStream]

The currently active thread-local recording, if any.

def is_enabled (recording=None)

Is this Rerun recording enabled.

If false, all calls to the recording are ignored.

The default can be set in rerun.init, but is otherwise True.

This can be controlled with the environment variable RERUN (e.g. RERUN=on or RERUN=off).

def log_components (entity_path, components, *, num_instances=None, timeless=False, recording=None, strict=None)

Log an entity from a collection of ComponentBatchLike objects.

All of the batches should have the same length as the value of num_instances, or length 1 if the component is a splat., or 0 if the component is being cleared.

PARAMETER DESCRIPTION
entity_path

Path to the entity in the space hierarchy.

TYPE: str

components

A collection of ComponentBatchLike objects that

TYPE: Iterable[ComponentBatchLike]

num_instances

Optional. The number of instances in each batch. If not provided, the max of all components will be used instead.

TYPE: int | None DEFAULT: None

timeless

If true, the entity will be timeless (default: False).

TYPE: bool DEFAULT: False

recording

Specifies the rerun.RecordingStream to use. If left unspecified, defaults to the current active data recording, if there is one. See also: rerun.init, rerun.set_global_data_recording.

TYPE: RecordingStream | None DEFAULT: None

strict

If True, raise exceptions on non-loggable data. If False, warn on non-loggable data. if None, use the global default from rerun.strict_mode()

TYPE: bool | None DEFAULT: None

See also: rerun.log.

def new_recording (*, application_id, recording_id=None, make_default=False, make_thread_default=False, spawn=False, default_enabled=True)

Creates a new recording with a user-chosen application id (name) that can be used to log data.

If you only need a single global recording, rerun.init might be simpler.

Warning

If you don't specify a recording_id, it will default to a random value that is generated once at the start of the process. That value will be kept around for the whole lifetime of the process, and even inherited by all its subprocesses, if any.

This makes it trivial to log data to the same recording in a multiprocess setup, but it also means that the following code will not create two distinct recordings: 

rr.init("my_app")
rr.init("my_app")

To create distinct recordings from the same process, specify distinct recording IDs: 

from uuid import uuid4
rec = rr.new_recording(application_id="test", recording_id=uuid4())
rec = rr.new_recording(application_id="test", recording_id=uuid4())

PARAMETER DESCRIPTION
application_id

Your Rerun recordings will be categorized by this application id, so try to pick a unique one for each application that uses the Rerun SDK.

For example, if you have one application doing object detection and another doing camera calibration, you could have rerun.init("object_detector") and rerun.init("calibrator").

TYPE: str

recording_id

Set the recording ID that this process is logging to, as a UUIDv4.

The default recording_id is based on multiprocessing.current_process().authkey which means that all processes spawned with multiprocessing will have the same default recording_id.

If you are not using multiprocessing and still want several different Python processes to log to the same Rerun instance (and be part of the same recording), you will need to manually assign them all the same recording_id. Any random UUIDv4 will work, or copy the recording id for the parent process.

TYPE: Optional[str] DEFAULT: None

make_default

If true (not the default), the newly initialized recording will replace the current active one (if any) in the global scope.

TYPE: bool DEFAULT: False

make_thread_default

If true (not the default), the newly initialized recording will replace the current active one (if any) in the thread-local scope.

TYPE: bool DEFAULT: False

spawn

Spawn a Rerun Viewer and stream logging data to it. Short for calling spawn separately. If you don't call this, log events will be buffered indefinitely until you call either connect, show, or save

TYPE: bool DEFAULT: False

default_enabled

Should Rerun logging be on by default? Can be overridden with the RERUN env-var, e.g. RERUN=on or RERUN=off.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
RecordingStream

A handle to the rerun.RecordingStream. Use it to log data to Rerun.

def set_global_data_recording (recording)

Replaces the currently active global recording with the specified one.

PARAMETER DESCRIPTION
recording

The newly active global recording.

TYPE: RecordingStream

def set_thread_local_data_recording (recording)

Replaces the currently active thread-local recording with the specified one.

PARAMETER DESCRIPTION
recording

The newly active thread-local recording.

TYPE: RecordingStream

def start_web_viewer_server (port=0)

Start an HTTP server that hosts the rerun web viewer.

This only provides the web-server that makes the viewer available and does not otherwise provide a rerun websocket server or facilitate any routing of data.

This is generally only necessary for application such as running a jupyter notebook in a context where app.rerun.io is unavailable, or does not have the matching resources for your build (such as when running from source.)

PARAMETER DESCRIPTION
port

Port to serve assets on. Defaults to 0 (random port).

TYPE: int DEFAULT: 0