Skip to content

__init__.py

rerun

The Rerun Python SDK, which is a wrapper around the re_sdk crate.

class RecordingStream(inner)

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

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 AnnotationInfo dataclass

Annotation info annotating a class id or key-point id.

Color and label will be used to annotate entities/keypoints which reference the id. The id refers either to a class or key-point id

id: int = 0 class-attribute

The id of the class or key-point to annotate

label: Optional[str] = None class-attribute

The label that will be shown in the UI

color: Optional[Color] = None class-attribute

The color that will be applied to the annotated entity

class LogLevel dataclass

Represents the standard log levels.

This is a collection of constants rather than an enum because we do support arbitrary strings as level (e.g. for user-defined levels).

CRITICAL: Final = 'CRITICAL' class-attribute

Designates catastrophic failures.

ERROR: Final = 'ERROR' class-attribute

Designates very serious errors.

WARN: Final = 'WARN' class-attribute

Designates hazardous situations.

INFO: Final = 'INFO' class-attribute

Designates useful information.

DEBUG: Final = 'DEBUG' class-attribute

Designates lower priority information.

TRACE: Final = 'TRACE' class-attribute

Designates very low priority, often extremely verbose, information.

class MeshFormat

Bases: Enum

Mesh file format.

GLB = 'GLB' class-attribute

glTF binary format.

OBJ = 'OBJ' class-attribute

Wavefront .obj format.

class RectFormat

Bases: Enum

How to specify rectangles (axis-aligned bounding boxes).

XYWH = 'XYWH' class-attribute

[x,y,w,h], with x,y = left,top.

YXHW = 'YXHW' class-attribute

[y,x,h,w], with x,y = left,top.

XYXY = 'XYXY' class-attribute

[x0, y0, x1, y1], with x0,y0 = left,top and x1,y1 = right,bottom.

YXYX = 'YXYX' class-attribute

[y0, x0, y1, x1], with x0,y0 = left,top and x1,y1 = right,bottom.

XCYCWH = 'XCYCWH' class-attribute

[x_center, y_center, width, height].

XCYCW2H2 = 'XCYCW2H2' class-attribute

[x_center, y_center, width/2, height/2].

class LoggingHandler(root_entity_path=None)

Bases: logging.Handler

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

Because Rerun's data model doesn't match 1-to-1 with the different concepts from python's logging ecosystem, we need a way to map the latter to the former:

Mapping
  • Root Entity: Optional root entity to gather all the logs under.

  • Entity path: the name of the logger responsible for the creation of the LogRecord is used as the final entity path, appended after the Root Entity path.

  • Level: the log level is mapped as-is.

  • Body: the body of the text entry corresponds to the formatted output of the LogRecord using the standard formatter of the logging package, unless it has been overridden by the user.

Read more about logging handlers

def emit(record)

Emits a record to the Rerun SDK.

class ImageFormat dataclass

Bases: Enum

Image file format.

JPEG = 'jpeg' class-attribute

JPEG format.

PNG = 'png' class-attribute

PNG format.

class ClassDescription dataclass

Metadata about a class type identified by an id.

Typically a class description contains only a annotation info. However, within a class there might be several keypoints, each with its own annotation info. Keypoints in turn may be connected to each other by connections (typically used for skeleton edges).

info: Optional[AnnotationInfoLike] = None class-attribute

The annotation info for the class

keypoint_annotations: Optional[Iterable[AnnotationInfoLike]] = None class-attribute

The annotation infos for the all key-points

keypoint_connections: Optional[Iterable[Union[int, Tuple[int, int]]]] = None class-attribute

The connections between key-points

def log_cleared(entity_path, *, recursive=False, recording=None)

Indicate that an entity at a given path should no longer be displayed.

If recursive is True this will also clear all sub-paths

Parameters:

Name Type Description Default
entity_path str

The path of the affected entity.

required

recursive: Should this apply to all entity paths below entity_path?

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.

def set_time_sequence(timeline, sequence, recording=None)

Set the current time for this thread as an integer sequence.

Used for all subsequent logging on the same thread, until the next call to set_time_sequence.

For example: set_time_sequence("frame_nr", frame_nr).

You can remove a timeline again using set_time_sequence("frame_nr", None).

There is no requirement of monotonicity. You can move the time backwards if you like.

Parameters:

Name Type Description Default
timeline str

The name of the timeline to set the time for.

required
sequence int

The current time on the timeline in integer units.

required
recording Optional[RecordingStream]

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.

None

def connect(addr=None, recording=None)

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

Requires that you first start a Rerun Viewer, e.g. with 'python -m rerun'

This function returns immediately.

Parameters:

Name Type Description Default
addr Optional[str]

The ip:port to connect to

None
recording Optional[RecordingStream]

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.

None

