Archetypes
rerun.archetypes
class AnnotationContext
Bases: Archetype
Archetype: The annotation context provides additional information on how to display entities.
Entities can use components.ClassIds and components.KeypointIds to provide annotations, and
the labels and colors will be looked up in the appropriate
annotation context. We use the first annotation context we find in the
path-hierarchy when searching up through the ancestors of a given entity
path.
See also datatypes.ClassDescription.
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))]), static=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:
|
class Arrows2D
Bases: Arrows2DExt, Archetype
Archetype: 2D arrows with optional colors, radii, labels, etc.
Example
Simple batch of 2D arrows:
import rerun as rr
rr.init("rerun_example_arrow2d", spawn=True)
rr.log(
"arrows",
rr.Arrows2D(
origins=[[0.25, 0.0], [0.25, 0.0], [-0.1, -0.1]],
vectors=[[1.0, 0.0], [0.0, -1.0], [-0.7, 0.7]],
colors=[[255, 0, 0], [0, 255, 0], [127, 0, 255]],
labels=["right", "up", "left-down"],
radii=0.025,
),
)
def __init__(*, vectors, origins=None, radii=None, colors=None, labels=None, show_labels=None, draw_order=None, class_ids=None)
Create a new instance of the Arrows2D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
vectors
|
All the vectors for each arrow in the batch.
TYPE:
|
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:
|
radii
|
Optional radii for the arrows. The shaft is rendered as a line with
TYPE:
|
colors
|
Optional colors for the points.
TYPE:
|
labels
|
Optional text labels for the arrows.
TYPE:
|
show_labels
|
Optional choice of whether the text labels should be shown by default.
TYPE:
|
draw_order
|
An optional floating point value that specifies the 2D drawing order of the arrows. Objects with higher values are drawn on top of those with lower values.
TYPE:
|
class_ids
|
Optional class Ids for the points. The class ID provides colors and labels if not specified explicitly.
TYPE:
|
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, show_labels=None, class_ids=None)
Create a new instance of the Arrows3D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
vectors
|
All the vectors for each arrow in the batch.
TYPE:
|
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:
|
radii
|
Optional radii for the arrows. The shaft is rendered as a line with
TYPE:
|
colors
|
Optional colors for the points.
TYPE:
|
labels
|
Optional text labels for the arrows.
TYPE:
|
show_labels
|
Optional choice of whether the text labels should be shown by default.
TYPE:
|
class_ids
|
Optional class Ids for the points. The class ID provides colors and labels if not specified explicitly.
TYPE:
|
class Asset3D
Bases: Asset3DExt, Archetype
Archetype: A prepacked 3D asset (.gltf, .glb, .obj, .stl, etc.).
See also archetypes.Mesh3D.
If there are multiple archetypes.InstancePoses3D instances logged to the same entity as a mesh,
an instance of the mesh will be drawn for each transform.
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|stl]>")
sys.exit(1)
rr.init("rerun_example_asset3d", spawn=True)
rr.log("world", rr.ViewCoordinates.RIGHT_HAND_Z_UP, static=True) # Set an up-axis
rr.log("world/asset", rr.Asset3D(path=sys.argv[1]))
def __init__(*, path=None, contents=None, media_type=None, albedo_factor=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
|
The contents of the file. Can be a BufferedReader, BytesIO, or
bytes. Mutually exclusive with
TYPE:
|
media_type
|
The Media Type of the asset. For instance:
* If omitted, it will be guessed from the
TYPE:
|
albedo_factor
|
Optional color multiplier for the whole mesh
TYPE:
|
class AssetVideo
Bases: AssetVideoExt, Archetype
Archetype: A video binary.
Only MP4 containers with AV1 are generally supported, though the web viewer supports more video codecs, depending on browser.
See https://rerun.io/docs/reference/video for details of what is and isn't supported.
In order to display a video, you also need to log a archetypes.VideoFrameReference for each frame.
Examples:
Video with automatically determined frames:
# TODO(#7298): ⚠️ Video is currently only supported in the Rerun web viewer.
import sys
import rerun as rr
if len(sys.argv) < 2:
# TODO(#7354): Only mp4 is supported for now.
print(f"Usage: {sys.argv[0]} <path_to_video.[mp4]>")
sys.exit(1)
rr.init("rerun_example_asset_video_auto_frames", spawn=True)
# Log video asset which is referred to by frame references.
video_asset = rr.AssetVideo(path=sys.argv[1])
rr.log("video", video_asset, static=True)
# Send automatically determined video frame timestamps.
frame_timestamps_ns = video_asset.read_frame_timestamps_ns()
rr.send_columns(
"video",
# Note timeline values don't have to be the same as the video timestamps.
times=[rr.TimeNanosColumn("video_time", frame_timestamps_ns)],
components=[rr.VideoFrameReference.indicator(), rr.components.VideoTimestamp.nanoseconds(frame_timestamps_ns)],
)
Demonstrates manual use of video frame references:
# TODO(#7298): ⚠️ Video is currently only supported in the Rerun web viewer.
import sys
import rerun as rr
import rerun.blueprint as rrb
if len(sys.argv) < 2:
# TODO(#7354): Only mp4 is supported for now.
print(f"Usage: {sys.argv[0]} <path_to_video.[mp4]>")
sys.exit(1)
rr.init("rerun_example_asset_video_manual_frames", spawn=True)
# Log video asset which is referred to by frame references.
rr.log("video_asset", rr.AssetVideo(path=sys.argv[1]), static=True)
# Create two entities, showing the same video frozen at different times.
rr.log(
"frame_1s",
rr.VideoFrameReference(seconds=1.0, video_reference="video_asset"),
)
rr.log(
"frame_2s",
rr.VideoFrameReference(seconds=2.0, video_reference="video_asset"),
)
# Send blueprint that shows two 2D views next to each other.
rr.send_blueprint(rrb.Horizontal(rrb.Spatial2DView(origin="frame_1s"), rrb.Spatial2DView(origin="frame_2s")))
def __init__(*, path=None, contents=None, media_type=None)
Create a new instance of the AssetVideo archetype.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
A path to an file stored on the local filesystem. Mutually
exclusive with |
contents
|
The contents of the file. Can be a BufferedReader, BytesIO, or
bytes. Mutually exclusive with
TYPE:
|
media_type
|
The Media Type of the asset. For instance:
* If omitted, it will be guessed from the
TYPE:
|
def read_frame_timestamps_ns()
Determines the presentation timestamps of all frames inside the video.
Throws a runtime exception if the video cannot be read.
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, *, color=None)
Create a new instance of the BarChart archetype.
| PARAMETER | DESCRIPTION |
|---|---|
values
|
The values. Should always be a 1-dimensional tensor (i.e. a vector).
TYPE:
|
color
|
The color of the bar chart
TYPE:
|
class Boxes2D
Bases: Boxes2DExt, Archetype
Archetype: 2D boxes with half-extents and optional center, 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]))
def __init__(*, sizes=None, mins=None, half_sizes=None, centers=None, array=None, array_format=None, radii=None, colors=None, labels=None, show_labels=None, draw_order=None, class_ids=None)
Create a new instance of the Boxes2D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
sizes
|
Full extents in x/y.
Incompatible with
TYPE:
|
half_sizes
|
All half-extents that make up the batch of boxes. Specify this instead of
TYPE:
|
mins
|
Minimum coordinates of the boxes. Specify this instead of
TYPE:
|
array
|
An array of boxes in the format specified by
TYPE:
|
array_format
|
How to interpret the data in
TYPE:
|
centers
|
Optional center positions of the boxes.
TYPE:
|
colors
|
Optional colors for the boxes.
TYPE:
|
radii
|
Optional radii for the lines that make up the boxes.
TYPE:
|
labels
|
Optional text labels for the boxes.
TYPE:
|
show_labels
|
Optional choice of whether the text labels should be shown by default.
TYPE:
|
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:
|
class_ids
|
Optional The class ID provides colors and labels if not specified explicitly.
TYPE:
|
class Boxes3D
Bases: Boxes3DExt, Archetype
Archetype: 3D boxes with half-extents and optional center, rotations, colors etc.
Note that orienting and placing the box is handled via [archetypes.InstancePoses3D].
Some of its component are repeated here for convenience.
If there's more instance poses than half sizes, the last half size will be repeated for the remaining poses.
Example
Batch of 3D boxes:
import rerun as rr
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]],
quaternions=[
rr.Quaternion.identity(),
rr.Quaternion(xyzw=[0.0, 0.0, 0.382683, 0.923880]), # 45 degrees around Z
],
radii=0.025,
colors=[(255, 0, 0), (0, 255, 0), (0, 0, 255)],
fill_mode="solid",
labels=["red", "green", "blue"],
),
)
def __init__(*, sizes=None, mins=None, half_sizes=None, centers=None, rotation_axis_angles=None, quaternions=None, rotations=None, colors=None, radii=None, fill_mode=None, labels=None, show_labels=None, class_ids=None)
Create a new instance of the Boxes3D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
sizes
|
Full extents in x/y/z. Specify this instead of
TYPE:
|
half_sizes
|
All half-extents that make up the batch of boxes. Specify this instead of
TYPE:
|
mins
|
Minimum coordinates of the boxes. Specify this instead of Only valid when used together with either
TYPE:
|
centers
|
Optional center positions of the boxes. If not specified, the centers will be at (0, 0, 0).
Note that this uses a
TYPE:
|
rotation_axis_angles
|
Rotations via axis + angle. If no rotation is specified, the axes of the boxes align with the axes of the local coordinate system.
Note that this uses a
TYPE:
|
quaternions
|
Rotations via quaternion. If no rotation is specified, the axes of the boxes align with the axes of the local coordinate system.
Note that this uses a
TYPE:
|
rotations
|
Backwards compatible parameter for specifying rotations. Tries to infer the type of rotation from the input. Prefer using
TYPE:
|
colors
|
Optional colors for the boxes.
TYPE:
|
radii
|
Optional radii for the lines that make up the boxes.
TYPE:
|
fill_mode
|
Optionally choose whether the boxes are drawn with lines or solid.
TYPE:
|
labels
|
Optional text labels for the boxes.
TYPE:
|
show_labels
|
Optional choice of whether the text labels should be shown by default.
TYPE:
|
class_ids
|
Optional The class ID provides colors and labels if not specified explicitly.
TYPE:
|
class Capsules3D
Bases: Capsules3DExt, Archetype
Archetype: 3D capsules; cylinders with hemispherical caps.
Capsules are defined by two endpoints (the centers of their end cap spheres), which are located at (0, 0, 0) and (0, 0, length), that is, extending along the positive direction of the Z axis. Capsules in other orientations may be produced by applying a rotation to the entity or instances.
Example
Batch of capsules:
import rerun as rr
rr.init("rerun_example_capsule3d_batch", spawn=True)
rr.log(
"capsules",
rr.Capsules3D(
lengths=[0.0, 2.0, 4.0, 6.0, 8.0],
radii=[1.0, 0.5, 0.5, 0.5, 1.0],
colors=[
(255, 0, 0),
(188, 188, 0),
(0, 255, 0),
(0, 188, 188),
(0, 0, 255),
],
translations=[
(0.0, 0.0, 0.0),
(2.0, 0.0, 0.0),
(4.0, 0.0, 0.0),
(6.0, 0.0, 0.0),
(8.0, 0.0, 0.0),
],
rotation_axis_angles=[
rr.RotationAxisAngle(
[1.0, 0.0, 0.0],
rr.Angle(deg=float(i) * -22.5),
)
for i in range(0, 5)
],
),
)
def __init__(*, lengths=None, radii=None, translations=None, rotation_axis_angles=None, quaternions=None, colors=None, labels=None, show_labels=None, class_ids=None)
Create a new instance of the Capsules3D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
lengths
|
All lengths of the capsules.
TYPE:
|
radii
|
All radii of the capsules.
TYPE:
|
translations
|
Optional translations of the capsules. If not specified, one end of each capsule will be at (0, 0, 0).
TYPE:
|
rotation_axis_angles
|
Rotations via axis + angle. If no rotation is specified, the capsules align with the +Z axis of the local coordinate system.
Note that this uses a
TYPE:
|
quaternions
|
Rotations via quaternion. If no rotation is specified, the capsules align with the +Z axis of the local coordinate system.
Note that this uses a
TYPE:
|
colors
|
Optional colors for the capsules.
TYPE:
|
labels
|
Optional text labels for the capsules.
TYPE:
|
show_labels
|
Optional choice of whether the text labels should be shown by default.
TYPE:
|
class_ids
|
Optional The class ID provides colors and labels if not specified explicitly.
TYPE:
|
class Clear
Bases: ClearExt, Archetype
Archetype: Empties all the components of an entity.
The presence of a clear means that a latest-at query of components at a given path(s) will not return any components that were logged at those paths before the clear. Any logged components after the clear are unaffected by the clear.
This implies that a range query that includes time points that are before the clear, still returns all components at the given path(s). Meaning that in practice clears are ineffective when making use of visible time ranges. Scalar plots are an exception: they track clears and use them to represent holes in the data (i.e. discontinuous lines).
Example
Flat:
import rerun as rr
rr.init("rerun_example_clear", 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:
|
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, i.e. as captured by a depth camera.
Each pixel corresponds to a depth value in units specified by components.DepthMeter.
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_3d", 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, colormap="viridis"))
def __init__(image, *, meter=None, colormap=None, depth_range=None, point_fill_ratio=None, draw_order=None)
Create a new instance of the DepthImage archetype.
| PARAMETER | DESCRIPTION |
|---|---|
image
|
A numpy array or tensor with the depth image data.
Leading and trailing unit-dimensions are ignored, so that
TYPE:
|
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). Note that the only effect on 2D views is the physical depth values shown when hovering the image. In 3D views on the other hand, this affects where the points of the point cloud are placed.
TYPE:
|
colormap
|
Colormap to use for rendering the depth image. If not set, the depth image will be rendered using the Turbo colormap.
TYPE:
|
depth_range
|
The expected range of depth values. This is typically the expected range of valid values. Everything outside of the range is clamped to the range for the purpose of colormpaping. Note that point clouds generated from this image will still display all points, regardless of this range. If not specified, the range will be automatically be estimated from the data. Note that the Viewer may try to guess a wider range than the minimum/maximum of values in the contents of the depth image. E.g. if all values are positive, some bigger than 1.0 and all smaller than 255.0, the Viewer will guess that the data likely came from an 8bit image, thus assuming a range of 0-255.
TYPE:
|
point_fill_ratio
|
Scale the radii of the points in the point cloud generated from this image. A fill ratio of 1.0 (the default) means that each point is as big as to touch the center of its neighbor if it is at the same depth, leaving no gaps. A fill ratio of 0.5 means that each point touches the edge of its neighbor if it has the same depth. TODO(#6744): This applies only to 3D views!
TYPE:
|
draw_order
|
An optional floating point value that specifies the 2D drawing order, used only if the depth image is shown as a 2D image. Objects with higher values are drawn on top of those with lower values.
TYPE:
|
class DisconnectedSpace
Bases: DisconnectedSpaceExt, Archetype
Archetype: Spatially disconnect this entity from its parent.
Specifies that the entity path at which this is logged is spatially disconnected from its parent, making it impossible to transform the entity path into its parent's space and vice versa. It only applies to space views that work with spatial transformations, i.e. 2D & 3D space views. This is useful for specifying that a subgraph is independent of the rest of the scene.
Example
Disconnected space:
import rerun as rr
rr.init("rerun_example_disconnected_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
TYPE:
|
class Ellipsoids3D
Bases: Ellipsoids3DExt, Archetype
Archetype: 3D ellipsoids or spheres.
This archetype is for ellipsoids or spheres whose size is a key part of the data
(e.g. a bounding sphere).
For points whose radii are for the sake of visualization, use archetypes.Points3D instead.
Note that orienting and placing the ellipsoids/spheres is handled via [archetypes.InstancePoses3D].
Some of its component are repeated here for convenience.
If there's more instance poses than half sizes, the last half size will be repeated for the remaining poses.
def __init__(*, half_sizes=None, radii=None, centers=None, rotation_axis_angles=None, quaternions=None, colors=None, line_radii=None, fill_mode=None, labels=None, show_labels=None, class_ids=None)
Create a new instance of the Ellipsoids3D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
half_sizes
|
All half-extents that make up the batch of ellipsoids.
Specify this instead of
TYPE:
|
radii
|
All radii that make up this batch of spheres.
Specify this instead of
TYPE:
|
centers
|
Optional center positions of the ellipsoids.
TYPE:
|
rotation_axis_angles
|
Rotations via axis + angle. If no rotation is specified, the axes of the boxes align with the axes of the local coordinate system.
Note that this uses a
TYPE:
|
quaternions
|
Rotations via quaternion. If no rotation is specified, the axes of the boxes align with the axes of the local coordinate system.
Note that this uses a
TYPE:
|
colors
|
Optional colors for the ellipsoids.
TYPE:
|
line_radii
|
Optional radii for the lines that make up the ellipsoids.
TYPE:
|
fill_mode
|
Optionally choose whether the ellipsoids are drawn with lines or solid.
TYPE:
|
labels
|
Optional text labels for the ellipsoids.
TYPE:
|
show_labels
|
Optional choice of whether the text labels should be shown by default.
TYPE:
|
class_ids
|
Optional The class ID provides colors and labels if not specified explicitly.
TYPE:
|
class EncodedImage
Bases: EncodedImageExt, Archetype
Archetype: An image encoded as e.g. a JPEG or PNG.
Rerun also supports uncompressed images with the archetypes.Image.
For images that refer to video frames see archetypes.VideoFrameReference.
To compress an image, use rerun.Image.compress.
Example
encoded_image:
from pathlib import Path
import rerun as rr
image_file_path = Path(__file__).parent / "ferris.png"
rr.init("rerun_example_encoded_image", spawn=True)
rr.log("image", rr.EncodedImage(path=image_file_path))
def __init__(*, path=None, contents=None, media_type=None, opacity=None, draw_order=None)
Create a new instance of the EncodedImage archetype.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
A path to an file stored on the local filesystem. Mutually
exclusive with |
contents
|
The contents of the file. Can be a BufferedReader, BytesIO, or
bytes. Mutually exclusive with |
media_type
|
The Media Type of the asset. For instance:
* If omitted, it will be guessed from the
TYPE:
|
opacity
|
Opacity of the image, useful for layering several images. Defaults to 1.0 (fully opaque).
TYPE:
|
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:
|
class GeoLineStrings
Bases: GeoLineStringsExt, Archetype
Archetype: Geospatial line strings with positions expressed in EPSG:4326 altitude and longitude (North/East-positive degrees), and optional colors and radii.
Also known as "line strips" or "polylines".
Example
Log a geospatial line string:
import rerun as rr
rr.init("rerun_example_geo_line_strings", spawn=True)
rr.log(
"colorado",
rr.GeoLineStrings(
lat_lon=[
[41.0000, -109.0452],
[41.0000, -102.0415],
[36.9931, -102.0415],
[36.9931, -109.0452],
[41.0000, -109.0452],
],
radii=rr.Radius.ui_points(2.0),
colors=[0, 0, 255],
),
)
def __init__(*, lat_lon, radii=None, colors=None)
Create a new instance of the GeoLineStrings archetype.
| PARAMETER | DESCRIPTION |
|---|---|
lat_lon
|
The line strings, expressed in EPSG:4326 coordinates (North/East-positive degrees).
TYPE:
|
radii
|
Optional radii for the line strings.
TYPE:
|
colors
|
Optional colors for the linestrings. 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:
|
class GeoPoints
Bases: GeoPointsExt, Archetype
Archetype: Geospatial points with positions expressed in EPSG:4326 latitude and longitude (North/East-positive degrees), and optional colors and radii.
Example
Log a geospatial point:
import rerun as rr
rr.init("rerun_example_geo_points", spawn=True)
rr.log(
"rerun_hq",
rr.GeoPoints(
lat_lon=[59.319221, 18.075631],
radii=rr.Radius.ui_points(10.0),
colors=[255, 0, 0],
),
)
def __init__(*, lat_lon, radii=None, colors=None)
Create a new instance of the GeoPoints archetype.
| PARAMETER | DESCRIPTION |
|---|---|
lat_lon
|
The EPSG:4326 coordinates for the points (North/East-positive degrees).
TYPE:
|
radii
|
Optional radii for the points, effectively turning them into circles.
TYPE:
|
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:
|
class Image
Bases: ImageExt, Archetype
Archetype: A monochrome or color image.
See also archetypes.DepthImage and archetypes.SegmentationImage.
Rerun also supports compressed images (JPEG, PNG, …), using archetypes.EncodedImage.
For images that refer to video frames see archetypes.VideoFrameReference.
Compressing images or using video data instead can save a lot of bandwidth and memory.
The raw image data is stored as a single buffer of bytes in a components.Blob.
The meaning of these bytes is determined by the components.ImageFormat which specifies the resolution
and the pixel format (e.g. RGB, RGBA, …).
The order of dimensions in the underlying components.Blob follows the typical
row-major, interleaved-pixel image format.
Examples:
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", spawn=True)
rr.log("image", rr.Image(image))
Logging images with various formats:
import numpy as np
import rerun as rr
rr.init("rerun_example_image_formats", spawn=True)
# Simple gradient image, logged in different formats.
image = np.array([[[x, min(255, x + y), y] for x in range(0, 256)] for y in range(0, 256)], dtype=np.uint8)
rr.log("image_rgb", rr.Image(image))
rr.log("image_green_only", rr.Image(image[:, :, 1], color_model="l")) # Luminance only
rr.log("image_bgr", rr.Image(image[:, :, ::-1], color_model="bgr")) # BGR
# New image with Separate Y/U/V planes with 4:2:2 chroma downsampling
y = bytes([128 for y in range(0, 256) for x in range(0, 256)])
u = bytes([x * 2 for y in range(0, 256) for x in range(0, 128)]) # Half horizontal resolution for chroma.
v = bytes([y for y in range(0, 256) for x in range(0, 128)])
rr.log("image_yuv422", rr.Image(bytes=y + u + v, width=256, height=256, pixel_format=rr.PixelFormat.Y_U_V16_FullRange))
def __init__(image=None, color_model=None, *, pixel_format=None, datatype=None, bytes=None, width=None, height=None, opacity=None, draw_order=None)
Create a new image with a given format.
There are three ways to create an image:
* By specifying an image as an appropriately shaped ndarray with an appropriate color_model.
* By specifying bytes of an image with a pixel_format, together with width, height.
* By specifying bytes of an image with a datatype and color_model, together with width, height.
| PARAMETER | DESCRIPTION |
|---|---|
image
|
A numpy array or tensor with the image data.
Leading and trailing unit-dimensions are ignored, so that
TYPE:
|
color_model
|
L, RGB, RGBA, BGR, BGRA, etc, specifying how to interpret
TYPE:
|
pixel_format
|
NV12, YUV420, etc. For chroma-downsampling.
Requires
TYPE:
|
datatype
|
The datatype of the image data. If not specified, it is inferred from the
TYPE:
|
bytes
|
The raw bytes of an image specified by
TYPE:
|
width
|
The width of the image. Only requires for
TYPE:
|
height
|
The height of the image. Only requires for
TYPE:
|
opacity
|
Optional opacity of the image, in 0-1. Set to 0.5 for a translucent image.
TYPE:
|
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:
|
def compress(jpeg_quality=95)
Compress the given image as a JPEG.
JPEG compression works best for photographs. Only U8 RGB and grayscale 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 saves a lot of space, but is still visually very similar.
TYPE:
|
class InstancePoses3D
Bases: Archetype
Archetype: One or more transforms between the current entity and its parent. Unlike archetypes.Transform3D, it is not propagated in the transform hierarchy.
If both archetypes.InstancePoses3D and archetypes.Transform3D are present,
first the tree propagating archetypes.Transform3D is applied, then archetypes.InstancePoses3D.
From the point of view of the entity's coordinate system, all components are applied in the inverse order they are listed here. E.g. if both a translation and a max3x3 transform are present, the 3x3 matrix is applied first, followed by the translation.
Currently, many visualizers support only a single instance transform per entity.
Check archetype documentations for details - if not otherwise specified, only the first instance transform is applied.
Some visualizers like the mesh visualizer used for [archetype.Mesh3D],
will draw an object for every pose, a behavior also known as "instancing".
Example
Regular & instance transforms in tandem:
import numpy as np
import rerun as rr
rr.init("rerun_example_instance_pose3d_combined", spawn=True)
rr.set_time_sequence("frame", 0)
# Log a box and points further down in the hierarchy.
rr.log("world/box", rr.Boxes3D(half_sizes=[[1.0, 1.0, 1.0]]))
rr.log("world/box/points", rr.Points3D(np.vstack([xyz.ravel() for xyz in np.mgrid[3 * [slice(-10, 10, 10j)]]]).T))
for i in range(0, 180):
rr.set_time_sequence("frame", i)
# Log a regular transform which affects both the box and the points.
rr.log("world/box", rr.Transform3D(rotation_axis_angle=rr.RotationAxisAngle([0, 0, 1], angle=rr.Angle(deg=i * 2))))
# Log an instance pose which affects only the box.
rr.log("world/box", rr.InstancePoses3D(translations=[0, 0, abs(i * 0.1 - 5.0) - 5.0]))
def __init__(*, translations=None, rotation_axis_angles=None, quaternions=None, scales=None, mat3x3=None)
Create a new instance of the InstancePoses3D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
translations
|
Translation vectors.
TYPE:
|
rotation_axis_angles
|
Rotations via axis + angle.
TYPE:
|
quaternions
|
Rotations via quaternion.
TYPE:
|
scales
|
Scaling factors.
TYPE:
|
mat3x3
|
3x3 transformation matrices.
TYPE:
|
class LineStrips2D
Bases: Archetype
Archetype: 2D line strips with positions and optional colors, radii, labels, etc.
Examples:
line_strip2d_batch:
import rerun as rr
import rerun.blueprint as rrb
rr.init("rerun_example_line_strip2d_batch", 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"],
),
)
# Set view bounds:
rr.send_blueprint(rrb.Spatial2DView(visual_bounds=rrb.VisualBounds2D(x_range=[-1, 7], y_range=[-3, 6])))
Lines with scene & UI radius each:
import rerun as rr
rr.init("rerun_example_line_strip3d_ui_radius", spawn=True)
# A blue line with a scene unit radii of 0.01.
points = [[0, 0, 0], [0, 0, 1], [1, 0, 0], [1, 0, 1]]
rr.log(
"scene_unit_line",
rr.LineStrips3D(
[points],
# By default, radii are interpreted as world-space units.
radii=0.01,
colors=[0, 0, 255],
),
)
# A red line with a ui point radii of 5.
# UI points are independent of zooming in Views, but are sensitive to the application UI scaling.
# For 100% ui scaling, UI points are equal to pixels.
points = [[3, 0, 0], [3, 0, 1], [4, 0, 0], [4, 0, 1]]
rr.log(
"ui_points_line",
rr.LineStrips3D(
[points],
# rr.Radius.ui_points produces radii that the viewer interprets as given in ui points.
radii=rr.Radius.ui_points(5.0),
colors=[255, 0, 0],
),
)
def __init__(strips, *, radii=None, colors=None, labels=None, show_labels=None, draw_order=None, class_ids=None)
Create a new instance of the LineStrips2D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
strips
|
All the actual 2D line strips that make up the batch.
TYPE:
|
radii
|
Optional radii for the line strips.
TYPE:
|
colors
|
Optional colors for the line strips.
TYPE:
|
labels
|
Optional text labels for the line strips. If there's a single label present, it will be placed at the center of the entity. Otherwise, each instance will have its own label.
TYPE:
|
show_labels
|
Optional choice of whether the text labels should be shown by default.
TYPE:
|
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:
|
class_ids
|
Optional The
TYPE:
|
class LineStrips3D
Bases: Archetype
Archetype: 3D line strips with positions and optional colors, radii, labels, etc.
Examples:
Many strips:
import rerun as rr
rr.init("rerun_example_line_strip3d_batch", 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"],
),
)
Lines with scene & UI radius each:
import rerun as rr
rr.init("rerun_example_line_strip3d_ui_radius", spawn=True)
# A blue line with a scene unit radii of 0.01.
points = [[0, 0, 0], [0, 0, 1], [1, 0, 0], [1, 0, 1]]
rr.log(
"scene_unit_line",
rr.LineStrips3D(
[points],
# By default, radii are interpreted as world-space units.
radii=0.01,
colors=[0, 0, 255],
),
)
# A red line with a ui point radii of 5.
# UI points are independent of zooming in Views, but are sensitive to the application UI scaling.
# For 100% ui scaling, UI points are equal to pixels.
points = [[3, 0, 0], [3, 0, 1], [4, 0, 0], [4, 0, 1]]
rr.log(
"ui_points_line",
rr.LineStrips3D(
[points],
# rr.Radius.ui_points produces radii that the viewer interprets as given in ui points.
radii=rr.Radius.ui_points(5.0),
colors=[255, 0, 0],
),
)
def __init__(strips, *, radii=None, colors=None, labels=None, show_labels=None, class_ids=None)
Create a new instance of the LineStrips3D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
strips
|
All the actual 3D line strips that make up the batch.
TYPE:
|
radii
|
Optional radii for the line strips.
TYPE:
|
colors
|
Optional colors for the line strips.
TYPE:
|
labels
|
Optional text labels for the line strips. If there's a single label present, it will be placed at the center of the entity. Otherwise, each instance will have its own label.
TYPE:
|
show_labels
|
Optional choice of whether the text labels should be shown by default.
TYPE:
|
class_ids
|
Optional The
TYPE:
|
class Mesh3D
Bases: Mesh3DExt, Archetype
Archetype: A 3D triangle mesh as specified by its per-mesh and per-vertex properties.
See also archetypes.Asset3D.
If there are multiple archetypes.InstancePoses3D instances logged to the same entity as a mesh,
an instance of the mesh will be drawn for each transform.
Examples:
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]],
triangle_indices=[2, 1, 0],
),
)
3D mesh with instancing:
import rerun as rr
rr.init("rerun_example_mesh3d_instancing", spawn=True)
rr.set_time_sequence("frame", 0)
rr.log(
"shape",
rr.Mesh3D(
vertex_positions=[[1, 1, 1], [-1, -1, 1], [-1, 1, -1], [1, -1, -1]],
triangle_indices=[[0, 1, 2], [0, 1, 3], [0, 2, 3], [1, 2, 3]],
vertex_colors=[[255, 0, 0], [0, 255, 0], [0, 0, 255], [255, 255, 0]],
),
)
# This box will not be affected by its parent's instance poses!
rr.log(
"shape/box",
rr.Boxes3D(half_sizes=[[5.0, 5.0, 5.0]]),
)
for i in range(0, 100):
rr.set_time_sequence("frame", i)
rr.log(
"shape",
rr.InstancePoses3D(
translations=[[2, 0, 0], [0, 2, 0], [0, -2, 0], [-2, 0, 0]],
rotation_axis_angles=rr.RotationAxisAngle([0, 0, 1], rr.Angle(deg=i * 2)),
),
)
def __init__(*, vertex_positions, triangle_indices=None, vertex_normals=None, vertex_colors=None, vertex_texcoords=None, albedo_texture=None, albedo_factor=None, class_ids=None)
Create a new instance of the Mesh3D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
vertex_positions
|
The positions of each vertex.
If no
TYPE:
|
triangle_indices
|
Optional indices for the triangles that make up the mesh.
TYPE:
|
vertex_normals
|
An optional normal for each vertex.
If specified, this must have as many elements as
TYPE:
|
vertex_texcoords
|
An optional texture coordinate for each vertex.
If specified, this must have as many elements as
TYPE:
|
vertex_colors
|
An optional color for each vertex.
TYPE:
|
albedo_factor
|
Optional color multiplier for the whole mesh
TYPE:
|
albedo_texture
|
Optional albedo texture. Used with
TYPE:
|
class_ids
|
Optional class Ids for the vertices. The class ID provides colors and labels if not specified explicitly.
TYPE:
|
class Pinhole
Bases: PinholeExt, Archetype
Archetype: Camera perspective projection (a.k.a. intrinsics).
Examples:
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))
Perspective pinhole camera:
import rerun as rr
rr.init("rerun_example_pinhole_perspective", spawn=True)
rr.log(
"world/cam",
rr.Pinhole(fov_y=0.7853982, aspect_ratio=1.7777778, camera_xyz=rr.ViewCoordinates.RUB, image_plane_distance=0.1),
)
rr.log("world/points", rr.Points3D([(0.0, 0.0, -0.5), (0.1, 0.1, -0.5), (-0.1, -0.1, -0.5)], radii=0.025))
def __init__(*, image_from_camera=None, resolution=None, camera_xyz=None, width=None, height=None, focal_length=None, principal_point=None, fov_y=None, aspect_ratio=None, image_plane_distance=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
TYPE:
|
resolution
|
Pixel resolution (usually integers) of child image space. Width and height.
TYPE:
|
camera_xyz
|
Sets the view coordinates for the camera. All common values are available as constants on the The default is The camera frustum will point whichever axis is set to The frustum's "up" direction will be whichever axis is set to The frustum's "right" direction will be whichever axis is set to Other common formats are NOTE: setting this to something else than The pinhole matrix (the
TYPE:
|
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. |
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:
|
width
|
Width of the image in pixels. |
height
|
Height of the image in pixels. |
fov_y
|
Vertical field of view in radians.
TYPE:
|
aspect_ratio
|
Aspect ratio (width/height).
TYPE:
|
image_plane_distance
|
The distance from the camera origin to the image plane when the projection is shown in a 3D viewer. This is only used for visualization purposes, and does not affect the projection itself.
TYPE:
|
class Points2D
Bases: Points2DExt, Archetype
Archetype: A 2D point cloud with positions and optional colors, radii, labels, etc.
Examples:
Randomly distributed 2D points with varying color and radius:
import rerun as rr
import rerun.blueprint as rrb
from numpy.random import default_rng
rr.init("rerun_example_points2d_random", 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))
# Set view bounds:
rr.send_blueprint(rrb.Spatial2DView(visual_bounds=rrb.VisualBounds2D(x_range=[-4, 4], y_range=[-4, 4])))
Log points with radii given in UI points:
import rerun as rr
import rerun.blueprint as rrb
rr.init("rerun_example_points2d_ui_radius", spawn=True)
# Two blue points with scene unit radii of 0.1 and 0.3.
rr.log(
"scene_units",
rr.Points2D(
[[0, 0], [0, 1]],
# By default, radii are interpreted as world-space units.
radii=[0.1, 0.3],
colors=[0, 0, 255],
),
)
# Two red points with ui point radii of 40 and 60.
# UI points are independent of zooming in Views, but are sensitive to the application UI scaling.
# For 100% ui scaling, UI points are equal to pixels.
rr.log(
"ui_points",
rr.Points2D(
[[1, 0], [1, 1]],
# rr.Radius.ui_points produces radii that the viewer interprets as given in ui points.
radii=rr.Radius.ui_points([40.0, 60.0]),
colors=[255, 0, 0],
),
)
# Set view bounds:
rr.send_blueprint(rrb.Spatial2DView(visual_bounds=rrb.VisualBounds2D(x_range=[-1, 2], y_range=[-1, 2])))
def __init__(positions, *, radii=None, colors=None, labels=None, show_labels=None, draw_order=None, class_ids=None, keypoint_ids=None)
Create a new instance of the Points2D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
positions
|
All the 2D positions at which the point cloud shows points.
TYPE:
|
radii
|
Optional radii for the points, effectively turning them into circles.
TYPE:
|
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:
|
labels
|
Optional text labels for the points.
TYPE:
|
show_labels
|
Optional choice of whether the text labels should be shown by default.
TYPE:
|
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:
|
class_ids
|
Optional class Ids for the points. The class ID provides colors and labels if not specified explicitly.
TYPE:
|
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
TYPE:
|
class Points3D
Bases: Points3DExt, Archetype
Archetype: A 3D point cloud with positions and optional colors, radii, labels, etc.
Examples:
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))
Log points with radii given in UI points:
import rerun as rr
rr.init("rerun_example_points3d_ui_radius", spawn=True)
# Two blue points with scene unit radii of 0.1 and 0.3.
rr.log(
"scene_units",
rr.Points3D(
[[0, 1, 0], [1, 1, 1]],
# By default, radii are interpreted as world-space units.
radii=[0.1, 0.3],
colors=[0, 0, 255],
),
)
# Two red points with ui point radii of 40 and 60.
# UI points are independent of zooming in Views, but are sensitive to the application UI scaling.
# For 100% ui scaling, UI points are equal to pixels.
rr.log(
"ui_points",
rr.Points3D(
[[0, 0, 0], [1, 0, 1]],
# rr.Radius.ui_points produces radii that the viewer interprets as given in ui points.
radii=rr.Radius.ui_points([40.0, 60.0]),
colors=[255, 0, 0],
),
)
Send several point clouds with varying point count over time in a single call:
from __future__ import annotations
import numpy as np
import rerun as rr
rr.init("rerun_example_send_columns_arrays", spawn=True)
# Prepare a point cloud that evolves over time 5 timesteps, changing the number of points in the process.
times = np.arange(10, 15, 1.0)
positions = [
[[1.0, 0.0, 1.0], [0.5, 0.5, 2.0]],
[[1.5, -0.5, 1.5], [1.0, 1.0, 2.5], [-0.5, 1.5, 1.0], [-1.5, 0.0, 2.0]],
[[2.0, 0.0, 2.0], [1.5, -1.5, 3.0], [0.0, -2.0, 2.5], [1.0, -1.0, 3.5]],
[[-2.0, 0.0, 2.0], [-1.5, 1.5, 3.0], [-1.0, 1.0, 3.5]],
[[1.0, -1.0, 1.0], [2.0, -2.0, 2.0], [3.0, -1.0, 3.0], [2.0, 0.0, 4.0]],
]
positions_arr = np.concatenate(positions)
# At each time stamp, all points in the cloud share the same but changing color.
colors = [0xFF0000FF, 0x00FF00FF, 0x0000FFFF, 0xFFFF00FF, 0x00FFFFFF]
rr.send_columns(
"points",
times=[rr.TimeSecondsColumn("time", times)],
components=[
rr.Points3D.indicator(),
rr.components.Position3DBatch(positions_arr).partition([len(row) for row in positions]),
rr.components.ColorBatch(colors),
],
)
def __init__(positions, *, radii=None, colors=None, labels=None, show_labels=None, class_ids=None, keypoint_ids=None)
Create a new instance of the Points3D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
positions
|
All the 3D positions at which the point cloud shows points.
TYPE:
|
radii
|
Optional radii for the points, effectively turning them into circles.
TYPE:
|
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:
|
labels
|
Optional text labels for the points.
TYPE:
|
show_labels
|
Optional choice of whether the text labels should be shown by default.
TYPE:
|
class_ids
|
Optional class Ids for the points. The class ID provides colors and labels if not specified explicitly.
TYPE:
|
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
TYPE:
|
class Scalar
Bases: Archetype
Archetype: A double-precision scalar, e.g. for use for time-series plots.
The current timeline value will be used for the time/X-axis, hence scalars cannot be static.
When used to produce a plot, this archetype is used to provide the data that
is referenced by archetypes.SeriesLine or archetypes.SeriesPoint. You can do
this by logging both archetypes to the same path, or alternatively configuring
the plot-specific archetypes through the blueprint.
Example
Simple line plot:
import math
import rerun as rr
rr.init("rerun_example_scalar", spawn=True)
# Log the data on a timeline called "step".
for step in range(0, 64):
rr.set_time_sequence("step", step)
rr.log("scalar", rr.Scalar(math.sin(step / 10.0)))
def __init__(scalar)
Create a new instance of the Scalar archetype.
| PARAMETER | DESCRIPTION |
|---|---|
scalar
|
The scalar value to log.
TYPE:
|
class SegmentationImage
Bases: SegmentationImageExt, Archetype
Archetype: An image made up of integer components.ClassIds.
Each pixel corresponds to a components.ClassId that will be mapped to a color based on annotation context.
In the case of floating point images, the label will be looked up based on rounding to the nearest integer value.
See also archetypes.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))]), static=True)
rr.log("image", rr.SegmentationImage(image))
class SeriesLine
Bases: Archetype
Archetype: Define the style properties for a line series in a chart.
This archetype only provides styling information and should be logged as static
when possible. The underlying data needs to be logged to the same entity-path using
archetypes.Scalar.
Example
Line series:
from math import cos, sin, tau
import rerun as rr
rr.init("rerun_example_series_line_style", spawn=True)
# Set up plot styling:
# They are logged as static as they don't change over time and apply to all timelines.
# Log two lines series under a shared root so that they show in the same plot by default.
rr.log("trig/sin", rr.SeriesLine(color=[255, 0, 0], name="sin(0.01t)", width=2), static=True)
rr.log("trig/cos", rr.SeriesLine(color=[0, 255, 0], name="cos(0.01t)", width=4), static=True)
# Log the data on a timeline called "step".
for t in range(0, int(tau * 2 * 100.0)):
rr.set_time_sequence("step", t)
rr.log("trig/sin", rr.Scalar(sin(float(t) / 100.0)))
rr.log("trig/cos", rr.Scalar(cos(float(t) / 100.0)))
def __init__(*, color=None, width=None, name=None, aggregation_policy=None)
Create a new instance of the SeriesLine archetype.
| PARAMETER | DESCRIPTION |
|---|---|
color
|
Color for the corresponding series.
TYPE:
|
width
|
Stroke width for the corresponding series.
TYPE:
|
name
|
Display name of the series. Used in the legend.
TYPE:
|
aggregation_policy
|
Configures the zoom-dependent scalar aggregation. This is done only if steps on the X axis go below a single pixel, i.e. a single pixel covers more than one tick worth of data. It can greatly improve performance (and readability) in such situations as it prevents overdraw.
TYPE:
|
class SeriesPoint
Bases: Archetype
Archetype: Define the style properties for a point series in a chart.
This archetype only provides styling information and should be logged as static
when possible. The underlying data needs to be logged to the same entity-path using
archetypes.Scalar.
Example
Point series:
from math import cos, sin, tau
import rerun as rr
rr.init("rerun_example_series_point_style", spawn=True)
# Set up plot styling:
# They are logged as static as they don't change over time and apply to all timelines.
# Log two point series under a shared root so that they show in the same plot by default.
rr.log(
"trig/sin",
rr.SeriesPoint(
color=[255, 0, 0],
name="sin(0.01t)",
marker="circle",
marker_size=4,
),
static=True,
)
rr.log(
"trig/cos",
rr.SeriesPoint(
color=[0, 255, 0],
name="cos(0.01t)",
marker="cross",
marker_size=2,
),
static=True,
)
# Log the data on a timeline called "step".
for t in range(0, int(tau * 2 * 10.0)):
rr.set_time_sequence("step", t)
rr.log("trig/sin", rr.Scalar(sin(float(t) / 10.0)))
rr.log("trig/cos", rr.Scalar(cos(float(t) / 10.0)))
def __init__(*, color=None, marker=None, name=None, marker_size=None)
Create a new instance of the SeriesPoint archetype.
| PARAMETER | DESCRIPTION |
|---|---|
color
|
Color for the corresponding series.
TYPE:
|
marker
|
What shape to use to represent the point
TYPE:
|
name
|
Display name of the series. Used in the legend.
TYPE:
|
marker_size
|
Size of the marker.
TYPE:
|
class Tensor
Bases: TensorExt, Archetype
Archetype: An N-dimensional array of numbers.
It's not currently possible to use send_columns with tensors since construction
of rerun.components.TensorDataBatch does not support more than a single element.
This will be addressed as part of https://github.com/rerun-io/rerun/issues/6832.
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", 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, value_range=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:
|
data
|
A TensorData object, or type that can be converted to a numpy array.
TYPE:
|
dim_names
|
The names of the tensor dimensions when generating the shape from an array. |
value_range
|
The range of values to use for colormapping. If not specified, the range will be estimated from the data.
TYPE:
|
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
'''.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:
|
media_type
|
The Media Type of the text. For instance:
* If omitted,
TYPE:
|
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:
|
level
|
The verbosity level of the message. This can be used to filter the log messages in the Rerun Viewer.
TYPE:
|
color
|
Optional color to use for the log line in the Rerun Viewer.
TYPE:
|
class Transform3D
Bases: Transform3DExt, Archetype
Archetype: A transform between two 3D spaces, i.e. a pose.
From the point of view of the entity's coordinate system, all components are applied in the inverse order they are listed here. E.g. if both a translation and a max3x3 transform are present, the 3x3 matrix is applied first, followed by the translation.
Whenever you log this archetype, it will write all components, even if you do not explicitly set them. This means that if you first log a transform with only a translation, and then log one with only a rotation, it will be resolved to a transform with only a rotation.
For transforms that affect only a single entity and do not propagate along the entity tree refer to archetypes.InstancePoses3D.
Examples:
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)
Transform hierarchy:
import numpy as np
import rerun as rr
import rerun.blueprint as rrb
rr.init("rerun_example_transform3d_hierarchy", spawn=True)
# One space with the sun in the center, and another one with the planet.
rr.send_blueprint(
rrb.Horizontal(rrb.Spatial3DView(origin="sun"), rrb.Spatial3DView(origin="sun/planet", contents="sun/**"))
)
rr.set_time_seconds("sim_time", 0)
# Planetary motion is typically in the XY plane.
rr.log("/", rr.ViewCoordinates.RIGHT_HAND_Z_UP, static=True)
# Setup points, all are in the center of their own space:
# TODO(#1361): Should use spheres instead of points.
rr.log("sun", rr.Points3D([0.0, 0.0, 0.0], radii=1.0, colors=[255, 200, 10]))
rr.log("sun/planet", rr.Points3D([0.0, 0.0, 0.0], radii=0.4, colors=[40, 80, 200]))
rr.log("sun/planet/moon", rr.Points3D([0.0, 0.0, 0.0], radii=0.15, colors=[180, 180, 180]))
# Draw fixed paths where the planet & moon move.
d_planet = 6.0
d_moon = 3.0
angles = np.arange(0.0, 1.01, 0.01) * np.pi * 2
circle = np.array([np.sin(angles), np.cos(angles), angles * 0.0]).transpose()
rr.log("sun/planet_path", rr.LineStrips3D(circle * d_planet))
rr.log("sun/planet/moon_path", rr.LineStrips3D(circle * d_moon))
# Movement via transforms.
for i in range(0, 6 * 120):
time = i / 120.0
rr.set_time_seconds("sim_time", time)
r_moon = time * 5.0
r_planet = time * 2.0
rr.log(
"sun/planet",
rr.Transform3D(
translation=[np.sin(r_planet) * d_planet, np.cos(r_planet) * d_planet, 0.0],
rotation=rr.RotationAxisAngle(axis=(1, 0, 0), degrees=20),
),
)
rr.log(
"sun/planet/moon",
rr.Transform3D(
translation=[np.cos(r_moon) * d_moon, np.sin(r_moon) * d_moon, 0.0],
from_parent=True,
),
)
def __init__(*, translation=None, rotation=None, rotation_axis_angle=None, quaternion=None, scale=None, mat3x3=None, from_parent=None, relation=None, axis_length=None)
Create a new instance of the Transform3D archetype.
| PARAMETER | DESCRIPTION |
|---|---|
translation
|
3D translation vector.
TYPE:
|
rotation
|
3D rotation, either a quaternion or an axis-angle.
Mutually exclusive with
TYPE:
|
rotation_axis_angle
|
Axis-angle representing rotation. Mutually exclusive with
TYPE:
|
quaternion
|
Quaternion representing rotation. Mutually exclusive with
TYPE:
|
scale
|
3D scale.
TYPE:
|
mat3x3
|
3x3 matrix representing scale and rotation, applied after translation.
Not compatible with
TYPE:
|
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.
Deprecated in favor of Mutually exclusive with
TYPE:
|
relation
|
Allows to explicitly specify the transform's relationship with the parent entity. Otherwise, the transform maps from the space to its parent. Mutually exclusive with
TYPE:
|
axis_length
|
Visual length of the 3 axes. The length is interpreted in the local coordinate system of the transform. If the transform is scaled, the axes will be scaled accordingly.
TYPE:
|
class VideoFrameReference
Bases: VideoFrameReferenceExt, Archetype
Archetype: References a single video frame.
Used to display individual video frames from a archetypes.AssetVideo.
To show an entire video, a video frame reference for each frame of the video should be logged.
See https://rerun.io/docs/reference/video for details of what is and isn't supported.
Examples:
Video with automatically determined frames:
# TODO(#7298): ⚠️ Video is currently only supported in the Rerun web viewer.
import sys
import rerun as rr
if len(sys.argv) < 2:
# TODO(#7354): Only mp4 is supported for now.
print(f"Usage: {sys.argv[0]} <path_to_video.[mp4]>")
sys.exit(1)
rr.init("rerun_example_asset_video_auto_frames", spawn=True)
# Log video asset which is referred to by frame references.
video_asset = rr.AssetVideo(path=sys.argv[1])
rr.log("video", video_asset, static=True)
# Send automatically determined video frame timestamps.
frame_timestamps_ns = video_asset.read_frame_timestamps_ns()
rr.send_columns(
"video",
# Note timeline values don't have to be the same as the video timestamps.
times=[rr.TimeNanosColumn("video_time", frame_timestamps_ns)],
components=[rr.VideoFrameReference.indicator(), rr.components.VideoTimestamp.nanoseconds(frame_timestamps_ns)],
)
Demonstrates manual use of video frame references:
# TODO(#7298): ⚠️ Video is currently only supported in the Rerun web viewer.
import sys
import rerun as rr
import rerun.blueprint as rrb
if len(sys.argv) < 2:
# TODO(#7354): Only mp4 is supported for now.
print(f"Usage: {sys.argv[0]} <path_to_video.[mp4]>")
sys.exit(1)
rr.init("rerun_example_asset_video_manual_frames", spawn=True)
# Log video asset which is referred to by frame references.
rr.log("video_asset", rr.AssetVideo(path=sys.argv[1]), static=True)
# Create two entities, showing the same video frozen at different times.
rr.log(
"frame_1s",
rr.VideoFrameReference(seconds=1.0, video_reference="video_asset"),
)
rr.log(
"frame_2s",
rr.VideoFrameReference(seconds=2.0, video_reference="video_asset"),
)
# Send blueprint that shows two 2D views next to each other.
rr.send_blueprint(rrb.Horizontal(rrb.Spatial2DView(origin="frame_1s"), rrb.Spatial2DView(origin="frame_2s")))
def __init__(timestamp=None, *, seconds=None, nanoseconds=None, video_reference=None)
Create a new instance of the VideoFrameReference archetype.
| PARAMETER | DESCRIPTION |
|---|---|
timestamp
|
References the closest video frame to this timestamp. Note that this uses the closest video frame instead of the latest at this timestamp in order to be more forgiving of rounding errors for inprecise timestamp types. Mutually exclusive with
TYPE:
|
seconds
|
Sets the timestamp to the given number of seconds. Mutually exclusive with
TYPE:
|
nanoseconds
|
Sets the timestamp to the given number of nanoseconds. Mutually exclusive with
TYPE:
|
video_reference
|
Optional reference to an entity with a If none is specified, the video is assumed to be at the same entity. Note that blueprint overrides on the referenced video will be ignored regardless, as this is always interpreted as a reference to the data store. For a series of video frame references, it is recommended to specify this path only once at the beginning of the series and then rely on latest-at query semantics to keep the video reference active.
TYPE:
|
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?
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.
Make sure that this archetype is logged at or above the origin entity path of your 3D views.
⚠ Rerun does not yet support left-handed coordinate systems.
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, static=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.
| PARAMETER | DESCRIPTION |
|---|---|
xyz
|
The directions of the [x, y, z] axes.
TYPE:
|