Archetypes

`rerun.archetypes`

`class AnnotationContext`

Bases: Archetype

Archetype: The AnnotationContext provides additional information on how to display entities.

Entities can use ClassIds and KeypointIds to provide annotations, and the labels and colors will be looked up in the appropriate AnnotationContext. We use the first annotation context we find in the path-hierarchy when searching up through the ancestors of a given entity path.

Example

Segmentation:

import numpy as np
import rerun as rr

rr.init("rerun_example_annotation_context_segmentation", spawn=True)

# Create a simple segmentation image
image = np.zeros((200, 300), dtype=np.uint8)
image[50:100, 50:120] = 1
image[100:180, 130:280] = 2

# Log an annotation context to assign a label and color to each class
rr.log("segmentation", rr.AnnotationContext([(1, "red", (255, 0, 0)), (2, "green", (0, 255, 0))]), timeless=True)

rr.log("segmentation/image", rr.SegmentationImage(image))

`def init(context)`

Create a new instance of the AnnotationContext archetype.

PARAMETER	DESCRIPTION
`context`	List of class descriptions, mapping class indices to class names, colors etc. TYPE: `AnnotationContextLike`

`class Arrows3D`

Bases: Arrows3DExt, Archetype

Archetype: 3D arrows with optional colors, radii, labels, etc.

Example

Simple batch of 3D Arrows:

from math import tau

import numpy as np
import rerun as rr

rr.init("rerun_example_arrow3d", spawn=True)

lengths = np.log2(np.arange(0, 100) + 1)
angles = np.arange(start=0, stop=tau, step=tau * 0.01)
origins = np.zeros((100, 3))
vectors = np.column_stack([np.sin(angles) * lengths, np.zeros(100), np.cos(angles) * lengths])
colors = [[1.0 - c, c, 0.5, 0.5] for c in angles / tau]

rr.log("arrows", rr.Arrows3D(origins=origins, vectors=vectors, colors=colors))

`def init(*, vectors, origins=None, radii=None, colors=None, labels=None, class_ids=None, instance_keys=None)`

Create a new instance of the Arrows3D archetype.

PARAMETER	DESCRIPTION
`vectors`	All the vectors for each arrow in the batch. TYPE: `Vec3DArrayLike`
`origins`	All the origin points for each arrow in the batch. If no origins are set, (0, 0, 0) is used as the origin for each arrow. TYPE: `Vec3DArrayLike \| None` DEFAULT: `None`
`radii`	Optional radii for the arrows. The shaft is rendered as a line with `radius = 0.5 * radius`. The tip is rendered with `height = 2.0 * radius` and `radius = 1.0 * radius`. TYPE: `RadiusArrayLike \| None` DEFAULT: `None`
`colors`	Optional colors for the points. TYPE: `Rgba32ArrayLike \| None` DEFAULT: `None`
`labels`	Optional text labels for the arrows. TYPE: `Utf8ArrayLike \| None` DEFAULT: `None`
`class_ids`	Optional class Ids for the points. The class ID provides colors and labels if not specified explicitly. TYPE: `ClassIdArrayLike \| None` DEFAULT: `None`
`instance_keys`	Unique identifiers for each individual point in the batch. TYPE: `InstanceKeyArrayLike \| None` DEFAULT: `None`

`class Asset3D`

Bases: Asset3DExt, Archetype

Archetype: A prepacked 3D asset (.gltf, .glb, .obj, etc.).

Example

Simple 3D asset:

import sys

import rerun as rr

if len(sys.argv) < 2:
    print(f"Usage: {sys.argv[0]} <path_to_asset.[gltf|glb|obj]>")
    sys.exit(1)

rr.init("rerun_example_asset3d_simple", spawn=True)

rr.log("world", rr.ViewCoordinates.RIGHT_HAND_Z_UP, timeless=True)  # Set an up-axis
rr.log("world/asset", rr.Asset3D(path=sys.argv[1]))

`def init(*, path=None, contents=None, media_type=None, transform=None)`

Create a new instance of the Asset3D archetype.

PARAMETER	DESCRIPTION
`path`	A path to an file stored on the local filesystem. Mutually exclusive with `contents`. TYPE: `str \| Path \| None` DEFAULT: `None`

contents: The contents of the file. Can be a BufferedReader, BytesIO, or bytes. Mutually exclusive with path.

media_type: The Media Type of the asset.

For instance:
 * `model/gltf-binary`
 * `model/obj`

If omitted, it will be guessed from the `path` (if any),
or the viewer will try to guess from the contents (magic header).
If the media type cannot be guessed, the viewer won't be able to render the asset.

transform: An out-of-tree transform.

Applies a transformation to the asset itself without impacting its children.

`class BarChart`

Bases: BarChartExt, Archetype

Archetype: A bar chart.

The x values will be the indices of the array, and the bar heights will be the provided values.

Example

Simple bar chart:

import rerun as rr

rr.init("rerun_example_bar_chart", spawn=True)
rr.log("bar_chart", rr.BarChart([8, 4, 0, 9, 1, 4, 1, 6, 9, 0]))

`def init(values)`

Create a new instance of the BarChart archetype.

PARAMETER	DESCRIPTION
`values`	The values. Should always be a rank-1 tensor. TYPE: `TensorDataLike`

`class Boxes2D`

Bases: Boxes2DExt, Archetype

Archetype: 2D boxes with half-extents and optional center, rotations, rotations, colors etc.

Example

Simple 2D boxes:

import rerun as rr

rr.init("rerun_example_box2d", spawn=True)

rr.log("simple", rr.Boxes2D(mins=[-1, -1], sizes=[2, 2]))

