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 \| npt.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`	`npt.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`	`npt.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`