def log_pinhole(entity_path, *, child_from_parent, width, height, timeless=False, recording=None)

Log a perspective camera model.

This logs the pinhole model that projects points from the parent (camera) space to this space (image) such that:

point_image_hom = child_from_parent * point_cam
point_image = point_image_hom[:,1] / point_image_hom[2]

Where point_image_hom is the projected point in the image space expressed in homogeneous coordinates.

Example
width = 640
height = 480
u_cen = width / 2
v_cen = height / 2
f_len = (height * width) ** 0.5

rerun.log_pinhole("world/camera/image",
                  child_from_parent = [[f_len, 0,     u_cen],
                                       [0,     f_len, v_cen],
                                       [0,     0,     1  ]],
                  width = width,
                  height = height)

Parameters:

Name Type Description Default
entity_path str

Path to the child (image) space in the space hierarchy.

required
child_from_parent npt.ArrayLike

Row-major intrinsics matrix for projecting from camera space to image space.

required
width int

Width of the image in pixels.

required
height int

Height of the image in pixels.

required
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def log_image(entity_path, image, *, draw_order=None, ext=None, timeless=False, recording=None)

Log a gray or color image.

The image should either have 1, 3 or 4 channels (gray, RGB or RGBA).

Supported dtypes
  • uint8: color components should be in 0-255 sRGB gamma space, except for alpha which should be in 0-255 linear space.
  • uint16: color components should be in 0-65535 sRGB gamma space, except for alpha which should be in 0-65535 linear space.
  • float32, float64: all color components should be in 0-1 linear space.

Parameters:

Name Type Description Default
entity_path str

Path to the image in the space hierarchy.

required
image Tensor

A Tensor representing the image to log.

required
draw_order Optional[float]

An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. The default for images is -10.0.

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def log_mesh(entity_path, positions, *, indices=None, normals=None, albedo_factor=None, vertex_colors=None, timeless=False, recording=None)

Log a raw 3D mesh by specifying its vertex positions, and optionally indices, normals and albedo factor.

You can also use [rerun.log_mesh_file] to log .gltf, .glb, .obj, etc.

Example:
# A simple red triangle:
rerun.log_mesh(
    "world/mesh",
    positions = [
        [0.0, 0.0, 0.0],
        [1.0, 0.0, 0.0],
        [0.0, 1.0, 0.0]
    ],
    indices = [0, 1, 2],
    normals = [
        [0.0, 0.0, 1.0],
        [0.0, 0.0, 1.0],
        [0.0, 0.0, 1.0]
    ],
    albedo_factor = [1.0, 0.0, 0.0],
)

Parameters:

Name Type Description Default
entity_path str

Path to the mesh in the space hierarchy

required
positions Any

An array of 3D points. If no indices are specified, then each triplet of positions is interpreted as a triangle.

required
indices Optional[Any]

If specified, is a flattened array of indices that describe the mesh's triangles, i.e. its length must be divisible by 3.

None
normals Optional[Any]

If specified, is a (potentially flattened) array of 3D vectors that describe the normal for each vertex, i.e. the total number of elements must be divisible by 3 and more importantly, len(normals) should be equal to len(positions).

None
albedo_factor Optional[Any]

Optional color multiplier of the mesh using RGB or unmuliplied RGBA in linear 0-1 space.

None
vertex_colors Optional[Colors]

Optional array of RGB(A) vertex colors, in sRGB gamma space, either as 0-1 floats or 0-255 integers. If specified, the alpha is considered separate (unmultiplied).

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def log_scalar(entity_path, scalar, *, label=None, color=None, radius=None, scattered=None, ext=None, recording=None)

Log a double-precision scalar that will be visualized as a timeseries plot.

The current simulation time will be used for the time/X-axis, hence scalars cannot be timeless!

See here for a larger example.

Understanding the plot and attributes hierarchy

Timeseries come in three parts: points, lines and finally the plots themselves. As a user of the Rerun SDK, your one and only entrypoint into that hierarchy is through the lowest-level layer: the points.

When logging scalars and their attributes (label, color, radius, scattered) through this function, Rerun will turn them into points with similar attributes. From these points, lines with appropriate attributes can then be inferred; and from these inferred lines, plots with appropriate attributes will be inferred in turn!

In terms of actual hierarchy:

  • Each space represents a single plot.
  • Each entity path within a space that contains scalar data is a line within that plot.
  • Each logged scalar is a point.

E.g. the following:

t=1.0
rerun.log_scalar("trig/sin", math.sin(t), label="sin(t)", color=[255, 0, 0])
rerun.log_scalar("trig/cos", math.cos(t), label="cos(t)", color=[0, 0, 255])
will yield a single plot (space = trig), comprised of two lines (entity paths trig/sin and trig/cos).

Parameters:

Name Type Description Default
entity_path str

