Transform3D
SUMMARY
A rigid-body transformation between two 3D coordinate frames.
python
from telekinesis import datatypes
transform = datatypes.Transform3D(
[[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 | Homogeneous 3D rigid-body transform with shape (4, 4), 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-2, or its shape isn't (4, 4) |
ValueError | data contains a non-finite value (NaN/Inf) |
ValueError | Last row isn't [0, 0, 0, 1] (within transform_atol) |
ValueError | The 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 (4, 4) float32 matrix. Assigning a new value re-validates it the same way as construction. |
shape | tuple[int, ...] | Always (4, 4). |
ndim | int | Always 2. |
dtype | np.dtype | Always float32. |
size | int | Always 16. |
transform_atol | float | Class-level absolute tolerance (1e-4) used when validating the last row and the rotation block. |
Methods
| Method | Type | Description |
|---|---|---|
Transform3D.coerce(value) | Transform3D | Converts array-like data into a Transform3D, running the same shape and SE(3) validity checks as the constructor. If value is already a Transform3D, it is returned unchanged. |
Transform3D.from_pose(pose, rot_type=RotationType.QUATERNION) | Transform3D | Builds a Transform3D from a flat, position-first pose vector: shape (7,) [x, y, z, qw, qx, qy, qz] (scalar-first quaternion) by default, or shape (6,) [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 pose must be 1D with a size (6 or 7) matching the chosen rot_type. |
to_pose3d() | Pose3D | Returns the equivalent Pose3D, converting this transform's position and rotation block into degree-based Euler XYZ orientation. |
inverse() | Transform3D | Returns a new Transform3D that is the inverse of this transform: [[Rᵗ, -Rᵗ·t], [0, 1]]. |
compute_transformation_error(other) | float | Computes a single SE(3) pose error between this transform and other — a combined rotation and translation magnitude, via the matrix logarithm. other must be a Transform3D. |
to_numpy(copy=True) | np.ndarray | Returns the matrix. Pass copy=False to get a direct reference to the internal array instead, so mutating it also mutates the Transform3D. |
copy() | Transform3D | Returns a new, independent Transform3D with the same data. |
Operators
| Operation | Behavior |
|---|---|
t == other | True only if other is also a Transform3D with element-equal data. False for anything else. |
len(t) | Always 4 (length of the first axis). |
np.asarray(t) | Returns a copy of data as an np.ndarray; NumPy functions accept a Transform3D directly. |
Visualization
python
import rerun as rr
# Your code block
# ....
rr.init("transform3d_example", spawn=True)
datatypes.visualize(transform, entity_path="/transform", label="Transform3D")Example
python
"""Demonstrates the Telekinesis Transform3D datatype."""
import time
import numpy as np
import rerun as rr
from loguru import logger
from telekinesis import datatypes
def transform3d_example():
"""Demonstrate creation, inspection, operations, visualization, and serialization."""
# ======================= Create ============================================
matrix = 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],
]
)
transform3d = datatypes.Transform3D(matrix)
logger.info(f"Created Transform3D: {transform3d}")
transform3d_from_pose = datatypes.Transform3D.from_pose(
[0.5, 0.2, 0.8, 0.0, 0.0, 0.3826834, 0.9238795]
)
logger.info(f"Transform3D created from pose: {transform3d_from_pose}")
# ======================= Inspect ===========================================
logger.info(f"data=\n{transform3d.data}")
logger.info(f"shape={transform3d.shape}")
logger.info(f"ndim={transform3d.ndim}")
logger.info(f"dtype={transform3d.dtype}")
logger.info(f"size={transform3d.size}")
# ======================= Operations =========================================
new_matrix = np.array(
[
[0.5000000, -0.5000000, 0.7071068, 1.5],
[0.8535534, 0.1464466, -0.5000000, 2.5],
[0.1464466, 0.8535534, 0.5000000, 3.0],
[0.0, 0.0, 0.0, 1.0],
]
)
transform3d.data = new_matrix
logger.info(f"Updated Transform3D: {transform3d}")
transform3d_copy = transform3d.copy()
logger.info(f"Copied Transform3D: {transform3d_copy}")
transform3d_numpy = transform3d.to_numpy(copy=True)
logger.info(f"NumPy Transform3D:\n{transform3d_numpy}")
inverse_transform3d = transform3d.inverse()
logger.info(f"Inverse Transform3D: {inverse_transform3d}")
pose3d = transform3d.to_pose3d()
logger.info(f"Transform3D as Pose3D: {pose3d}")
transformation_error = transform3d.compute_transformation_error(transform3d_from_pose)
logger.info(f"Transformation error vs pose-based Transform3D: {transformation_error}")
numpy_array = np.asarray(transform3d)
sum_result = numpy_array + np.array([1, 1, 1, 0])
logger.info(f"NumPy array:\n{numpy_array}")
logger.info(f"Sum of Transform3D with NumPy array:\n{sum_result}")
# ======================= Visualize =========================================
rr.init("transform3d_example", spawn=True)
datatypes.visualize(transform3d, entity_path="/transform3d", label="Transform3D")
datatypes.visualize(
inverse_transform3d, entity_path="/transform3d/inverse", label="Inverse Transform3D"
)
datatypes.visualize(
transform3d_from_pose,
entity_path="/transform3d/from_pose",
label="Transform3D From Pose",
)
# ======================= Serialize / Deserialize ===========================
start = time.perf_counter()
serialized = datatypes.serialize(transform3d)
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 Transform3D: {deserialized}")
logger.info(f"Round-trip successful: {deserialized == transform3d}")
logger.info(f"Serialization time: {serialization_ms:.3f} ms")
logger.info(f"Deserialization time: {deserialization_ms:.3f} ms")
if __name__ == "__main__":
transform3d_example()