Skip to content

Transforms

Methods for logging transforms on entity paths.

Learn more about transforms in the manual

def rerun.log_transform3d(entity_path, transform, *, from_parent=False, timeless=False, recording=None)

Log an (affine) 3D transform between this entity and the parent.

If from_parent is set to True, the transformation is from the parent to the space of the entity_path, otherwise it is from the child to the parent.

Note that new transforms replace previous, i.e. if you call this function several times on the same path, each new transform will replace the previous one and does not combine with it.

Examples:

# Log translation only.
rr.log_transform3d("transform_test/translation", rr.Translation3D((2, 1, 3)))

# Log scale along the x axis only.
rr.log_transform3d("transform_test/x_scaled", rr.Scale3D((3, 1, 1)))

# Log a rotation around the z axis.
rr.log_transform3d("transform_test/z_rotated_object", rr.RotationAxisAngle((0, 0, 1), degrees=20))

# Log scale followed by translation along the Y-axis.
rr.log_transform3d(
    "transform_test/scaled_and_translated_object", rr.TranslationRotationScale3D([0.0, 1.0, 0.0], scale=2)
)

# Log translation + rotation, also called a rigid transform.
rr.log_transform3d("transform_test/rigid3", rr.Rigid3D([1, 2, 3], rr.RotationAxisAngle((0, 1, 0), radians=1.57)))

# Log translation, rotation & scale all at once.
rr.log_transform3d(
    "transform_test/transformed",
    rr.TranslationRotationScale3D(
        translation=[0, 1, 5],
        rotation=rr.RotationAxisAngle((0, 0, 1), degrees=20),
        scale=2,
    ),
)

Parameters:

Name Type Description Default
entity_path str

Path of the child space in the space hierarchy.

 required
transform TranslationAndMat3 | TranslationRotationScale3D | RotationAxisAngle | Translation3D | Scale3D | Quaternion | Rigid3D

Instance of a rerun data class that describes a three dimensional transform. One of: * TranslationAndMat3 * TranslationRotationScale3D * Rigid3D * RotationAxisAngle * Translation3D * Quaternion * Scale3D

 required
from_parent bool

If True, the transform is from the parent to the child, otherwise it is from the child to the parent.

 False
timeless bool

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

 False
recording RecordingStream | None

Specifies the rerun.RecordingStream to use. If left unspecified, defaults to the current active data recording, if there is one. See also: rerun.init, rerun.set_global_data_recording.

 None

def rerun.log_pinhole(entity_path, *, width, height, focal_length_px=None, principal_point_px=None, child_from_parent=None, timeless=False, recording=None, camera_xyz=None)

Log a perspective camera model.

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

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

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

Example
width = 640
height = 480
f_len = (height * width) ** 0.5

rerun.log_pinhole("world/camera/image",
                  width = width,
                  height = height,
                  focal_length_px = f_len)

# More explicit:
u_cen = width / 2
v_cen = height / 2
rerun.log_pinhole("world/camera/image",
                  width = width,
                  height = height,
                  child_from_parent = [[f_len, 0,     u_cen],
                                       [0,     f_len, v_cen],
                                       [0,     0,     1  ]],
                  camera_xyz="RDF")

Parameters:

Name Type Description Default
entity_path str

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

 required
focal_length_px float | ArrayLike | None

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.

 None
principal_point_px ArrayLike | None

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

 None
child_from_parent ArrayLike | None

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_px and principal_point_px.

 None
width int

Width of the image in pixels.

 required
height int

Height of the image in pixels.

 required
timeless bool

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

 False
recording RecordingStream | None

Specifies the rerun.RecordingStream to use. If left unspecified, defaults to the current active data recording, if there is one. See also: rerun.init, rerun.set_global_data_recording.

 None
camera_xyz str | None

Sets the view coordinates for the camera. The default is "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.

Each letter represents:

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

The camera furstum will point whichever axis is set to F (or the oppositve of B). When logging a depth image under this entity, this is the direction the point cloud will be projected. With XYZ=RDF, the default forward is +Z.

The frustum's "up" direction will be whichever axis is set to U (or the oppositve 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 oppositve 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).

Equivalent to calling rerun.log_view_coordinates(entity, xyz=…).

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 child_from_parent argument) always project along the third (Z) axis, but will be re-oriented to project along the forward axis of the camera_xyz argument.

 None

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

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

Parameters:

Name Type Description Default
entity_path str

The path of the affected entity.

 required

timeless: Log the data as timeless.

recording: Specifies the rerun.RecordingStream to use. If left unspecified, defaults to the current active data recording, if there is one. See also: rerun.init, rerun.set_global_data_recording.

def rerun.log_disconnected_space(entity_path, timeless=False, recording=None)

Log that this entity is NOT in the same space as the 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 component will be ignored.

Parameters:

Name Type Description Default
entity_path str

The path of the affected entity.

 required

timeless: Log the data as timeless.

recording: Specifies the rerun.RecordingStream to use. If left unspecified, defaults to the current active data recording, if there is one. See also: rerun.init, rerun.set_global_data_recording.

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

Log the view coordinates for an entity.

Each entity defines its own coordinate system, called a space. By logging view coordinates you can give semantic meaning to the XYZ axes of the space.

This is particularly useful for 3D spaces, to set the up-axis.

For pinhole entities this will control the direction of the camera frustum. You should use rerun.log_pinhole(…, camera_xyz=…) for this instead, and read the documentation there.

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

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

Some of the most common are:

  • "RDF": X=Right Y=Down Z=Forward (right-handed)
  • "RUB" X=Right Y=Up Z=Back (right-handed)
  • "RDB": X=Right Y=Down Z=Back (left-handed)
  • "RUF": X=Right Y=Up Z=Forward (left-handed)

Currently Rerun only supports right-handed coordinate systems.

Example
rerun.log_view_coordinates("world/camera/image", xyz="RUB")

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

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

Parameters:

Name Type Description Default
entity_path str

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

 required
xyz str

Three-letter acronym for the view coordinate axes.

 ''
up str

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

 ''
right_handed bool | None

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

 None
timeless bool

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

 False
recording RecordingStream | None

Specifies the rerun.RecordingStream to use. If left unspecified, defaults to the current active data recording, if there is one. See also: rerun.init, rerun.set_global_data_recording.

 None