The path to the scalar in the space hierarchy.

required
scalar float

The scalar value to log.

required
label Optional[str]

An optional label for the point.

This won't show up on points at the moment, as our plots don't yet support displaying labels for individual points TODO(https://github.com/rerun-io/rerun/issues/1289). If all points within a single entity path (i.e. a line) share the same label, then this label will be used as the label for the line itself. Otherwise, the line will be named after the entity path. The plot itself is named after the space it's in.

None
color Optional[Color]

Optional RGB or RGBA in sRGB gamma-space as either 0-1 floats or 0-255 integers, with separate alpha.

If left unspecified, a pseudo-random color will be used instead. That same color will apply to all points residing in the same entity path that don't have a color specified.

Points within a single line do not have to share the same color, the line will have differently colored segments as appropriate. If all points within a single entity path (i.e. a line) share the same color, then this color will be used as the line color in the plot legend. Otherwise, the line will appear gray in the legend.

None
radius Optional[float]

An optional radius for the point.

Points within a single line do not have to share the same radius, the line will have differently sized segments as appropriate.

If all points within a single entity path (i.e. a line) share the same radius, then this radius will be used as the line width too. Otherwise, the line will use the default width of 1.0.

None
scattered Optional[bool]

Specifies whether the point should form a continuous line with its neighbors, or whether it should stand on its own, akin to a scatter plot. Points within a single line do not have to all share the same scatteredness: the line will switch between a scattered and a continuous representation as required.

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
recording Optional[RecordingStream]

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.

None

def log_arrow(entity_path, origin, vector=None, *, color=None, label=None, width_scale=None, ext=None, timeless=False, recording=None)

Log a 3D arrow.

An arrow is defined with an origin, and a vector. This can also be considered as start and end positions for the arrow.

The shaft is rendered as a cylinder with radius = 0.5 * width_scale. The tip is rendered as a cone with height = 2.0 * width_scale and radius = 1.0 * width_scale.

Parameters:

Name Type Description Default
entity_path str

The path to store the entity at.

required
origin Optional[npt.ArrayLike]

The base position of the arrow.

required
vector Optional[npt.ArrayLike]

The vector along which the arrow will be drawn.

None
color Optional[Color]

Optional RGB or RGBA in sRGB gamma-space as either 0-1 floats or 0-255 integers, with separate alpha.

None
label Optional[str]

An optional text to show beside the arrow.

None
width_scale Optional[float]

An optional scaling factor, default=1.0.

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

The entity is not time-dependent, and will be visible at any time point.

False
recording Optional[RecordingStream]

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.

None

def log_view_coordinates(entity_path, *, xyz='', up='', right_handed=None, timeless=False, recording=None)

Log the view coordinates for an entity.

Each entity defines its own coordinate system, called a space. By logging view coordinates you can give semantic meaning to the XYZ axes of the space. This is for example useful for camera entities ("what axis is forward?").

For full control, set the xyz parameter to a three-letter acronym (xyz="RDF"). Each letter represents:

  • R: Right
  • L: Left
  • U: Up
  • D: Down
  • F: Forward
  • B: Back

Some of the most common are:

  • "RDF": X=Right Y=Down Z=Forward (right-handed)
  • "RUB" X=Right Y=Up Z=Back (right-handed)
  • "RDB": X=Right Y=Down Z=Back (left-handed)
  • "RUF": X=Right Y=Up Z=Forward (left-handed)
Example
rerun.log_view_coordinates("world/camera", xyz="RUB")

For world-coordinates it's often convenient to just specify an up-axis. You can do so by using the up-parameter (where up is one of "+X", "-X", "+Y", "-Y", "+Z", "-Z"):

rerun.log_view_coordinates("world", up="+Z", right_handed=True, timeless=True)
rerun.log_view_coordinates("world", up="-Y", right_handed=False, timeless=True)

Parameters:

Name Type Description Default
entity_path str

Path in the space hierarchy where the view coordinate will be set.

required
xyz str

Three-letter acronym for the view coordinate axes.

''
up str

Which axis is up? One of "+X", "-X", "+Y", "-Y", "+Z", "-Z".

''
right_handed Optional[bool]

If True, the coordinate system is right-handed. If False, it is left-handed.

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def log_obb(entity_path, *, half_size, position=None, rotation_q=None, color=None, stroke_width=None, label=None, class_id=None, ext=None, timeless=False, recording=None)

Log a 3D Oriented Bounding Box, or OBB.

Example:
rr.log_obb("my_obb", half_size=[1.0, 2.0, 3.0], position=[0, 0, 0], rotation_q=[0, 0, 0, 1])

Parameters:

Name Type Description Default
entity_path str

The path to the oriented bounding box in the space hierarchy.

required
half_size Optional[npt.ArrayLike]

Array with [x, y, z] half dimensions of the OBB.

required
position Optional[npt.ArrayLike]

Optional array with [x, y, z] position of the OBB in world space.

None
rotation_q Optional[npt.ArrayLike]

Optional array with quaternion coordinates [x, y, z, w] for the rotation from model to world space.

None
color Optional[Color]

Optional RGB or RGBA in sRGB gamma-space as either 0-1 floats or 0-255 integers, with separate alpha.

None
stroke_width Optional[float]

Optional width of the line edges.

None
label Optional[str]

Optional text label placed at position.

None
class_id Optional[int]

Optional class id for the OBB. The class id provides colors and labels if not specified explicitly.

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def script_add_args(parser)

Add common Rerun script arguments to parser.

Parameters:

Name Type Description Default
parser ArgumentParser

The parser to add arguments to.

required

def log_rect(entity_path, rect, *, rect_format=RectFormat.XYWH, color=None, label=None, class_id=None, draw_order=None, ext=None, timeless=False, recording=None)

Log a 2D rectangle.

Parameters:

Name Type Description Default
entity_path str

Path to the rectangle in the space hierarchy.

required
rect Optional[npt.ArrayLike]

the rectangle in [x, y, w, h], or some format you pick with the rect_format argument.

required
rect_format RectFormat

how to interpret the rect argument

RectFormat.XYWH
color Optional[Color]

Optional RGB or RGBA in sRGB gamma-space as either 0-1 floats or 0-255 integers, with separate alpha.

None
label Optional[str]

Optional text to show inside the rectangle.

None
class_id Optional[int]

Optional class id for the rectangle. The class id provides color and label if not specified explicitly. See rerun.log_annotation_context

None
draw_order Optional[float]

An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. The default for rects is 10.0.

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def log_point(entity_path, position=None, *, radius=None, color=None, label=None, class_id=None, keypoint_id=None, draw_order=None, ext=None, timeless=False, recording=None)

Log a 2D or 3D point, with a position and optional color, radii, label, etc.

Logging again to the same entity_path will replace the previous point.

Colors should either be in 0-255 gamma space or in 0-1 linear space. Colors can be RGB or RGBA represented as a 2-element or 3-element sequence.

Supported dtypes for color:
  • uint8: color components should be in 0-255 sRGB gamma space, except for alpha which should be in 0-255 linear space.
  • float32/float64: all color components should be in 0-1 linear space.

Parameters:

Name Type Description Default
entity_path str

Path to the point in the space hierarchy.

required
position Optional[npt.ArrayLike]

Any 2-element or 3-element array-like.

None
radius Optional[float]

Optional radius (make it a sphere).

None
color Optional[Color]

Optional RGB or RGBA in sRGB gamma-space as either 0-1 floats or 0-255 integers, with separate alpha.

None
label Optional[str]

Optional text to show with the point.

None
class_id Optional[int]

Optional class id for the point. The class id provides color and label if not specified explicitly. See rerun.log_annotation_context

None
keypoint_id Optional[int]

Optional key point id for the point, identifying it within a class. If keypoint_id is passed but no class_id was specified, class_id will be set to 0. This is useful to identify points within a single classification (which is identified with class_id). E.g. the classification might be 'Person' and the keypoints refer to joints on a detected skeleton. See rerun.log_annotation_context

None
draw_order Optional[float]

An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. The default for 2D points is 30.0.

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def save(path, recording=None)

Stream all log-data to a file.

Parameters:

Name Type Description Default
path str

The path to save the data to.

required
recording Optional[RecordingStream]

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.

None

def set_time_seconds(timeline, seconds, recording=None)

Set the current time for this thread in seconds.

Used for all subsequent logging on the same thread, until the next call to rerun.set_time_seconds or rerun.set_time_nanos.

For example: set_time_seconds("capture_time", seconds_since_unix_epoch).

You can remove a timeline again using set_time_seconds("capture_time", None).

Very large values will automatically be interpreted as seconds since unix epoch (1970-01-01). Small values (less than a few years) will be interpreted as relative some unknown point in time, and will be shown as e.g. +3.132s.

The bindings has a built-in time which is log_time, and is logged as seconds since unix epoch.

There is no requirement of monotonicity. You can move the time backwards if you like.

Parameters:

Name Type Description Default
timeline str

The name of the timeline to set the time for.

required
seconds float

The current time on the timeline in seconds.

required
recording Optional[RecordingStream]

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.

None

def log_line_strip(entity_path, positions, *, stroke_width=None, color=None, draw_order=None, ext=None, timeless=False, recording=None)

Log a line strip through 2D or 3D space.

A line strip is a list of points connected by line segments. It can be used to draw approximations of smooth curves.

The points will be connected in order, like so:

       2------3     5
      /        \   /
0----1          \ /
                 4

Parameters:

Name Type Description Default
entity_path str

Path to the path in the space hierarchy

required
positions Optional[npt.ArrayLike]

An Nx2 or Nx3 array of points along the path.

required
stroke_width Optional[float]

Optional width of the line.

None
color Optional[Color]

Optional RGB or RGBA in sRGB gamma-space as either 0-1 floats or 0-255 integers, with separate alpha.

None
draw_order Optional[float]

An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. The default for lines is 20.0.

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def log_tensor(entity_path, tensor, *, names=None, meter=None, ext=None, timeless=False, recording=None)

Log an n-dimensional tensor.

Parameters:

Name Type Description Default
entity_path str

Path to the tensor in the space hierarchy.

required
tensor npt.ArrayLike

A Tensor object.

required
names Optional[Iterable[Optional[str]]]

Optional names for each dimension of the tensor.

None
meter Optional[float]

Optional scale of the tensor (e.g. meters per cell).

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def log_mesh_file(entity_path, mesh_format, *, mesh_bytes=None, mesh_path=None, transform=None, timeless=False, recording=None)

Log the contents of a mesh file (.gltf, .glb, .obj, …).

You must pass either mesh_bytes or mesh_path.

You can also use [rerun.log_mesh] to log raw mesh data.

Example:
# Move mesh 10 units along the X axis.
transform=np.array([
    [1, 0, 0, 10],
    [0, 1, 0, 0],
    [0, 0, 1, 0]])

Parameters:

Name Type Description Default
entity_path str

Path to the mesh in the space hierarchy

required
mesh_format MeshFormat

Format of the mesh file

required
mesh_bytes Optional[bytes]

Content of an mesh file, e.g. a .glb.

None
mesh_path Optional[Path]

Path to an mesh file, e.g. a .glb.

None
transform Optional[npt.ArrayLike]

Optional 3x4 affine transform matrix applied to the mesh

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def script_setup(args, application_id)

Run common Rerun script setup actions. Connect to the viewer if necessary.

Parameters:

Name Type Description Default
args Namespace

The parsed arguments from parser.parse_args().

required
application_id str

The application ID to use for the viewer.

required

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

Parameters:

Name Type Description Default
recording Optional[RecordingStream]

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.

None

def log_extension_components(entity_path, ext, *, identifiers=None, timeless=False, recording=None)

Log an arbitrary collection of extension components.

Each item in ext will be logged as a separate component.

  • The key will be used as the name of the component
  • The value must be able to be converted to an array of arrow types. In general, if you can pass it to pyarrow.array, you can log it as a extension component.

All values must either have the same length, or be singular in which case they will be treated as a splat.

Extension components will be prefixed with "ext." to avoid collisions with rerun native components. You do not need to include this prefix; it will be added for you.

Note: rerun requires that a given component only take on a single type. The first type logged will be the type that is used for all future logs of that component. The API will make a best effort to do type conversion if supported by numpy and arrow. Any components that can't be converted will be dropped.

If you are want to inspect how your component will be converted to the underlying arrow code, the following snippet is what is happening internally:

np_value = np.atleast_1d(np.array(value, copy=False))
pa_value = pa.array(value)

Parameters:

Name Type Description Default
entity_path str

Path to the extension components in the space hierarchy.

required
ext Dict[str, Any]

A dictionary of extension components.

required
identifiers Optional[Sequence[int]]

Optional identifiers for each component. If provided, must be the same length as the components.

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def log_text_entry(entity_path, text, *, level=LogLevel.INFO, color=None, ext=None, timeless=False, recording=None)

Log a text entry, with optional level.

Parameters:

Name Type Description Default
entity_path str

The object path to log the text entry under.

required
text str

The text to log.

required
level Optional[str]

The level of the text entry (default: LogLevel.INFO). Note this can technically be an arbitrary string, but it's recommended to use one of the constants from LogLevel

LogLevel.INFO
color Optional[Color]

Optional RGB or RGBA in sRGB gamma-space as either 0-1 floats or 0-255 integers, with separate alpha.

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

Whether the text entry should be timeless.

False
recording Optional[RecordingStream]

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.

None

def set_time_nanos(timeline, nanos, recording=None)

Set the current time for this thread.

Used for all subsequent logging on the same thread, until the next call to rerun.set_time_nanos or rerun.set_time_seconds.

For example: set_time_nanos("capture_time", nanos_since_unix_epoch).

You can remove a timeline again using set_time_nanos("capture_time", None).

Very large values will automatically be interpreted as nanoseconds since unix epoch (1970-01-01). Small values (less than a few years) will be interpreted as relative some unknown point in time, and will be shown as e.g. +3.132s.

The bindings has a built-in time which is log_time, and is logged as nanos since unix epoch.

There is no requirement of monotonicity. You can move the time backwards if you like.

Parameters:

Name Type Description Default
timeline str

The name of the timeline to set the time for.

required
nanos int

The current time on the timeline in nanoseconds.

required
recording Optional[RecordingStream]

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.

None

def log_annotation_context(entity_path, class_descriptions, *, timeless=True, recording=None)

Log an annotation context made up of a collection of ClassDescriptions.

Any entity needing to access the annotation context will find it by searching the path upward. If all entities share the same you can simply log it to the root ("/"), or if you want a per-entity ClassDescriptions log it to the same path as your entity.

Each ClassDescription must include an annotation info with an id, which will be used for matching the class and may optionally include a label and color. Colors should either be in 0-255 gamma space or in 0-1 gamma space. Colors can be RGB or RGBA.

These can either be specified verbosely as:

[AnnotationInfo(id=23, label='foo', color=(255, 0, 0)), ...]

Or using short-hand tuples.

[(23, 'bar'), ...]

Unspecified colors will be filled in by the visualizer randomly.

Parameters:

Name Type Description Default
entity_path str

The path to the annotation context in the space hierarchy.

required
class_descriptions Union[ClassDescriptionLike, Iterable[ClassDescriptionLike]]

A single ClassDescription or a collection of ClassDescriptions.

required
timeless bool

If true, the annotation context will be timeless (default: True).

True
recording Optional[RecordingStream]

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.

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.MemoryRecording.as_html][].

