Skip to content

Notebook

rerun.notebook

Helper functions for converting streams to inline html.

SelectionItem module-attribute 

SelectionItem = (
    EntitySelectionItem
    | ViewSelectionItem
    | ContainerSelectionItem
)

Union type for all possible selection item types.

ViewerEvent module-attribute 

ViewerEvent = (
    PlayEvent
    | PauseEvent
    | TimeUpdateEvent
    | TimelineChangeEvent
    | SelectionChangeEvent
    | RecordingOpenEvent
)

Union type for all possible viewer event types.

ContainerSelectionItem dataclass

A container selection item, representing a selected container in the viewer.

container_id instance-attribute 
container_id: str

The ID of the selected container.

container_name instance-attribute 
container_name: str

The name of the selected container.

EntitySelectionItem dataclass

An entity selection item, representing a selected entity in the viewer.

entity_path instance-attribute 
entity_path: str

The entity path of the selected entity.

instance_id class-attribute instance-attribute 
instance_id: int | None = None

The instance ID of the selected entity, if any.

position class-attribute instance-attribute 
position: list[float] | None = None

The 3D position of the selection, if any.

view_name class-attribute instance-attribute 
view_name: str | None = None

The name of the view containing the selected entity, if any.

PauseEvent dataclass

Bases: ViewerEventBase

Event triggered when the viewer pauses playback.

application_id instance-attribute 
application_id: str

The application ID of the recording that triggered the event.

recording_id instance-attribute 
recording_id: str

The recording ID of the recording that triggered the event.

segment_id instance-attribute 
segment_id: str | None

The segment ID of the recording that triggered the event, if any.

PlayEvent dataclass

Bases: ViewerEventBase

Event triggered when the viewer starts playing.

application_id instance-attribute 
application_id: str

The application ID of the recording that triggered the event.

recording_id instance-attribute 
recording_id: str

The recording ID of the recording that triggered the event.

segment_id instance-attribute 
segment_id: str | None

The segment ID of the recording that triggered the event, if any.

RecordingOpenEvent dataclass

Bases: ViewerEventBase

Event triggered when a recording is opened in the viewer.

application_id instance-attribute 
application_id: str

The application ID of the recording that triggered the event.

recording_id instance-attribute 
recording_id: str

The recording ID of the recording that triggered the event.

segment_id instance-attribute 
segment_id: str | None

The segment ID of the recording that triggered the event, if any.

source instance-attribute 
source: str

The source of the recording (e.g. a URL or file path).

version instance-attribute 
version: str | None

The version of the recording, if available.

SelectionChangeEvent dataclass

Bases: ViewerEventBase

Event triggered when the selection changes in the viewer.

application_id instance-attribute 
application_id: str

The application ID of the recording that triggered the event.

items instance-attribute 
items: list[SelectionItem]

The list of currently selected items.

recording_id instance-attribute 
recording_id: str

The recording ID of the recording that triggered the event.

segment_id instance-attribute 
segment_id: str | None

The segment ID of the recording that triggered the event, if any.

TimeUpdateEvent dataclass

Bases: ViewerEventBase

Event triggered when the current time changes in the viewer.

application_id instance-attribute 
application_id: str

The application ID of the recording that triggered the event.

recording_id instance-attribute 
recording_id: str

The recording ID of the recording that triggered the event.

segment_id instance-attribute 
segment_id: str | None

The segment ID of the recording that triggered the event, if any.

time instance-attribute 
time: float

The new time value.

TimelineChangeEvent dataclass

Bases: ViewerEventBase

Event triggered when the active timeline changes in the viewer.

application_id instance-attribute 
application_id: str

The application ID of the recording that triggered the event.

recording_id instance-attribute 
recording_id: str

The recording ID of the recording that triggered the event.

segment_id instance-attribute 
segment_id: str | None

The segment ID of the recording that triggered the event, if any.

time instance-attribute 
time: float

The current time value on the new timeline.

timeline instance-attribute 
timeline: str

The name of the new active timeline.

ViewSelectionItem dataclass

A view selection item, representing a selected view in the viewer.

