Skip to content

Spatial Primitives

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

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[Sequence[int]]

Optional color of the point.

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

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

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.

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

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

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[Sequence[int]]

Optional RGB or RGBA triplet in 0-255 sRGB.

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

def rerun.log_rects(entity_path, rects, *, rect_format=RectFormat.XYWH, identifiers=None, colors=None, labels=None, class_ids=None, ext=None, timeless=False)

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 RGB or RGBA triplet in 0-255 sRGB.

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

def rerun.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)

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[Sequence[int]]

Optional RGB or RGBA triplet in 0-255 sRGB.

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

def rerun.log_line_strip(entity_path, positions, *, stroke_width=None, color=None, ext=None, timeless=False)

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[Sequence[int]]

Optional RGB or RGBA triplet in 0-255 sRGB.

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

def rerun.log_line_segments(entity_path, positions, *, stroke_width=None, color=None, ext=None, timeless=False)

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[Sequence[int]]

Optional RGB or RGBA triplet in 0-255 sRGB.

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

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

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[Sequence[int]]

An optional RGB or RGBA triplet in 0-255 sRGB.

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

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

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

None
timeless bool

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

False

def rerun.log_meshes(entity_path, position_buffers, *, vertex_color_buffers, index_buffers, normal_buffers, albedo_factors, timeless=False)

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

def rerun.log_mesh_file(entity_path, mesh_format, mesh_file, *, transform=None, timeless=False)

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

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_file bytes

Contents of the mesh file

required
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