Parameters:

Name Type Description Default
recording Optional[RecordingStream]

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.

None

Returns:

Type Description
MemoryRecording

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

def script_teardown(args)

Run common post-actions. Sleep if serving the web viewer.

Parameters:

Name Type Description Default
args Namespace

The parsed arguments from parser.parse_args().

required

def log_depth_image(entity_path, image, *, draw_order=None, meter=None, ext=None, timeless=False, recording=None)

Log a depth image.

The image must be a 2D array.

Supported dtypes

uint8, uint16, float32, float64

Parameters:

Name Type Description Default
entity_path str

Path to the image in the space hierarchy.

required
image Tensor

A Tensor representing the depth image to log.

required
draw_order Optional[float]

An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. The default for images is -10.0.

None
meter Optional[float]

How long is a meter in the given dtype? For instance: with uint16, perhaps meter=1000 which would mean you have millimeter precision and a range of up to ~65 meters (2^16 / 1000).

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def serve(open_browser=True, web_port=None, ws_port=None, recording=None)

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

You can connect to this server using python -m rerun.

WARNING: This is an experimental feature.

This function returns immediately.

Parameters:

Name Type Description Default
open_browser bool

Open the default browser to the viewer.

True
web_port Optional[int]

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

None
ws_port Optional[int]

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