view_id instance-attribute 
view_id: str

The ID of the selected view.

view_name instance-attribute 
view_name: str

The name of the selected view.

Viewer

A viewer embeddable in a notebook.

This viewer is a wrapper around the rerun_notebook.Viewer widget.

__init__ 
def __init__(
    *,
    width: int | Literal["auto"] | None = None,
    height: int | Literal["auto"] | None = None,
    url: str | None = None,
    blueprint: BlueprintLike | None = None,
    recording: RecordingStream | None = None,
    use_global_recording: bool | None = None,
    theme: Literal["dark", "light", "system"] | None = None,
) -> None

Create a new Rerun viewer widget for use in a notebook.

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

This widget can be displayed by returning it at the end of your cells execution, or immediately by calling rerun.notebook.Viewer.display.

PARAMETER DESCRIPTION
width

The width of the viewer in pixels, or "auto".

When set to "auto", scales to 100% of the notebook cell's width.

TYPE: int | Literal['auto'] | None DEFAULT: None

height

The height of the viewer in pixels, or "auto".

When set to "auto", scales using a 16:9 aspect ratio with width.

TYPE: int | Literal['auto'] | None DEFAULT: None

url

Optional URL passed to the viewer for displaying its contents.

TYPE: str | 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

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 | None DEFAULT: None

use_global_recording

If no explicit recording is provided, the Viewer uses the thread-local/global recording created by rr.init or set explicitly via rr.set_thread_local_data_recording/rr.set_global_data_recording.

Settings this to False causes the Viewer to not pick up the global recording.

Defaults to False if url is provided, and True otherwise.

TYPE: bool | None DEFAULT: None

theme

The color theme to use. Either "dark", "light", or "system".

If not set, the viewer uses the previously persisted theme preference or defaults to "system".

TYPE: Literal['dark', 'light', 'system'] | None DEFAULT: None

add_recording 
def add_recording(
    recording: RecordingStream | None = None,
    blueprint: BlueprintLike | None = None,
) -> None

Adds a recording to the viewer.

If no recording is specified, the current active recording will be used.

NOTE: By default all calls to rr.init() will re-use the same recording_id, meaning that your recordings will be merged together. If you want to keep them separate, you should call rr.init("my_app_id", recording_id=uuid.uuid4()).

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

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 | None DEFAULT: None

close_url 
def close_url(url: str) -> None

Close an open URL in the viewer.

Does nothing if the URL is not open.

PARAMETER DESCRIPTION
url

The URL to close.

TYPE: str

display 
def display(block_until_ready: bool = False) -> None

Display the viewer in the notebook cell immediately.

PARAMETER DESCRIPTION
block_until_ready

Whether to block until the viewer is ready to receive data. If this is False, the viewer will still be displayed, but logged data will likely be queued until the viewer becomes ready at the end of cell execution.

TYPE: bool DEFAULT: False

on_event 
def on_event(callback: Callable[[ViewerEvent], None]) -> None

Register a callback to be called when a viewer event occurs.

The callback will receive a ViewerEvent, which is one of: PlayEvent, PauseEvent, TimeUpdateEvent, TimelineChangeEvent, SelectionChangeEvent, or RecordingOpenEvent.

PARAMETER DESCRIPTION
callback

A function that takes a ViewerEvent as its only argument.

TYPE: Callable[[ViewerEvent], None]

open_url 
def open_url(url: str) -> None

Open a URL in the viewer.

PARAMETER DESCRIPTION
url

The URL to open.

Must point to a valid data source.

TYPE: str

send_table 
def send_table(
    id: str,
    table: RecordBatch | list[RecordBatch] | DataFrame,
) -> None

Sends a table in the form of a dataframe to the viewer.

PARAMETER DESCRIPTION
id

The name that uniquely identifies the table in the viewer. This name will also be shown in the recording panel.

TYPE: str

table

The table data as an Arrow RecordBatch, list of RecordBatches, or a datafusion DataFrame.

TYPE: RecordBatch | list[RecordBatch] | DataFrame