# Log an extra rect to set the view bounds
rr.log("bounds", rr.Boxes2D(sizes=[4.0, 3.0]))

`def init(*, sizes=None, mins=None, half_sizes=None, centers=None, array=None, array_format=None, radii=None, colors=None, labels=None, draw_order=None, class_ids=None, instance_keys=None)`

Create a new instance of the Boxes2D archetype.

PARAMETER	DESCRIPTION
`sizes`	Full extents in x/y. Incompatible with `array` and `half_sizes`. TYPE: `Vec2DArrayLike \| None` DEFAULT: `None`
`half_sizes`	All half-extents that make up the batch of boxes. Specify this instead of `sizes` Incompatible with `array` and `sizes`. TYPE: `Vec2DArrayLike \| None` DEFAULT: `None`
`mins`	Minimum coordinates of the boxes. Specify this instead of `centers`. Incompatible with `array`. Only valid when used together with either `sizes` or `half_sizes`. TYPE: `Vec2DArrayLike \| None` DEFAULT: `None`
`array`	An array of boxes in the format specified by `array_format`. Requires specifying `array_format`. Incompatible with `sizes`, `half_sizes`, `mins` and `centers`. TYPE: `ArrayLike \| None` DEFAULT: `None`
`array_format`	How to interpret the data in `array`. TYPE: `Box2DFormat \| None` DEFAULT: `None`
`centers`	Optional center positions of the boxes. TYPE: `Vec2DArrayLike \| None` DEFAULT: `None`
`colors`	Optional colors for the boxes. TYPE: `Rgba32ArrayLike \| None` DEFAULT: `None`
`radii`	Optional radii for the lines that make up the boxes. TYPE: `RadiusArrayLike \| None` DEFAULT: `None`
`labels`	Optional text labels for the boxes. TYPE: `Utf8ArrayLike \| None` DEFAULT: `None`
`draw_order`	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 boxes is 10.0. TYPE: `DrawOrderLike \| None` DEFAULT: `None`
`class_ids`	Optional `ClassId`s for the boxes. The class ID provides colors and labels if not specified explicitly. TYPE: `ClassIdArrayLike \| None` DEFAULT: `None`
`instance_keys`	Unique identifiers for each individual boxes in the batch. TYPE: `InstanceKeyArrayLike \| None` DEFAULT: `None`

`class Boxes3D`

Bases: Boxes3DExt, Archetype

Archetype: 3D boxes with half-extents and optional center, rotations, rotations, colors etc.

Example

Batch of 3D boxes:

import rerun as rr
from rerun.datatypes import Angle, Quaternion, Rotation3D, RotationAxisAngle

rr.init("rerun_example_box3d_batch", spawn=True)

rr.log(
    "batch",
    rr.Boxes3D(
        centers=[[2, 0, 0], [-2, 0, 0], [0, 0, 2]],
        half_sizes=[[2.0, 2.0, 1.0], [1.0, 1.0, 0.5], [2.0, 0.5, 1.0]],
        rotations=[
            Rotation3D.identity(),
            Quaternion(xyzw=[0.0, 0.0, 0.382683, 0.923880]),  # 45 degrees around Z
            RotationAxisAngle(axis=[0, 1, 0], angle=Angle(deg=30)),
        ],
        radii=0.025,
        colors=[(255, 0, 0), (0, 255, 0), (0, 0, 255)],
        labels=["red", "green", "blue"],
    ),
)

`def init(*, sizes=None, mins=None, half_sizes=None, centers=None, rotations=None, colors=None, radii=None, labels=None, class_ids=None, instance_keys=None)`

Create a new instance of the Boxes3D archetype.

PARAMETER	DESCRIPTION
`sizes`	Full extents in x/y/z. Specify this instead of `half_sizes` TYPE: `Vec3DArrayLike \| None` DEFAULT: `None`
`half_sizes`	All half-extents that make up the batch of boxes. Specify this instead of `sizes` TYPE: `Vec3DArrayLike \| None` DEFAULT: `None`
`mins`	Minimum coordinates of the boxes. Specify this instead of `centers`. Only valid when used together with either `sizes` or `half_sizes`. TYPE: `Vec3DArrayLike \| None` DEFAULT: `None`
`centers`	Optional center positions of the boxes. TYPE: `Vec3DArrayLike \| None` DEFAULT: `None`
`rotations`	Optional rotations of the boxes. TYPE: `Rotation3DArrayLike \| None` DEFAULT: `None`
`colors`	Optional colors for the boxes. TYPE: `Rgba32ArrayLike \| None` DEFAULT: `None`
`radii`	Optional radii for the lines that make up the boxes. TYPE: `RadiusArrayLike \| None` DEFAULT: `None`
`labels`	Optional text labels for the boxes. TYPE: `Utf8ArrayLike \| None` DEFAULT: `None`
`class_ids`	Optional `ClassId`s for the boxes. The class ID provides colors and labels if not specified explicitly. TYPE: `ClassIdArrayLike \| None` DEFAULT: `None`
`instance_keys`	Unique identifiers for each individual boxes in the batch. TYPE: `InstanceKeyArrayLike \| None` DEFAULT: `None`

`class Clear`

Bases: ClearExt, Archetype

Archetype: Empties all the components of an entity.

Example

Flat:

import rerun as rr

rr.init("rerun_example_clear_simple", spawn=True)

vectors = [(1.0, 0.0, 0.0), (0.0, -1.0, 0.0), (-1.0, 0.0, 0.0), (0.0, 1.0, 0.0)]
origins = [(-0.5, 0.5, 0.0), (0.5, 0.5, 0.0), (0.5, -0.5, 0.0), (-0.5, -0.5, 0.0)]
colors = [(200, 0, 0), (0, 200, 0), (0, 0, 200), (200, 0, 200)]