None
recording Optional[RecordingStream]

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.

None

def log_meshes(entity_path, position_buffers, *, vertex_color_buffers, index_buffers, normal_buffers, albedo_factors, timeless=False, recording=None)

Log multiple raw 3D meshes by specifying their different buffers and albedo factors.

To learn more about how the data within these buffers is interpreted and laid out, refer to the documentation for [rerun.log_mesh].

Parameters:

Name Type Description Default
entity_path str

Path to the mesh in the space hierarchy

required
position_buffers Sequence[npt.ArrayLike]

A sequence of position buffers, one for each mesh.

required
vertex_color_buffers Sequence[Optional[Colors]]

An optional sequence of vertex color buffers, one for each mesh.

required
index_buffers Sequence[Optional[npt.ArrayLike]]

An optional sequence of index buffers, one for each mesh.

required
normal_buffers Sequence[Optional[npt.ArrayLike]]

An optional sequence of normal buffers, one for each mesh.

required
albedo_factors Sequence[Optional[npt.ArrayLike]]

An optional sequence of albedo factors, one for each mesh.

required
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def reset_time(recording=None)

Clear all timeline information on this thread.

This is the same as calling set_time_* with None for all of the active timelines.

Used for all subsequent logging on the same thread, until the next call to rerun.set_time_nanos or rerun.set_time_seconds.

