Poses2D

SUMMARY

A batch of positions and orientations in 2D space.

from telekinesis import datatypes
poses = datatypes.Poses2D([[1.0, 2.0, 90.0], [3.0, 4.0, 0.0]])

API Reference

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

View Reference →

Parameters

Parameter	Type	Default	Description
data	np.ndarray | list | tuple	Required	Planar poses with shape (N, 3), with one [x, y, yaw] row per pose. 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-2, or its last axis isn't length 3
ValueError	data contains a non-finite value (NaN/Inf)

Attributes

Attribute	Type	Description
data	np.ndarray	Defensive copy of the underlying (N, 3) float32 array. Assigning a new value re-validates it the same way as construction.
shape	tuple[int, ...]	(N, 3), where N is the batch size.
ndim	int	Always 2.
dtype	np.dtype	Always float32.
size	int	N * 3.
positions	np.ndarray	Positions, shape (N, 2) — a copy of data[:, 0:2].
orientations	np.ndarray	Orientations (yaw) in degrees, shape (N, 1) — a copy of data[:, 2:3].

Methods

Method	Type	Description
Poses2D.coerce(value)	Poses2D	Converts array-like data into a Poses2D. Accepts an (N, 3) array-like, one [x, y, yaw] row per pose, checked the same way as the constructor. If value is already a Poses2D, it is returned unchanged.
to_numpy(copy=True)	np.ndarray	Returns the poses' 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 Poses2D.
copy()	Poses2D	Returns a new, independent Poses2D with the same data.

Operators

Operation	Behavior
p == other	True only if other is also a Poses2D with element-equal data (same N, same values). False for anything else.
len(p)	The batch size N (length of the first axis).
poses[i]	Returns a Pose2D for an integer index (negative indices supported). Raises IndexError if out of range.
poses[a:b] / poses[mask]	Returns a new Poses2D holding the matched rows, for a slice or a boolean np.ndarray mask. Any other index type raises TypeError.
for p in poses	Iterates via __getitem__ (the old-style sequence protocol), yielding one Pose2D per row in order.
np.asarray(p)	Returns a copy of data as an np.ndarray; NumPy functions accept a Poses2D directly.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("poses2d_example", spawn=True)
datatypes.visualize(poses, entity_path="/poses", label="Poses2D")

Example

"""Demonstrates the Telekinesis Poses2D datatype."""

import time

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

from telekinesis import datatypes


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

    # ======================= Create ============================================
    poses_data = [[1.0, 2.0, 90.0], [3.0, 4.0, 0.0]]
    poses2d = datatypes.Poses2D(poses_data)
    logger.info(f"Created Poses2D: {poses2d}")

    # ======================= Inspect ===========================================
    logger.info(f"data={poses2d.data}")
    logger.info(f"shape={poses2d.shape}")
    logger.info(f"ndim={poses2d.ndim}")
    logger.info(f"dtype={poses2d.dtype}")
    logger.info(f"size={poses2d.size}")
    logger.info(f"positions={poses2d.positions}")
    logger.info(f"orientations={poses2d.orientations}")

    # ======================= Operations =========================================
    poses2d.data = [[3.0, 4.0, 45.0], [5.0, 6.0, 180.0]]
    logger.info(f"Updated Poses2D: {poses2d}")

    poses2d_copy = poses2d.copy()
    logger.info(f"Copied Poses2D: {poses2d_copy}")

    poses2d_numpy = poses2d.to_numpy(copy=True)
    logger.info(f"NumPy Poses2D: {poses2d_numpy}")

    first_pose2d = poses2d[0]
    logger.info(f"First Pose2D via indexing: {first_pose2d}")

    poses2d_subset = poses2d[0:1]
    logger.info(f"Poses2D subset via slicing: {poses2d_subset}")

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

    # ======================= Visualize =========================================
    rr.init("poses2d_example", spawn=True)
    datatypes.visualize(poses2d, entity_path="/poses2d", label=["Poses2D 0", "Poses2D 1"])

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


if __name__ == "__main__":
    poses2d_example()