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(...)

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:

Metadata-related functions: rerun.is_enabled, rerun.get_recording_id, …
Sink-related functions: rerun.connect, rerun.spawn, …
Time-related functions: rerun.set_time_seconds, rerun.set_time_sequence, …
Log-related functions: rerun.log, rerun.log_components, …

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.

`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.

If recording is specified, returns that one;
Otherwise, falls back to the currently active thread-local recording, if there is one;
Otherwise, falls back to the currently active global recording, if there is one;
Otherwise, returns None.

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.

`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`

`def escape_entity_path_part(part)`

Escape an individual part of an entity path.

For instance, escape_entity_path_path("my image!") will return "my\ image\!".

See https://www.rerun.io/docs/concepts/entity-path for more on entity paths.

PARAMETER	DESCRIPTION
`part`	An unescaped string TYPE: `str`

RETURNS	DESCRIPTION
`str`	The escaped entity path. TYPE: `str`

`def new_entity_path(entity_path)`

Construct an entity path, defined by a list of (unescaped) parts.

If any part if not a string, it will be converted to a string using str().

For instance, new_entity_path(["world", 42, "my image!"]) will return "world/42/my\ image\!".

See https://www.rerun.io/docs/concepts/entity-path for more on entity paths.

PARAMETER	DESCRIPTION
`entity_path`	A list of strings to escape and join with slash. TYPE: `list[Any]`

RETURNS	DESCRIPTION
`str`	The escaped entity path. TYPE: `str`

PARAMETER	DESCRIPTION
`entity_path`	Path to the entity in the space hierarchy. The entity path can either be a string (with special characters escaped, split on unescaped slashes) or a list of unescaped strings. This means that logging to `"world/my\ image\!"` is the same as logging to ["world", "my image!"]. See https://www.rerun.io/docs/concepts/entity-path for more on entity paths. TYPE: `str \| list[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`

Other classes and functions

rerun

class RecordingStream

class LoggingHandler

def __init__(path_prefix=None)

def emit(record)

class MemoryRecording

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

def num_msgs()

def reset_blueprint(*, add_to_app_default_blueprint=False)

def reset_data()

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

def get_data_recording(recording=None)

def get_global_data_recording()

def get_recording_id(recording=None)

def get_thread_local_data_recording()

def is_enabled(recording=None)

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

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

def set_global_data_recording(recording)

def set_thread_local_data_recording(recording)

def start_web_viewer_server(port=0)

def escape_entity_path_part(part)

def new_entity_path(entity_path)