# Log a handful of arrows.
for i, (vector, origin, color) in enumerate(zip(vectors, origins, colors)):
    rr.log(f"arrows/{i}", rr.Arrows3D(vectors=vector, origins=origin, colors=color))

# Now clear them, one by one on each tick.
for i in range(len(vectors)):
    rr.log(f"arrows/{i}", rr.Clear(recursive=False))  # or `rr.Clear.flat()`

`def init(*, recursive)`

Create a new instance of the Clear archetype.

PARAMETER	DESCRIPTION
`recursive`	Whether to recursively clear all children. TYPE: `bool`

`def flat()` `staticmethod`

Returns a non-recursive clear archetype.

This will empty all components of the associated entity at the logged timepoint. Children will be left untouched.

`def recursive()` `staticmethod`

Returns a recursive clear archetype.

This will empty all components of the associated entity at the logged timepoint, as well as all components of all its recursive children.

`class DepthImage`

Bases: DepthImageExt, Archetype

Archetype: A depth image.

The shape of the TensorData must be mappable to an HxW tensor. Each pixel corresponds to a depth value in units specified by meter.

Example

Depth to 3D example:

import numpy as np
import rerun as rr

depth_image = 65535 * np.ones((200, 300), dtype=np.uint16)
depth_image[50:150, 50:150] = 20000
depth_image[130:180, 100:280] = 45000

rr.init("rerun_example_depth_image", spawn=True)

# If we log a pinhole camera model, the depth gets automatically back-projected to 3D
rr.log(
    "world/camera",
    rr.Pinhole(
        width=depth_image.shape[1],
        height=depth_image.shape[0],
        focal_length=200,
    ),
)

# Log the tensor.
rr.log("world/camera/depth", rr.DepthImage(depth_image, meter=10_000.0))

`def init(data, *, meter=None, draw_order=None)`

Create a new instance of the DepthImage archetype.

PARAMETER	DESCRIPTION
`data`	The depth-image data. Should always be a rank-2 tensor. TYPE: `TensorDataLike`
`meter`	An optional floating point value that specifies how long a meter is in the native depth units. 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). TYPE: `DepthMeterLike \| None` DEFAULT: `None`
`draw_order`	An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. TYPE: `DrawOrderLike \| None` DEFAULT: `None`

`class DisconnectedSpace`

Bases: DisconnectedSpaceExt, Archetype

Archetype: Specifies that the entity path at which this is logged is disconnected from its parent.

This is useful for specifying that a subgraph is independent of the rest of the scene.

If a transform or pinhole is logged on the same path, this archetype's components will be ignored.

Example

Disconnected Space:

import rerun as rr

rr.init("rerun_example_disconnect_space", spawn=True)

# These two points can be projected into the same space..
rr.log("world/room1/point", rr.Points3D([[0, 0, 0]]))
rr.log("world/room2/point", rr.Points3D([[1, 1, 1]]))

# ..but this one lives in a completely separate space!
rr.log("world/wormhole", rr.DisconnectedSpace())
rr.log("world/wormhole/point", rr.Points3D([[2, 2, 2]]))

`def init(is_disconnected=True)`

Disconnect an entity from its parent.

PARAMETER	DESCRIPTION
`is_disconnected`	Whether or not the entity should be disconnected from the rest of the scene. Set to `True` to disconnect the entity from its parent. Set to `False` to disable the effects of this archetype, (re-)connecting the entity to its parent again. TYPE: `DisconnectedSpaceLike` DEFAULT: `True`

`class Image`

Bases: ImageExt, Archetype

Archetype: A monochrome or color image.

The shape of the TensorData must be mappable to: - A HxW tensor, treated as a grayscale image. - A HxWx3 tensor, treated as an RGB image. - A HxWx4 tensor, treated as an RGBA image.

Leading and trailing unit-dimensions are ignored, so that 1x640x480x3x1 is treated as a 640x480x3 RGB image.

Example

`image_simple`:

import numpy as np
import rerun as rr

# Create an image with numpy
image = np.zeros((200, 300, 3), dtype=np.uint8)
image[:, :, 0] = 255
image[50:150, 50:150] = (0, 255, 0)

rr.init("rerun_example_image_simple", spawn=True)

rr.log("image", rr.Image(image))

`def init(data, *, draw_order=None)`

Create a new instance of the Image archetype.

PARAMETER	DESCRIPTION
`data`	The image data. Should always be a rank-2 or rank-3 tensor. TYPE: `TensorDataLike`
`draw_order`	An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. TYPE: `DrawOrderLike \| None` DEFAULT: `None`

`def compress(*, jpeg_quality=95)`

Converts an Image to an rerun.ImageEncoded using JPEG compression.

JPEG compression works best for photographs. Only RGB or Mono images are supported, not RGBA. Note that compressing to JPEG costs a bit of CPU time, both when logging and later when viewing them.

PARAMETER	DESCRIPTION
`jpeg_quality`	Higher quality = larger file size. A quality of 95 still saves a lot of space, but is visually very similar. TYPE: `int` DEFAULT: `95`

`class LineStrips2D`

Bases: Archetype

Archetype: 2D line strips with positions and optional colors, radii, labels, etc.

Example

`line_strip2d_batch`:

import rerun as rr

rr.init("rerun_example_line_strip2d", spawn=True)

rr.log(
    "strips",
    rr.LineStrips2D(
        [
            [[0, 0], [2, 1], [4, -1], [6, 0]],
            [[0, 3], [1, 4], [2, 2], [3, 4], [4, 2], [5, 4], [6, 3]],
        ],
        colors=[[255, 0, 0], [0, 255, 0]],
        radii=[0.025, 0.005],
        labels=["one strip here", "and one strip there"],
    ),
)

