Poses2D

Represents a batch of 2D poses: a planar position plus a heading angle per pose.

Parameters

Field	Type	Description
data	np.ndarray | list | tuple	Array-like input of shape (N, 3), one row [x, y, theta] per pose, converted to a contiguous float32 array.

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.

Methods

Method	Description
to_numpy(copy=True)	Returns the batch as np.ndarray. Pass copy=False for a reference to the internal array instead — faster, but mutating it mutates the Poses2D too.
copy()	Returns a new Poses2D with an independent copy of the data.
Poses2D.coerce(value)	Returns value unchanged if it's already a Poses2D; otherwise wraps an array-like into one. Raises TypeError for any other input.

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).
np.asarray(p)	Works directly via __array__. Always returns a copy; use to_numpy(copy=False) for a zero-copy view.
hash(p)	Not supported — mutable via the data setter.

Visualization

datatypes.visualize(poses, entity_path=...) logs each pose's posed frame under its own indexed child path ({entity_path}/{i}), plus a single shared world-origin frame labeled "origin" (logged once, not once per pose, to avoid overlapping labels at the coincident origin points). Passing label=[...] (one string per pose) attaches a floating text label at each pose's own frame.

Example

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

from loguru import logger
import rerun as rr

from telekinesis import datatypes


def poses2d_example():
    """Demonstrate creation, access, and visualization."""

    # ======================= Create ============================================
    poses2d = datatypes.Poses2D([[1.0, 2.0, 0.5], [3.0, 4.0, 1.2]])
    logger.info(f"Original Poses2D: {poses2d}")

    # ======================= Inspect ===========================================
    data = poses2d.data
    logger.info(f"Underlying Poses2D data: {data}")

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


if __name__ == "__main__":
    poses2d_example()