Pose2D

SUMMARY

A position and orientation in 2D space.

from telekinesis import datatypes
pose = datatypes.Pose2D([1.0, 2.0, 90.0])

API Reference

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

View Reference →

Parameters

Parameter	Type	Default	Description
data	np.ndarray | list | tuple	Required	Planar pose [x, y, yaw] with shape (3,). yaw is expressed in degrees.

Raises

Exception	Condition
TypeError	data can't be converted to float32 (e.g. non-numeric elements)
ValueError	data is not rank-1, or its shape isn't (3,)
ValueError	data contains a non-finite value (NaN/Inf)

Attributes

Attribute	Type	Description
data	np.ndarray	Defensive copy of the underlying (3,) float32 array. Assigning a new value re-validates it the same way as construction.
shape	tuple[int, ...]	Always (3,).
ndim	int	Always 1.
dtype	np.dtype	Always float32.
size	int	Always 3.
position	np.ndarray	Position [x, y] — a copy of data[0:2].
orientation	np.ndarray	Orientation [yaw] in degrees — a copy of data[2:3].

Methods

Method	Type	Description
Pose2D.coerce(value)	Pose2D	Converts array-like data into a Pose2D. Accepts a [x, y, yaw] array-like of shape (3,), checked the same way as the constructor. If value is already a Pose2D, it is returned unchanged.
to_transform2d()	Transform2D	Converts this pose into the equivalent Transform2D — an SE(2) homogeneous 3x3 matrix built from the pose's position and yaw.
to_numpy(copy=True)	np.ndarray	Returns the pose's coordinates 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 Pose2D.
copy()	Pose2D	Returns a new, independent Pose2D with the same data.

Operators

Operation	Behavior
p == other	True only if other is also a Pose2D with element-equal data. False for anything else.
len(p)	Always 3.
np.asarray(p)	Returns a copy of data as an np.ndarray; NumPy functions accept a Pose2D directly.
p + array	Not implemented on Pose2D — Python falls back to NumPy's array coercion (__array__), so e.g. np.asarray(p) + np.array([1.0, 1.0, 0.0]) returns a plain np.ndarray, not a Pose2D.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("pose2d_example", spawn=True)
datatypes.visualize(pose, entity_path="/pose", label="Pose2D")

Example

"""Demonstrates the Telekinesis Pose2D datatype."""

import time

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

from telekinesis import datatypes


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

    # ======================= Create ============================================
    pose_data = [1.0, 2.0, 90.0]
    pose2d = datatypes.Pose2D(pose_data)
    logger.info(f"Created Pose2D: {pose2d}")

    # ======================= Inspect ===========================================
    logger.info(f"data={pose2d.data}")
    logger.info(f"shape={pose2d.shape}")
    logger.info(f"ndim={pose2d.ndim}")
    logger.info(f"dtype={pose2d.dtype}")
    logger.info(f"size={pose2d.size}")
    logger.info(f"position={pose2d.position}")
    logger.info(f"orientation={pose2d.orientation}")

    # ======================= Operations =========================================
    pose2d.data = [3.0, 4.0, 45.0]
    logger.info(f"Updated Pose2D: {pose2d}")

    pose2d_copy = pose2d.copy()
    logger.info(f"Copied Pose2D: {pose2d_copy}")

    pose2d_numpy = pose2d.to_numpy(copy=True)
    logger.info(f"NumPy Pose2D: {pose2d_numpy}")

    transform2d = pose2d.to_transform2d()
    logger.info(f"Pose2D as Transform2D: {transform2d}")

    numpy_array = np.asarray(pose2d)
    translated = numpy_array + np.array([1.0, 1.0, 0.0], dtype=np.float32)
    logger.info(f"NumPy array: {numpy_array}")
    logger.info(f"Translated via NumPy addition: {translated}")

    # ======================= Visualize =========================================
    rr.init("pose2d_example", spawn=True)
    datatypes.visualize(pose2d, entity_path="/pose2d", label="Pose2D")
    datatypes.visualize(
        transform2d, entity_path="/pose2d/transform2d", label="Pose2D As Transform2D"
    )

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


if __name__ == "__main__":
    pose2d_example()