# Log an extra rect to set the view bounds
rr.log("bounds", rr.Boxes2D(centers=[3, 1.5], half_sizes=[4.0, 4.5]))

`def init(strips, *, radii=None, colors=None, labels=None, draw_order=None, class_ids=None, instance_keys=None)`

Create a new instance of the LineStrips2D archetype.

PARAMETER	DESCRIPTION
`strips`	All the actual 2D line strips that make up the batch. TYPE: `LineStrip2DArrayLike`
`radii`	Optional radii for the line strips. TYPE: `RadiusArrayLike \| None` DEFAULT: `None`
`colors`	Optional colors for the line strips. TYPE: `Rgba32ArrayLike \| None` DEFAULT: `None`
`labels`	Optional text labels for the line strips. TYPE: `Utf8ArrayLike \| None` DEFAULT: `None`
`draw_order`	An optional floating point value that specifies the 2D drawing order of each line strip. Objects with higher values are drawn on top of those with lower values. TYPE: `DrawOrderLike \| None` DEFAULT: `None`
`class_ids`	Optional `ClassId`s for the lines. The class ID provides colors and labels if not specified explicitly. TYPE: `ClassIdArrayLike \| None` DEFAULT: `None`
`instance_keys`	Unique identifiers for each individual line strip in the batch. TYPE: `InstanceKeyArrayLike \| None` DEFAULT: `None`

`class LineStrips3D`

Bases: Archetype

Archetype: 3D line strips with positions and optional colors, radii, labels, etc.

Example

Many strips:

import rerun as rr

rr.init("rerun_example_line_strip3d", spawn=True)

rr.log(
    "strips",
    rr.LineStrips3D(
        [
            [
                [0, 0, 2],
                [1, 0, 2],
                [1, 1, 2],
                [0, 1, 2],
            ],
            [
                [0, 0, 0],
                [0, 0, 1],
                [1, 0, 0],
                [1, 0, 1],
                [1, 1, 0],
                [1, 1, 1],
                [0, 1, 0],
                [0, 1, 1],
            ],
        ],
        colors=[[255, 0, 0], [0, 255, 0]],
        radii=[0.025, 0.005],
        labels=["one strip here", "and one strip there"],
    ),
)

`def init(strips, *, radii=None, colors=None, labels=None, class_ids=None, instance_keys=None)`

Create a new instance of the LineStrips3D archetype.

PARAMETER	DESCRIPTION
`strips`	All the actual 3D line strips that make up the batch. TYPE: `LineStrip3DArrayLike`
`radii`	Optional radii for the line strips. TYPE: `RadiusArrayLike \| None` DEFAULT: `None`
`colors`	Optional colors for the line strips. TYPE: `Rgba32ArrayLike \| None` DEFAULT: `None`
`labels`	Optional text labels for the line strips. TYPE: `Utf8ArrayLike \| None` DEFAULT: `None`
`class_ids`	Optional `ClassId`s for the lines. The class ID provides colors and labels if not specified explicitly. TYPE: `ClassIdArrayLike \| None` DEFAULT: `None`
`instance_keys`	Unique identifiers for each individual line strip in the batch. TYPE: `InstanceKeyArrayLike \| None` DEFAULT: `None`

`class Mesh3D`

Bases: Mesh3DExt, Archetype

Archetype: A 3D triangle mesh as specified by its per-mesh and per-vertex properties.

Example

Simple indexed 3D mesh:

import rerun as rr

rr.init("rerun_example_mesh3d_indexed", spawn=True)

rr.log(
    "triangle",
    rr.Mesh3D(
        vertex_positions=[[0.0, 1.0, 0.0], [1.0, 0.0, 0.0], [0.0, 0.0, 0.0]],
        vertex_normals=[0.0, 0.0, 1.0],
        vertex_colors=[[0, 0, 255], [0, 255, 0], [255, 0, 0]],
        indices=[2, 1, 0],
        mesh_material=rr.Material(albedo_factor=[0xCC, 0x00, 0xCC, 0xFF]),
    ),
)

`def init(*, vertex_positions, indices=None, mesh_properties=None, vertex_normals=None, vertex_colors=None, mesh_material=None, class_ids=None, instance_keys=None)`

Create a new instance of the Mesh3D archetype.

PARAMETER	DESCRIPTION
`vertex_positions`	The positions of each vertex. If no `indices` are specified, then each triplet of positions is interpreted as a triangle. TYPE: `Vec3DArrayLike`
`indices`	If specified, a flattened array of indices that describe the mesh's triangles, i.e. its length must be divisible by 3. Mutually exclusive with `mesh_properties`. TYPE: `ArrayLike \| None` DEFAULT: `None`
`mesh_properties`	Optional properties for the mesh as a whole (including indexed drawing). Mutually exclusive with `indices`. TYPE: `MeshPropertiesLike \| None` DEFAULT: `None`
`vertex_normals`	An optional normal for each vertex. If specified, this must have as many elements as `vertex_positions`. TYPE: `Vec3DArrayLike \| None` DEFAULT: `None`
`vertex_colors`	An optional color for each vertex. TYPE: `Rgba32ArrayLike \| None` DEFAULT: `None`
`mesh_material`	Optional material properties for the mesh as a whole. TYPE: `MaterialLike \| None` DEFAULT: `None`
`class_ids`	Optional class Ids for the vertices. The class ID provides colors and labels if not specified explicitly. TYPE: `ClassIdArrayLike \| None` DEFAULT: `None`
`instance_keys`	Unique identifiers for each individual vertex in the mesh. TYPE: `InstanceKeyArrayLike \| None` DEFAULT: `None`