Parameters:

Name Type Description Default
recording Optional[RecordingStream]

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.

None

def log_image_file(entity_path, *, img_bytes=None, img_path=None, img_format=None, timeless=False, recording=None)

Log an image file given its contents or path on disk.

You must pass either img_bytes or img_path.

Only JPEGs and PNGs are supported right now.

JPEGs will be stored compressed, saving memory, whilst PNGs will currently be decoded before they are logged. This may change in the future.

If no img_format is specified, rerun will try to guess it.

Parameters:

Name Type Description Default
entity_path str

Path to the image in the space hierarchy.

required
img_bytes Optional[bytes]

Content of an image file, e.g. a .jpg.

None
img_path Optional[Path]

Path to an image file, e.g. a .jpg.

None
img_format Optional[ImageFormat]

Format of the image file.

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def log_unknown_transform(entity_path, timeless=False, recording=None)

Log that this entity is NOT in the same space as the parent, but you do not (yet) know how they relate.

Parameters:

Name Type Description Default
entity_path str

The path of the affected entity.

required

timeless: Log the data as timeless.

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.

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_rects(entity_path, rects, *, rect_format=RectFormat.XYWH, identifiers=None, colors=None, labels=None, class_ids=None, draw_order=None, ext=None, timeless=False, recording=None)