set_active_recording 
def set_active_recording(*, recording_id: str) -> None

Set the active recording for the viewer.

This is equivalent to clicking on the given recording in the blueprint panel.

PARAMETER DESCRIPTION
recording_id

The ID of the recording to set the viewer to.

Using this requires setting an explicit recording ID when creating the recording.

TYPE: str

set_application_blueprint 
def set_application_blueprint(
    application_id: str,
    blueprint: BlueprintLike,
    *,
    make_active: bool = True,
    make_default: bool = True,
) -> None

Set the blueprint for the given application.

PARAMETER DESCRIPTION
application_id

The ID of the application to set the blueprint for.

TYPE: str

blueprint

The blueprint to set for the application.

TYPE: BlueprintLike

make_active

Whether to make the blueprint active. If True, the blueprint will be set as the active blueprint for the application.

TYPE: bool DEFAULT: True

make_default

Whether to make the blueprint the default blueprint for the application. If True, the blueprint will be set as the default blueprint for the application.

TYPE: bool DEFAULT: True

set_time_ctrl 
def set_time_ctrl(
    *,
    sequence: int | None = None,
    duration: int
    | float
    | timedelta
    | timedelta64
    | None = None,
    timestamp: int
    | float
    | datetime
    | datetime64
    | None = None,
    timeline: str | None = None,
    play: bool = False,
) -> None

Set the time control for the viewer.

You are expected to set at most ONE of the arguments sequence, duration, or timestamp.

PARAMETER DESCRIPTION
sequence

Used for sequential indices, like frame_nr. Must be an integer.

TYPE: int | None DEFAULT: None

duration

Used for relative times, like time_since_start. Must either be in seconds, a datetime.timedelta, or numpy.timedelta64. For nanosecond precision, use numpy.timedelta64(nanoseconds, 'ns').

TYPE: int | float | timedelta | timedelta64 | None DEFAULT: None

timestamp

Used for absolute time indices, like capture_time. Must either be in seconds since Unix epoch, a datetime.datetime, or numpy.datetime64. For nanosecond precision, use numpy.datetime64(nanoseconds, 'ns').

TYPE: int | float | datetime | datetime64 | None DEFAULT: None

play

Whether to start playing from the specified time point. Defaults to paused.

TYPE: bool DEFAULT: False

timeline

The name of the timeline to switch to. If not provided, time will remain on the current timeline.

TYPE: str | None DEFAULT: None

update_panels 
def update_panels(
    *,
    top: _PanelState | Literal["default"] | None = None,
    blueprint: _PanelState
    | Literal["default"]
    | None = None,
    selection: _PanelState
    | Literal["default"]
    | None = None,
    time: _PanelState | Literal["default"] | None = None,
) -> None

Partially update the state of panels in the viewer.

Valid states are the strings expanded, collapsed, hidden, default, and the value None.

Panels set to: - None will be unchanged. - expanded will be fully expanded, taking up the most space. - collapsed will be smaller and simpler, omitting some information. - hidden will be completely invisible, taking up no space. - default will be reset to the default state.

The collapsed state is the same as the hidden state for panels which do not support the collapsed state.

Setting the panel state using this function will also prevent the user from modifying that panel's state in the viewer.

PARAMETER DESCRIPTION
top

State of the top panel of the viewer.

TYPE: _PanelState | Literal['default'] | None DEFAULT: None

blueprint

State of the blueprint panel, positioned on the left side of the viewer.

TYPE: _PanelState | Literal['default'] | None DEFAULT: None

selection

State of the selection panel, positioned on the right side of the viewer.

TYPE: _PanelState | Literal['default'] | None DEFAULT: None

time

State of the time panel, positioned on the bottom side of the viewer.

TYPE: _PanelState | Literal['default'] | None DEFAULT: None

set_default_size 

def set_default_size(
    *, width: int | None, height: int | None
) -> None

Set the default size for the viewer.

This will be used for any viewers created after this call.

PARAMETER DESCRIPTION
width

The width of the viewer in pixels.

TYPE: int | None

height

The height of the viewer in pixels.

TYPE: int | None