`class Pinhole`

Bases: PinholeExt, Archetype

Archetype: Camera perspective projection (a.k.a. intrinsics).

Example

Simple Pinhole Camera:

import numpy as np
import rerun as rr

rr.init("rerun_example_pinhole", spawn=True)
rng = np.random.default_rng(12345)

image = rng.uniform(0, 255, size=[3, 3, 3])
rr.log("world/image", rr.Pinhole(focal_length=3, width=3, height=3))
rr.log("world/image", rr.Image(image))

`def init(*, image_from_camera=None, resolution=None, camera_xyz=None, width=None, height=None, focal_length=None, principal_point=None)`

Create a new instance of the Pinhole archetype.

PARAMETER	DESCRIPTION
`image_from_camera`	Row-major intrinsics matrix for projecting from camera space to image space. The first two axes are X=Right and Y=Down, respectively. Projection is done along the positive third (Z=Forward) axis. This can be specified instead of `focal_length` and `principal_point`. TYPE: `Mat3x3Like \| None` DEFAULT: `None`
`resolution`	Pixel resolution (usually integers) of child image space. Width and height. `image_from_camera` projects onto the space spanned by `(0,0)` and `resolution - 1`. TYPE: `Vec2DLike \| None` DEFAULT: `None`
`camera_xyz`	Sets the view coordinates for the camera. All common values are available as constants on the `components.ViewCoordinates` class. The default is `ViewCoordinates.RDF`, i.e. X=Right, Y=Down, Z=Forward, and this is also the recommended setting. This means that the camera frustum will point along the positive Z axis of the parent space, and the cameras "up" direction will be along the negative Y axis of the parent space. The camera frustum will point whichever axis is set to `F` (or the opposite of `B`). When logging a depth image under this entity, this is the direction the point cloud will be projected. With `RDF`, the default forward is +Z. The frustum's "up" direction will be whichever axis is set to `U` (or the opposite of `D`). This will match the negative Y direction of pixel space (all images are assumed to have xyz=RDF). With `RDF`, the default is up is -Y. The frustum's "right" direction will be whichever axis is set to `R` (or the opposite of `L`). This will match the positive X direction of pixel space (all images are assumed to have xyz=RDF). With `RDF`, the default right is +x. Other common formats are `RUB` (X=Right, Y=Up, Z=Back) and `FLU` (X=Forward, Y=Left, Z=Up). NOTE: setting this to something else than `RDF` (the default) will change the orientation of the camera frustum, and make the pinhole matrix not match up with the coordinate system of the pinhole entity. The pinhole matrix (the `image_from_camera` argument) always project along the third (Z) axis, but will be re-oriented to project along the forward axis of the `camera_xyz` argument. TYPE: `ViewCoordinatesLike \| None` DEFAULT: `None`
`focal_length`	The focal length of the camera in pixels. This is the diagonal of the projection matrix. Set one value for symmetric cameras, or two values (X=Right, Y=Down) for anamorphic cameras. TYPE: `float \| ArrayLike \| None` DEFAULT: `None`
`principal_point`	The center of the camera in pixels. The default is half the width and height. This is the last column of the projection matrix. Expects two values along the dimensions Right and Down TYPE: `ArrayLike \| None` DEFAULT: `None`
`width`	Width of the image in pixels. TYPE: `int \| float \| None` DEFAULT: `None`
`height`	Height of the image in pixels. TYPE: `int \| float \| None` DEFAULT: `None`

`class Points2D`

Bases: Points2DExt, Archetype

Archetype: A 2D point cloud with positions and optional colors, radii, labels, etc.

Example

Randomly distributed 2D points with varying color and radius:

import rerun as rr
from numpy.random import default_rng

rr.init("rerun_example_points2d", spawn=True)
rng = default_rng(12345)

positions = rng.uniform(-3, 3, size=[10, 2])
colors = rng.uniform(0, 255, size=[10, 4])
radii = rng.uniform(0, 1, size=[10])

rr.log("random", rr.Points2D(positions, colors=colors, radii=radii))

# Log an extra rect to set the view bounds
rr.log("bounds", rr.Boxes2D(half_sizes=[4, 3]))

`def init(positions, *, radii=None, colors=None, labels=None, draw_order=None, class_ids=None, keypoint_ids=None, instance_keys=None)`

Create a new instance of the Points2D archetype.

PARAMETER	DESCRIPTION
`positions`	All the 2D positions at which the point cloud shows points. TYPE: `Vec2DArrayLike`
`radii`	Optional radii for the points, effectively turning them into circles. TYPE: `RadiusArrayLike \| None` DEFAULT: `None`
`colors`	Optional colors for 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. TYPE: `Rgba32ArrayLike \| None` DEFAULT: `None`
`labels`	Optional text labels for the points. TYPE: `Utf8ArrayLike \| None` DEFAULT: `None`
`draw_order`	An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. TYPE: `DrawOrderLike \| None` DEFAULT: `None`
`class_ids`	Optional class Ids for the points. The class ID provides colors and labels if not specified explicitly. TYPE: `ClassIdArrayLike \| None` DEFAULT: `None`
`keypoint_ids`	Optional keypoint IDs for the points, identifying them within a class. If keypoint IDs are passed in but no class IDs were specified, the class ID will default 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. TYPE: `KeypointIdArrayLike \| None` DEFAULT: `None`
`instance_keys`	Unique identifiers for each individual point in the batch. TYPE: `InstanceKeyArrayLike \| None` DEFAULT: `None`

`class Points3D`

Bases: Points3DExt, Archetype

Archetype: A 3D point cloud with positions and optional colors, radii, labels, etc.

Example

Randomly distributed 3D points with varying color and radius:

