Transform2D

SUMMARY

A rigid-body transformation between two 2D coordinate frames.

from telekinesis import datatypes
transform = datatypes.Transform2D([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]])

API Reference

Complete API documentation for Transform2D, including parameters, attributes, and methods.

View Reference →

Parameters

Parameter	Type	Default	Description
data	np.ndarray | list | tuple	Required	Homogeneous 2D rigid-body transform with shape (3, 3), containing a 2 × 2 rotation matrix and a 2D 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 (3, 3)
ValueError	data contains a non-finite value (NaN/Inf)
ValueError	Last row isn't [0, 0, 1] (within transform_atol)
ValueError	The 2x2 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 (3, 3) float32 matrix. Assigning a new value re-validates it the same way as construction.
shape	tuple[int, ...]	Always (3, 3).
ndim	int	Always 2.
dtype	np.dtype	Always float32.
size	int	Always 9.
transform_atol	float	Class-level absolute tolerance (1e-4) used when validating the last row and the rotation block.

Methods

Method	Type	Description
Transform2D.coerce(value)	Transform2D	Converts array-like data into a Transform2D. Accepts a np.ndarray, list, or tuple of shape (3, 3), checked the same way as constructing one directly — the bottom row must be [0, 0, 1] and the top-left 2x2 block must be a valid rotation. If value is already a Transform2D, it is returned unchanged.
to_numpy(copy=True)	np.ndarray	Returns the matrix as a plain array. With the default copy=True you get an independent copy; pass copy=False to get a direct reference to the internal array instead, so mutating it also mutates the Transform2D.
copy()	Transform2D	Returns a new, independent Transform2D with the same data.

Operators

Operation	Behavior
t == other	True only if other is also a Transform2D with element-equal data. False for anything else.
len(t)	Always 3 (length of the first axis).
np.asarray(t)	Returns a copy of data as an np.ndarray; NumPy functions accept a Transform2D directly.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("transform2d_example", spawn=True)
datatypes.visualize(transform, entity_path="/transform", label="Transform2D")

Example

"""Demonstrates the Telekinesis Transform2D datatype."""

import time

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

from telekinesis import datatypes


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

    # ======================= Create ============================================
    theta = np.pi / 4
    matrix = np.array(
        [
            [np.cos(theta), -np.sin(theta), 1.0],
            [np.sin(theta), np.cos(theta), 2.0],
            [0.0, 0.0, 1.0],
        ]
    )
    transform2d = datatypes.Transform2D(matrix)
    logger.info(f"Created Transform2D: {transform2d}")

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

    # ======================= Operations =========================================
    updated_theta = np.pi / 2
    updated_matrix = np.array(
        [
            [np.cos(updated_theta), -np.sin(updated_theta), 1.5],
            [np.sin(updated_theta), np.cos(updated_theta), 2.5],
            [0.0, 0.0, 1.0],
        ]
    )
    transform2d.data = updated_matrix
    logger.info(f"Updated Transform2D: {transform2d}")

    transform2d_copy = transform2d.copy()
    logger.info(f"Copied Transform2D: {transform2d_copy}")

    transform2d_numpy = transform2d.to_numpy(copy=True)
    logger.info(f"NumPy Transform2D:\n{transform2d_numpy}")

    numpy_array = np.asarray(transform2d)
    total = numpy_array + np.array([1, 1, 0])
    logger.info(f"NumPy array:\n{numpy_array}")
    logger.info(f"Sum of Transform2D with NumPy array:\n{total}")

    # ======================= Visualize =========================================
    rr.init("transform2d_example", spawn=True)
    datatypes.visualize(transform2d, entity_path="/transform2d", label="Transform2D")

    # ======================= Serialize / Deserialize ===========================
    start = time.perf_counter()
    serialized = datatypes.serialize(transform2d)
    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 Transform2D: {deserialized}")
    logger.info(f"Round-trip successful: {transform2d == deserialized}")
    logger.info(f"Serialization time: {serialization_ms:.3f} ms")
    logger.info(f"Deserialization time: {deserialization_ms:.3f} ms")


if __name__ == "__main__":
    transform2d_example()