Transforms3D

SUMMARY

A batch of rigid-body transformations between 3D coordinate frames.

python

from telekinesis import datatypes
transforms = datatypes.Transforms3D([
    [[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0], [0.0, 0.0, 0.0, 1.0]],
])

Parameters

Parameter	Type	Default	Description
`data`	`np.ndarray \| list \| tuple`	Required	Batch of homogeneous 3D rigid-body transforms with shape `(N, 4, 4)`, each containing a 3 × 3 rotation matrix and a 3D translation.

Raises

Exception	Condition
`TypeError`	`data` can't be converted to float32 (e.g. non-numeric elements)
`ValueError`	`data` is not rank-3, or its shape isn't `(N, 4, 4)`
`ValueError`	`data` contains a non-finite value (`NaN`/`Inf`)
`ValueError`	Any row's last row isn't `[0, 0, 0, 1]` (within `transform_atol`)
`ValueError`	Any row's `3x3` rotation block isn't orthonormal (within `transform_atol`), or its determinant isn't `~1.0` (a determinant of `-1` is a reflection, not a rotation)

Attributes

Attribute	Type	Description
`data`	`np.ndarray`	Defensive copy of the underlying `(N, 4, 4)` float32 batch.
`shape`	`tuple[int, ...]`	Runtime shape of `data`, `(N, 4, 4)`.
`ndim`	`int`	Always `3`.
`dtype`	`np.dtype`	Always `float32`.
`size`	`int`	Total number of elements in `data`, `16*N`.
`transform_atol`	`float`	Class-level absolute tolerance (`1e-4`) used when validating each row's last row and rotation block.

Methods

Method	Type	Description
`Transforms3D.coerce(value)`	`Transforms3D`	Converts array-like data into a `Transforms3D`, running the same shape and SE(3) validity checks as the constructor. If `value` is already a `Transforms3D`, it is returned unchanged.
`Transforms3D.from_pose(poses, rot_type=RotationType.QUATERNION)`	`Transforms3D`	Builds a `Transforms3D` from a batch of flat, position-first pose vectors: shape `(N, 7)` rows `[x, y, z, qw, qx, qy, qz]` (scalar-first quaternion) by default, or shape `(N, 6)` rows `[x, y, z, r0, r1, r2]` (Euler angles or a rotation vector) when `rot_type` is `DEGREES`, `RADIANS`, or `ROTVEC`. `rot_type` accepts a RotationType member or its string value, and `poses` must be 2D with a last dimension (`6` or `7`) matching the chosen `rot_type`.
`to_poses3d()`	`Poses3D`	Returns the equivalent Poses3D, built from these transforms' positions and degree-based Euler orientations.
`inverse()`	`Transforms3D`	Returns a new `Transforms3D`, the inverse of every transform in the batch.
`to_numpy(copy=True)`	`np.ndarray`	Returns the `(N, 4, 4)` matrix batch. Pass `copy=False` to get a direct reference to the internal array instead, so mutating it also mutates the `Transforms3D`.
`copy()`	`Transforms3D`	Returns a new, independent `Transforms3D` with the same data.

Operators

Operation	Behavior
`transforms3d[i]`	Single `Transform3D` for that row (int index, supports negative indices).
`transforms3d[start:stop]`	New `Transforms3D` subset (slice).
`transforms3d[mask]`	New `Transforms3D` subset selected by a 1-D boolean mask.
`transforms3d == other`	`True` only if `other` is also a `Transforms3D` with element-equal data. `False` for anything else.
`len(transforms3d)`	Number of transforms `N` in the batch.
`np.asarray(transforms3d)`	Returns a copy of `data` as an `np.ndarray`; NumPy functions accept a `Transforms3D` directly.

Visualization

python

import rerun as rr

# Your code block
# ....

rr.init("transforms3d_example", spawn=True)
datatypes.visualize(transforms3d, entity_path="/transforms3d", label=["Transforms3D 0", "Transforms3D 1"])

Example

python

"""Demonstrates the Telekinesis Transforms3D datatype."""

import time