import rerun as rr
from numpy.random import default_rng

rr.init("rerun_example_points3d_random", spawn=True)
rng = default_rng(12345)

positions = rng.uniform(-5, 5, size=[10, 3])
colors = rng.uniform(0, 255, size=[10, 3])
radii = rng.uniform(0, 1, size=[10])

rr.log("random", rr.Points3D(positions, colors=colors, radii=radii))

`def init(positions, *, radii=None, colors=None, labels=None, class_ids=None, keypoint_ids=None, instance_keys=None)`

Create a new instance of the Points3D archetype.

PARAMETER	DESCRIPTION
`positions`	All the 3D positions at which the point cloud shows points. TYPE: `Vec3DArrayLike`
`radii`	Optional radii for the points, effectively turning them into circles. TYPE: `RadiusArrayLike \| None` DEFAULT: `None`
`colors`	Optional colors for 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. TYPE: `Rgba32ArrayLike \| None` DEFAULT: `None`
`labels`	Optional text labels for the points. TYPE: `Utf8ArrayLike \| None` DEFAULT: `None`
`class_ids`	Optional class Ids for the points. The class ID provides colors and labels if not specified explicitly. TYPE: `ClassIdArrayLike \| None` DEFAULT: `None`
`keypoint_ids`	Optional keypoint IDs for the points, identifying them within a class. If keypoint IDs are passed in but no class IDs were specified, the class ID will default 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. TYPE: `KeypointIdArrayLike \| None` DEFAULT: `None`
`instance_keys`	Unique identifiers for each individual point in the batch. TYPE: `InstanceKeyArrayLike \| None` DEFAULT: `None`

`class SegmentationImage`

Bases: SegmentationImageExt, Archetype

Archetype: An image made up of integer class-ids.

The shape of the TensorData must be mappable to an HxW tensor. Each pixel corresponds to a depth value in units specified by meter.

Leading and trailing unit-dimensions are ignored, so that 1x640x480x1 is treated as a 640x480 image.

See also AnnotationContext to associate each class with a color and a label.

Example

Simple segmentation image:

import numpy as np
import rerun as rr

# Create a segmentation image
image = np.zeros((8, 12), dtype=np.uint8)
image[0:4, 0:6] = 1
image[4:8, 6:12] = 2

rr.init("rerun_example_segmentation_image", spawn=True)

# Assign a label and color to each class
rr.log("/", rr.AnnotationContext([(1, "red", (255, 0, 0)), (2, "green", (0, 255, 0))]), timeless=True)

rr.log("image", rr.SegmentationImage(image))

`def init(data, *, draw_order=None)`

Create a new instance of the SegmentationImage archetype.

PARAMETER	DESCRIPTION
`data`	The image data. Should always be a rank-2 tensor. TYPE: `TensorDataLike`
`draw_order`	An optional floating point value that specifies the 2D drawing order. Objects with higher values are drawn on top of those with lower values. TYPE: `DrawOrderLike \| None` DEFAULT: `None`

`class Tensor`

Bases: TensorExt, Archetype

Archetype: A generic n-dimensional Tensor.

Example

Simple Tensor:

import numpy as np
import rerun as rr

tensor = np.random.randint(0, 256, (8, 6, 3, 5), dtype=np.uint8)  # 4-dimensional tensor

rr.init("rerun_example_tensor_simple", spawn=True)

# Log the tensor, assigning names to each dimension
rr.log("tensor", rr.Tensor(tensor, dim_names=("width", "height", "channel", "batch")))

`def init(data=None, *, dim_names=None)`

Construct a Tensor archetype.

The Tensor archetype internally contains a single component: TensorData.

See the TensorData constructor for more advanced options to interpret buffers as TensorData of varying shapes.

For simple cases, you can pass array objects and optionally specify the names of the dimensions. The shape of the TensorData will be inferred from the array.

PARAMETER	DESCRIPTION
`self`	The TensorData object to construct. TYPE: `Any`
`data`	A TensorData object, or type that can be converted to a numpy array. TYPE: `TensorDataLike \| TensorLike \| None` DEFAULT: `None`
`dim_names`	The names of the tensor dimensions when generating the shape from an array. TYPE: `Sequence[str \| None] \| None` DEFAULT: `None`

`class TextDocument`

Bases: Archetype

Archetype: A text element intended to be displayed in its own text-box.

Supports raw text and markdown.

Example

Markdown text document:

import rerun as rr

rr.init("rerun_example_text_document", spawn=True)

rr.log("text_document", rr.TextDocument("Hello, TextDocument!"))

rr.log(
    "markdown",
    rr.TextDocument(
        '''
# Hello Markdown!
[Click here to see the raw text](recording://markdown.Text).

Basic formatting:

| **Feature**       | **Alternative** |
| ----------------- | --------------- |
| Plain             |                 |
| *italics*         | _italics_       |
| **bold**          | __bold__        |
| ~~strikethrough~~ |                 |
| `inline code`     |                 |

----------------------------------

## Support
- [x] [Commonmark](https://commonmark.org/help/) support
- [x] GitHub-style strikethrough, tables, and checkboxes
- Basic syntax highlighting for:
  - [x] C and C++
  - [x] Python
  - [x] Rust
  - [ ] Other languages

## Links
You can link to [an entity](recording://markdown),
a [specific instance of an entity](recording://markdown[#0]),
or a [specific component](recording://markdown.Text).

Of course you can also have [normal https links](https://github.com/rerun-io/rerun), e.g. <https://rerun.io>.

## Image
![A random image](https://picsum.photos/640/480)
'''.strip(),
        media_type=rr.MediaType.MARKDOWN,
    ),
)

