Skip to content

Initialization functions

rerun

def init(application_id, *, recording_id=None, spawn=False, init_logging=True, default_enabled=True, strict=None, default_blueprint=None)

Initialize the Rerun SDK with a user-chosen application id (name).

You must call this function first in order to initialize a global recording. Without an active recording, all methods of the SDK will turn into no-ops.

For more advanced use cases, e.g. multiple recordings setups, see rerun.new_recording.

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
rr.init("my_app", recording_id=uuid4())
rr.init("my_app", 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").

Application ids starting with rerun_example_ are reserved for Rerun examples, and will be treated specially by the Rerun Viewer. In particular, it will opt-in to more analytics, and will also seed the global random number generator deterministically.

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

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

init_logging

Should we initialize the logging for this application?

TYPE: bool DEFAULT: True

strict

If True, an exception is raised on use error (wrong parameter types, etc.). If False, errors are logged as warnings instead. If unset, this can alternatively be overridden using the RERUN_STRICT environment variable. If not otherwise specified, the default behavior will be equivalent to False.

TYPE: bool | None DEFAULT: None

default_blueprint

Optionally set a default blueprint to use for this application. If the application already has an active blueprint, the new blueprint won't become active until the user clicks the "reset blueprint" button. If you want to activate the new blueprint immediately, instead use the rerun.send_blueprint API.

TYPE: BlueprintLike | None DEFAULT: None

def connect(addr=None, *, flush_timeout_sec=2.0, default_blueprint=None, recording=None)

Connect to a remote Rerun Viewer on the given ip:port.

Requires that you first start a Rerun Viewer by typing 'rerun' in a terminal.

This function returns immediately.

PARAMETER DESCRIPTION
addr

The ip:port to connect to

TYPE: str | None DEFAULT: None

flush_timeout_sec

The minimum time the SDK will wait during a flush before potentially dropping data if progress is not being made. Passing None indicates no timeout, and can cause a call to flush to block indefinitely.

TYPE: float | None DEFAULT: 2.0

default_blueprint

Optionally set a default blueprint to use for this application. If the application already has an active blueprint, the new blueprint won't become active until the user clicks the "reset blueprint" button. If you want to activate the new blueprint immediately, instead use the rerun.send_blueprint API.

TYPE: BlueprintLike | None DEFAULT: None

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

def disconnect(recording=None)

Closes all TCP connections, servers, and files.

Closes all TCP connections, servers, and files that have been opened with [rerun.connect], [rerun.serve], [rerun.save] or [rerun.spawn].

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

def save(path, default_blueprint=None, recording=None)

Stream all log-data to a file.

Call this before you log any data!

PARAMETER DESCRIPTION
path

The path to save the data to.

TYPE: str | Path

default_blueprint

Optionally set a default blueprint to use for this application. If the application already has an active blueprint, the new blueprint won't become active until the user clicks the "reset blueprint" button. If you want to activate the new blueprint immediately, instead use the rerun.send_blueprint API.

TYPE: BlueprintLike | None DEFAULT: None

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

def send_blueprint(blueprint, *, make_active=True, make_default=True, recording=None)

Create a blueprint from a BlueprintLike and send it to the RecordingStream.

PARAMETER DESCRIPTION
blueprint

A blueprint object to send to the viewer.

TYPE: BlueprintLike

make_active

Immediately make this the active blueprint for the associated app_id. Note that setting this to false does not mean the blueprint may not still end up becoming active. In particular, if make_default is true and there is no other currently active blueprint.

TYPE: bool DEFAULT: True

make_default

Make this the default blueprint for the app_id. The default blueprint will be used as the template when the user resets the blueprint for the app. It will also become the active blueprint if no other blueprint is currently active.

TYPE: bool DEFAULT: True

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

def serve(*, open_browser=True, web_port=None, ws_port=None, default_blueprint=None, recording=None, server_memory_limit='25%')

Serve log-data over WebSockets and serve a Rerun web viewer over HTTP.

You can also connect to this server with the native viewer using rerun localhost:9090.

The WebSocket server will buffer all log data in memory so that late connecting viewers will get all the data. You can limit the amount of data buffered by the WebSocket server with the server_memory_limit argument. Once reached, the earliest logged data will be dropped. Note that this means that static data may be dropped if logged early (see https://github.com/rerun-io/rerun/issues/5531).

This function returns immediately.

PARAMETER DESCRIPTION
open_browser

Open the default browser to the viewer.

TYPE: bool DEFAULT: True

web_port

The port to serve the web viewer on (defaults to 9090).

TYPE: int | None DEFAULT: None

ws_port

The port to serve the WebSocket server on (defaults to 9877)

TYPE: int | None DEFAULT: None

default_blueprint

Optionally set a default blueprint to use for this application. If the application already has an active blueprint, the new blueprint won't become active until the user clicks the "reset blueprint" button. If you want to activate the new blueprint immediately, instead use the rerun.send_blueprint API.

TYPE: BlueprintLike | None DEFAULT: None

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

server_memory_limit

Maximum amount of memory to use for buffering log data for clients that connect late. This can be a percentage of the total ram (e.g. "50%") or an absolute value (e.g. "4GB").

TYPE: str DEFAULT: '25%'

def spawn(*, port=9876, connect=True, memory_limit='75%', hide_welcome_screen=False, default_blueprint=None, recording=None)

Spawn a Rerun Viewer, listening on the given port.

This is often the easiest and best way to use Rerun. Just call this once at the start of your program.

You can also call rerun.init with a spawn=True argument.

PARAMETER DESCRIPTION
port

The port to listen on.

TYPE: int DEFAULT: 9876

connect

also connect to the viewer and stream logging data to it.

TYPE: bool DEFAULT: True

memory_limit

An upper limit on how much memory the Rerun Viewer should use. When this limit is reached, Rerun will drop the oldest data. Example: 16GB or 50% (of system total).

TYPE: str DEFAULT: '75%'

hide_welcome_screen

Hide the normal Rerun welcome screen.

TYPE: bool DEFAULT: False

recording

Specifies the rerun.RecordingStream to use if connect = True. 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

default_blueprint

Optionally set a default blueprint to use for this application. If the application already has an active blueprint, the new blueprint won't become active until the user clicks the "reset blueprint" button. If you want to activate the new blueprint immediately, instead use the rerun.send_blueprint API.

TYPE: BlueprintLike | None DEFAULT: None

def memory_recording(recording=None)

Streams all log-data to a memory buffer.

This can be used to display the RRD to alternative formats such as html. See: rerun.notebook_show.

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
MemoryRecording

A memory recording object that can be used to read the data.

def notebook_show(*, width=DEFAULT_WIDTH, height=DEFAULT_HEIGHT, blueprint=None, recording=None)

Output the Rerun viewer in a notebook using IPython IPython.core.display.HTML.

Any data logged to the recording after initialization will be sent directly to the viewer.

Note that this can be called at any point during cell execution. The call will block until the embedded viewer is initialized and ready to receive data. Thereafter any log calls will immediately send data to the viewer.

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

blueprint

A blueprint object to send to the viewer. It will be made active and set as the default blueprint in the recording.

Setting this is equivalent to calling rerun.send_blueprint before initializing the viewer.

TYPE: BlueprintLike DEFAULT: None

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