import numpy as np
import rerun as rr
from loguru import logger

from telekinesis import datatypes


def transforms3d_example():
    """Demonstrate creation, inspection, operations, visualization, and serialization."""

    # ======================= Create ============================================
    matrix_1 = np.array(
        [
            [0.5000000, -0.5000000, 0.7071068, 1.0],
            [0.8535534, 0.1464466, -0.5000000, 2.0],
            [0.1464466, 0.8535534, 0.5000000, 3.0],
            [0.0, 0.0, 0.0, 1.0],
        ]
    )
    matrix_2 = np.array(
        [
            [0.0, -1.0, 0.0, 4.0],
            [1.0, 0.0, 0.0, -1.0],
            [0.0, 0.0, 1.0, 0.5],
            [0.0, 0.0, 0.0, 1.0],
        ]
    )
    matrix_3 = np.eye(4)
    transforms3d = datatypes.Transforms3D([matrix_1, matrix_2, matrix_3])
    logger.info(f"Created Transforms3D: {transforms3d}")

    transforms3d_from_pose = datatypes.Transforms3D.from_pose(
        [
            [0.5, 0.2, 0.8, 0.0, 0.0, 0.3826834, 0.9238795],
            [0.1, 0.2, 0.3, 0.0, 0.0, 0.0, 1.0],
        ]
    )
    logger.info(f"Transforms3D created from pose: {transforms3d_from_pose}")

    # ======================= Inspect ===========================================
    logger.info(f"data=\n{transforms3d.data}")
    logger.info(f"shape={transforms3d.shape}")
    logger.info(f"ndim={transforms3d.ndim}")
    logger.info(f"dtype={transforms3d.dtype}")
    logger.info(f"size={transforms3d.size}")

    # ======================= Operations =========================================
    transforms3d_copy = transforms3d.copy()
    logger.info(f"Copied Transforms3D: {transforms3d_copy}")

    transforms3d_numpy = transforms3d.to_numpy(copy=True)
    logger.info(f"NumPy Transforms3D:\n{transforms3d_numpy}")

    inverse_transforms3d = transforms3d.inverse()
    logger.info(f"Inverse Transforms3D: {inverse_transforms3d}")

    poses3d = transforms3d.to_poses3d()
    logger.info(f"Transforms3D as Poses3D: {poses3d}")

    first_transform3d = transforms3d[0]
    logger.info(f"First Transform3D via indexing: {first_transform3d}")

    transforms3d_subset = transforms3d[0:2]
    logger.info(f"Transforms3D subset via slicing: {transforms3d_subset}")

    numpy_array = np.asarray(transforms3d)
    logger.info(f"NumPy array:\n{numpy_array}")

    # ======================= Visualize =========================================
    rr.init("transforms3d_example", spawn=True)
    datatypes.visualize(
        transforms3d,
        entity_path="/transforms3d",
        label=["Transforms3D 0", "Transforms3D 1", "Transforms3D 2"],
    )
    datatypes.visualize(
        transforms3d_from_pose,
        entity_path="/transforms3d/from_pose",
        label=["From Pose 0", "From Pose 1"],
    )

    # ======================= Serialize / Deserialize ===========================
    start = time.perf_counter()
    serialized = datatypes.serialize(transforms3d)
    serialization_ms = (time.perf_counter() - start) * 1000

    start = time.perf_counter()
    deserialized = datatypes.deserialize(serialized)["param_0"]
    deserialization_ms = (time.perf_counter() - start) * 1000

    logger.info(f"Deserialized Transforms3D: {deserialized}")
    logger.info(f"Round-trip successful: {deserialized == transforms3d}")
    logger.info(f"Serialization time: {serialization_ms:.3f} ms")
    logger.info(f"Deserialization time: {deserialization_ms:.3f} ms")


if __name__ == "__main__":
    transforms3d_example()

Transforms3D ​

Parameters ​

Raises ​

Attributes ​

Methods ​

Operators ​

Visualization ​

Example ​

Transforms3D

Parameters

Raises

Attributes

Methods

Operators

Visualization

Example