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
Application ids starting with
TYPE:
|
recording_id |
Set the recording ID that this process is logging to, as a UUIDv4. The default recording_id is based on If you are not using
TYPE:
|
spawn |
Spawn a Rerun Viewer and stream logging data to it.
Short for calling
TYPE:
|
default_enabled |
Should Rerun logging be on by default?
Can be overridden with the RERUN env-var, e.g.
TYPE:
|
init_logging |
Should we initialize the logging for this application?
TYPE:
|
strict |
If
TYPE:
|
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
TYPE:
|
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:
|
flush_timeout_sec |
The minimum time the SDK will wait during a flush before potentially
dropping data if progress is not being made. Passing
TYPE:
|
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
TYPE:
|
recording |
Specifies the
TYPE:
|
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
TYPE:
|
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. |
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
TYPE:
|
recording |
Specifies the
TYPE:
|
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:
|
make_active |
Immediately make this the active blueprint for the associated
TYPE:
|
make_default |
Make this the default blueprint for the
TYPE:
|
recording |
Specifies the
TYPE:
|
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:
|
web_port |
The port to serve the web viewer on (defaults to 9090).
TYPE:
|
ws_port |
The port to serve the WebSocket server on (defaults to 9877)
TYPE:
|
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
TYPE:
|
recording |
Specifies the
TYPE:
|
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:
|
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:
|
connect |
also connect to the viewer and stream logging data to it.
TYPE:
|
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:
TYPE:
|
hide_welcome_screen |
Hide the normal Rerun welcome screen.
TYPE:
|
recording |
Specifies the
TYPE:
|
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
TYPE:
|
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
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
MemoryRecording
|
A memory recording object that can be used to read the data. |
def notebook_show(*, width=None, height=None, 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:
|
height |
The height of the viewer in pixels.
TYPE:
|
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
TYPE:
|
recording |
Specifies the
TYPE:
|
def legacy_notebook_show(*, width=DEFAULT_WIDTH, height=DEFAULT_HEIGHT, app_url=None, timeout_ms=DEFAULT_TIMEOUT, blueprint=None, recording=None)
Output the Rerun viewer in a notebook using IPython IPython.core.display.HTML.
This is a legacy function that uses a limited mechanism of inlining an RRD into a self-contained HTML template that loads the viewer in an iframe.
In general, rerun.notebook_show should be preferred. However, this function can be useful
in some systems with incomplete support for the anywidget
library.
PARAMETER | DESCRIPTION |
---|---|
width |
The width of the viewer in pixels.
TYPE:
|
height |
The height of the viewer in pixels.
TYPE:
|
app_url |
Alternative HTTP url to find the Rerun web viewer. This will default to using
TYPE:
|
timeout_ms |
The number of milliseconds to wait for the Rerun web viewer to load.
TYPE:
|
blueprint |
The blueprint to display in the viewer.
TYPE:
|
recording |
Specifies the
TYPE:
|