`def init(text, *, media_type=None)`

Create a new instance of the TextDocument archetype.

PARAMETER	DESCRIPTION
`text`	Contents of the text document. TYPE: `Utf8Like`
`media_type`	The Media Type of the text. For instance: * `text/plain` * `text/markdown` If omitted, `text/plain` is assumed. TYPE: `Utf8Like \| None` DEFAULT: `None`

`class TextLog`

Bases: Archetype

Archetype: A log entry in a text log, comprised of a text body and its log level.

Example

`text_log_integration`:

import logging

import rerun as rr

rr.init("rerun_example_text_log_integration", spawn=True)

# Log a text entry directly
rr.log("logs", rr.TextLog("this entry has loglevel TRACE", level=rr.TextLogLevel.TRACE))

# Or log via a logging handler
logging.getLogger().addHandler(rr.LoggingHandler("logs/handler"))
logging.getLogger().setLevel(-1)
logging.info("This INFO log got added through the standard logging interface")

`def init(text, *, level=None, color=None)`

Create a new instance of the TextLog archetype.

PARAMETER	DESCRIPTION
`text`	The body of the message. TYPE: `Utf8Like`
`level`	The verbosity level of the message. This can be used to filter the log messages in the Rerun Viewer. TYPE: `Utf8Like \| None` DEFAULT: `None`
`color`	Optional color to use for the log line in the Rerun Viewer. TYPE: `Rgba32Like \| None` DEFAULT: `None`

`class TimeSeriesScalar`

Bases: Archetype

Archetype: Log a double-precision scalar that will be visualized as a time-series plot.

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

Example

Simple line plot:

import math

import rerun as rr

rr.init("rerun_example_scalar", spawn=True)

for step in range(0, 64):
    rr.set_time_sequence("step", step)
    rr.log("scalar", rr.TimeSeriesScalar(math.sin(step / 10.0)))

`def init(scalar, *, radius=None, color=None, label=None, scattered=None)`

Create a new instance of the TimeSeriesScalar archetype.