Log multiple 2D rectangles.

Logging again to the same entity_path will replace all the previous rectangles.

Colors should either be in 0-255 gamma space or in 0-1 linear space. Colors can be RGB or RGBA. You can supply no colors, one color, or one color per point in a Nx3 or Nx4 numpy array.

Supported dtypes for colors:
  • uint8: color components should be in 0-255 sRGB gamma space, except for alpha which should be in 0-255 linear space.
  • float32/float64: all color components should be in 0-1 linear space.

Parameters:

Name Type Description Default
entity_path str

Path to the rectangles in the space hierarchy.

required
rects Optional[npt.ArrayLike]

Nx4 numpy array, where each row is [x, y, w, h], or some format you pick with the rect_format argument.

required
rect_format RectFormat

how to interpret the rect argument

RectFormat.XYWH
identifiers Optional[Sequence[int]]

Unique numeric id that shows up when you hover or select the point.

None
colors Optional[Union[Color, Colors]]

Optional per-rectangle gamma-space RGB or RGBA as 0-1 floats or 0-255 integers.

None
labels Optional[Sequence[str]]

Optional per-rectangle text to show inside the rectangle.

None
class_ids OptionalClassIds

Optional class ids for the rectangles. The class id provides colors and labels if not specified explicitly. See rerun.log_annotation_context

None
draw_order Optional[float]

An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. The default for rects is 10.0.

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def log_line_segments(entity_path, positions, *, stroke_width=None, color=None, draw_order=None, ext=None, timeless=False, recording=None)

Log many 2D or 3D line segments.

The points will be connected in even-odd pairs, like so:

       2------3     5
                   /
0----1            /
                 4

Parameters:

Name Type Description Default
entity_path str

Path to the line segments in the space hierarchy

required
positions npt.ArrayLike

An Nx2 or Nx3 array of points. Even-odd pairs will be connected as segments.

required
stroke_width Optional[float]

Optional width of the line.

None
color Optional[Color]

Optional RGB or RGBA in sRGB gamma-space as either 0-1 floats or 0-255 integers, with separate alpha.

None
draw_order Optional[float]

An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. The default for lines is 20.0.

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def get_application_id(recording=None)

Get the application ID that this recording is associated with, if any.

Parameters:

Name Type Description Default
recording Optional[RecordingStream]

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.

None

Returns:

Type Description
str

The application ID that this recording is associated with.

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

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.

Parameters:

Name Type Description Default
application_id str

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

required
recording_id Optional[str]

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.

None
spawn bool

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

False
default_enabled bool

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

True
strict bool

If True, an exceptions is raised on use error (wrong parameter types etc). If False, errors are logged as warnings instead.

False