PARAMETER	DESCRIPTION
`scalar`	The scalar value to log. TYPE: `ScalarLike`
`radius`	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`. TYPE: `RadiusLike \| None` DEFAULT: `None`
`color`	Optional color for the scalar entry. 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. TYPE: `Rgba32Like \| None` DEFAULT: `None`
`label`	An optional label for the point. TODO(#1289): This won't show up on points at the moment, as our plots don't yet support displaying labels for individual points. 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. TYPE: `Utf8Like \| None` DEFAULT: `None`
`scattered`	Specifies whether a point in a scatter plot should form a continuous line. If set to true, this scalar will be drawn as a point, akin to a scatterplot. Otherwise, it will form a continuous line with its neighbors. 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. TYPE: `ScalarScatteringLike \| None` DEFAULT: `None`

`class Transform3D`

Bases: Transform3DExt, Archetype

Archetype: A 3D transform.

Example

Variety of 3D transforms:

from math import pi

import rerun as rr
from rerun.datatypes import Angle, RotationAxisAngle

rr.init("rerun_example_transform3d", spawn=True)

arrow = rr.Arrows3D(origins=[0, 0, 0], vectors=[0, 1, 0])

rr.log("base", arrow)

rr.log("base/translated", rr.Transform3D(translation=[1, 0, 0]))
rr.log("base/translated", arrow)

rr.log(
    "base/rotated_scaled",
    rr.Transform3D(
        rotation=RotationAxisAngle(axis=[0, 0, 1], angle=Angle(rad=pi / 4)),
        scale=2,
    ),
)
rr.log("base/rotated_scaled", arrow)

`def init(transform=None, *, translation=None, rotation=None, scale=None, mat3x3=None, from_parent=False)`

Create a new instance of the Transform3D archetype.

PARAMETER	DESCRIPTION
`transform`	Transform using an existing Transform3D datatype object. If not provided, none of the other named parameters must be set. TYPE: `Transform3DLike \| None` DEFAULT: `None`
`translation`	3D translation vector, applied last. Not compatible with `transform`. TYPE: `Vec3DLike \| None` DEFAULT: `None`
`rotation`	3D rotation, applied second. Not compatible with `transform` and `mat3x3` parameters. TYPE: `Rotation3DLike \| None` DEFAULT: `None`
`scale`	3D scale, applied last. Not compatible with `transform` and `mat3x3` parameters. TYPE: `Scale3DLike \| None` DEFAULT: `None`
`mat3x3`	3x3 matrix representing scale and rotation, applied after translation. Not compatible with `rotation` and `scale` parameters. TODO(#3559): Support 4x4 and 4x3 matrices. TYPE: `Mat3x3Like \| None` DEFAULT: `None`
`from_parent`	If true, the transform maps from the parent space to the space where the transform was logged. Otherwise, the transform maps from the space to its parent. TYPE: `bool` DEFAULT: `False`

`class ViewCoordinates`

Bases: ViewCoordinatesExt, Archetype

Archetype: How we interpret the coordinate system of an entity/space.

For instance: What is "up"? What does the Z axis mean? Is this right-handed or left-handed?

The three coordinates are always ordered as [x, y, z].

For example [Right, Down, Forward] means that the X axis points to the right, the Y axis points down, and the Z axis points forward.

Example

View coordinates for adjusting the eye camera:

import rerun as rr

rr.init("rerun_example_view_coordinates", spawn=True)

rr.log("world", rr.ViewCoordinates.RIGHT_HAND_Z_UP, timeless=True)  # Set an up-axis
rr.log(
    "world/xyz",
    rr.Arrows3D(
        vectors=[[1, 0, 0], [0, 1, 0], [0, 0, 1]],
        colors=[[255, 0, 0], [0, 255, 0], [0, 0, 255]],
    ),
)

`def init(xyz)`

Create a new instance of the ViewCoordinates archetype.

Archetypes

rerun.archetypes

class AnnotationContext

Example

Segmentation:

def __init__(context)

class Arrows3D

Example

Simple batch of 3D Arrows:

def __init__(*, vectors, origins=None, radii=None, colors=None, labels=None, class_ids=None, instance_keys=None)

class Asset3D

Example

Simple 3D asset:

def __init__(*, path=None, contents=None, media_type=None, transform=None)

class BarChart

Example

Simple bar chart:

def __init__(values)

class Boxes2D

Example

Simple 2D boxes:

def __init__(*, sizes=None, mins=None, half_sizes=None, centers=None, array=None, array_format=None, radii=None, colors=None, labels=None, draw_order=None, class_ids=None, instance_keys=None)

class Boxes3D

Example

Batch of 3D boxes:

def __init__(*, sizes=None, mins=None, half_sizes=None, centers=None, rotations=None, colors=None, radii=None, labels=None, class_ids=None, instance_keys=None)

class Clear

Example

Flat:

def __init__(*, recursive)

def flat() staticmethod

def recursive() staticmethod

class DepthImage

Example

Depth to 3D example:

def __init__(data, *, meter=None, draw_order=None)

class DisconnectedSpace

Example

Disconnected Space:

def __init__(is_disconnected=True)

class Image

Example

image_simple:

def __init__(data, *, draw_order=None)

def compress(*, jpeg_quality=95)

class LineStrips2D

Example

line_strip2d_batch:

def __init__(strips, *, radii=None, colors=None, labels=None, draw_order=None, class_ids=None, instance_keys=None)

class LineStrips3D

Example

Many strips:

def __init__(strips, *, radii=None, colors=None, labels=None, class_ids=None, instance_keys=None)

class Mesh3D

Example

Simple indexed 3D mesh:

def __init__(*, vertex_positions, indices=None, mesh_properties=None, vertex_normals=None, vertex_colors=None, mesh_material=None, class_ids=None, instance_keys=None)

class Pinhole

Example

Simple Pinhole Camera:

def __init__(*, image_from_camera=None, resolution=None, camera_xyz=None, width=None, height=None, focal_length=None, principal_point=None)

class Points2D

Example

Randomly distributed 2D points with varying color and radius:

def __init__(positions, *, radii=None, colors=None, labels=None, draw_order=None, class_ids=None, keypoint_ids=None, instance_keys=None)

class Points3D

Example

Randomly distributed 3D points with varying color and radius:

def __init__(positions, *, radii=None, colors=None, labels=None, class_ids=None, keypoint_ids=None, instance_keys=None)

class SegmentationImage

Example

Simple segmentation image:

def __init__(data, *, draw_order=None)

class Tensor

Example

Simple Tensor:

def __init__(data=None, *, dim_names=None)

class TextDocument

Example

Markdown text document:

`rerun.archetypes`

`class AnnotationContext`

`def init(context)`

`class Arrows3D`

`def init(*, vectors, origins=None, radii=None, colors=None, labels=None, class_ids=None, instance_keys=None)`

`class Asset3D`

`def init(*, path=None, contents=None, media_type=None, transform=None)`

`class BarChart`

`def init(values)`

`class Boxes2D`

`def init(*, sizes=None, mins=None, half_sizes=None, centers=None, array=None, array_format=None, radii=None, colors=None, labels=None, draw_order=None, class_ids=None, instance_keys=None)`

`class Boxes3D`

`def init(*, sizes=None, mins=None, half_sizes=None, centers=None, rotations=None, colors=None, radii=None, labels=None, class_ids=None, instance_keys=None)`

`class Clear`

`def init(*, recursive)`

`def flat()` `staticmethod`

`def recursive()` `staticmethod`

`class DepthImage`

`def init(data, *, meter=None, draw_order=None)`

`class DisconnectedSpace`

`def init(is_disconnected=True)`

`class Image`

`image_simple`:

`def init(data, *, draw_order=None)`

`def compress(*, jpeg_quality=95)`

`class LineStrips2D`

`line_strip2d_batch`:

`def init(strips, *, radii=None, colors=None, labels=None, draw_order=None, class_ids=None, instance_keys=None)`

`class LineStrips3D`

`def init(strips, *, radii=None, colors=None, labels=None, class_ids=None, instance_keys=None)`

`class Mesh3D`

`def init(*, vertex_positions, indices=None, mesh_properties=None, vertex_normals=None, vertex_colors=None, mesh_material=None, class_ids=None, instance_keys=None)`

`class Pinhole`

`def init(*, image_from_camera=None, resolution=None, camera_xyz=None, width=None, height=None, focal_length=None, principal_point=None)`

`class Points2D`

`def init(positions, *, radii=None, colors=None, labels=None, draw_order=None, class_ids=None, keypoint_ids=None, instance_keys=None)`

`class Points3D`

`def init(positions, *, radii=None, colors=None, labels=None, class_ids=None, keypoint_ids=None, instance_keys=None)`

`class SegmentationImage`

`def init(data, *, draw_order=None)`

`class Tensor`

`def init(data=None, *, dim_names=None)`

`class TextDocument`

`def init(text, *, media_type=None)`

`class TextLog`

`text_log_integration`:

`def init(text, *, level=None, color=None)`

`class TimeSeriesScalar`

`def init(scalar, *, radius=None, color=None, label=None, scattered=None)`

`class Transform3D`

`def init(transform=None, *, translation=None, rotation=None, scale=None, mat3x3=None, from_parent=False)`

`class ViewCoordinates`

`def init(xyz)`