def spawn(port=9876, connect=True, 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.

Parameters:

Name Type Description Default
port int

The port to listen on.

9876
connect bool

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

True
recording Optional[RecordingStream]

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.

None

def log_rigid3(entity_path, *, parent_from_child=None, child_from_parent=None, xyz='', timeless=False, recording=None)

Log a proper rigid 3D transform between this entity and the parent.

Set either parent_from_child or child_from_parent to a tuple of (translation_xyz, quat_xyzw).

Parent-from-child

Also known as pose (e.g. camera extrinsics).

The translation is the position of the entity in the parent space. The resulting transform from child to parent corresponds to taking a point in the child space, rotating it by the given rotations, and then translating it by the given translation:

point_parent = translation + quat * point_child * quat*

Example
t = 0.0
translation = [math.sin(t), math.cos(t), 0.0] # circle around origin
rotation = [0.5, 0.0, 0.0, np.sin(np.pi/3)] # 60 degrees around x-axis
rerun.log_rigid3("sun/planet", parent_from_child=(translation, rotation))

Parameters:

Name Type Description Default
entity_path str

Path of the child space in the space hierarchy.

required
parent_from_child Optional[Tuple[npt.ArrayLike, npt.ArrayLike]]

A tuple of (translation_xyz, quat_xyzw) mapping points in the child space to the parent space.

None
child_from_parent Optional[Tuple[npt.ArrayLike, npt.ArrayLike]]

the inverse of parent_from_child

None
xyz str

Optionally set the view coordinates of this entity, e.g. to RDF for X=Right, Y=Down, Z=Forward. This is a convenience for also calling log_view_coordinates.

''
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

def log_points(entity_path, positions=None, *, identifiers=None, colors=None, radii=None, labels=None, class_ids=None, keypoint_ids=None, draw_order=None, ext=None, timeless=False, recording=None)

Log 2D or 3D points, with positions and optional colors, radii, labels, etc.

Logging again to the same entity_path will replace all the previous points.

Colors should either be in 0-255 gamma space or in 0-1 linear space. Colors can be RGB or RGBA. You can supply no colors, one color, or one color per point in a Nx3 or Nx4 numpy array.

Supported dtypes for colors:
  • uint8: color components should be in 0-255 sRGB gamma space, except for alpha which should be in 0-255 linear space.
  • float32/float64: all color components should be in 0-1 linear space.

Parameters:

Name Type Description Default
entity_path str

Path to the points in the space hierarchy.

required
positions Optional[npt.ArrayLike]

Nx2 or Nx3 array

None
identifiers Optional[npt.ArrayLike]

Unique numeric id that shows up when you hover or select the point.

None
colors Optional[Union[Color, Colors]]

Optional colors of the points. The colors are interpreted as RGB or RGBA in sRGB gamma-space, as either 0-1 floats or 0-255 integers, with separate alpha.

None
radii Optional[npt.ArrayLike]

Optional radii (make it a sphere).

None
labels Optional[Sequence[str]]

Optional per-point text to show with the points

None
class_ids OptionalClassIds

Optional class ids for the points. The class id provides colors and labels if not specified explicitly. See rerun.log_annotation_context

None
keypoint_ids OptionalKeyPointIds

Optional key point ids for the points, identifying them within a class. If keypoint_ids are passed in but no class_ids were specified, class_id will be set to 0. This is useful to identify points within a single classification (which is identified with class_id). E.g. the classification might be 'Person' and the keypoints refer to joints on a detected skeleton. See rerun.log_annotation_context

None
draw_order Optional[float]

An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. The default for 2D points is 30.0.

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

None

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.

Parameters:

Name Type Description Default
recording Optional[RecordingStream]

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.

None

Returns:

Type Description
str

The recording ID that this recording is logging to.

def log_segmentation_image(entity_path, image, *, draw_order=None, ext=None, timeless=False, recording=None)

Log an image made up of integer class-ids.

The image should have 1 channel, i.e. be either H x W or H x W x 1.

See: rerun.log_annotation_context for information on how to map the class-ids to colors and labels.

Supported dtypes

uint8, uint16

Parameters:

Name Type Description Default
entity_path str

Path to the image in the space hierarchy.

required
image npt.ArrayLike

A Tensor representing the segmentation image to log.

required
draw_order Optional[float]

An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. The default for images is -10.0.

None
ext Optional[Dict[str, Any]]

Optional dictionary of extension components. See rerun.log_extension_components

None
timeless bool

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

False
recording Optional[RecordingStream]

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.

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.

Parameters:

Name Type Description Default
recording Optional[RecordingStream]

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.

None

Returns:

Type Description
Optional[RecordingStream]

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

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.

Parameters:

Name Type Description Default
application_id str

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

required
recording_id Optional[str]

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.

None
make_default bool

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

False
make_thread_default bool

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

False
spawn bool

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

False
default_enabled bool

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

True

Returns:

Type Description
RecordingStream

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

def get_global_data_recording()

Returns the currently active global recording, if any.

Returns:

Type Description
Optional[RecordingStream]

The currently active global recording, if any.

def set_global_data_recording(recording)

Replaces the currently active global recording with the specified one.

Parameters:

Name Type Description Default
recording RecordingStream

The newly active global recording.

required

def get_thread_local_data_recording()

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

Returns:

Type Description
Optional[RecordingStream]

The currently active thread-local recording, if any.

def set_thread_local_data_recording(recording)

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

Parameters:

Name Type Description Default
recording RecordingStream

The newly active thread-local recording.

required

def version()

Returns a verbose version string of the Rerun SDK.

Example: rerun_py 0.6.0-alpha.0 [rustc 1.69.0 (84c898d65 2023-04-16), LLVM 15.0.7] aarch64-apple-darwin main bd8a072, built 2023-05-11T08:25:17Z

def strict_mode()

Strict mode enabled.

In strict mode, incorrect use of the Rerun API (wrong parameter types etc.) will result in exception being raised. When strict mode is on, such problems are instead logged as warnings.

The default is OFF.

def set_strict_mode(strict_mode)

Turn strict mode on/off.

In strict mode, incorrect use of the Rerun API (wrong parameter types etc.) will result in exception being raised. When strict mode is off, such problems are instead logged as warnings.

The default is OFF.

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 having the matching resources for your build (such as when running from source.)

Parameters:

Name Type Description Default
port int

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

0