Poses3D

Represents a batch of SE(3) poses: a 3D position plus an orientation quaternion per pose.

Parameters

Field	Type	Description
data	np.ndarray | list | tuple	Array-like input of shape (N, 7), one row [x, y, z, qw, qx, qy, qz] 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 7
ValueError	data contains a non-finite value (NaN/Inf)
ValueError	Any row's quaternion sub-range data[:, 3:7] is the zero quaternion (norm 0.0)
ValueError	Any row's quaternion sub-range data[:, 3:7] has a norm deviating from 1.0 by more than quat_norm_atol (1e-3)

Attributes

Attribute	Type	Description
data	np.ndarray	Defensive copy of the underlying (N, 7) float32 array. Assigning a new value re-validates it (shape, finiteness, per-row unit-norm quaternion) the same way as construction.
shape	tuple[int, ...]	(N, 7), where N is the batch size.
ndim	int	Always 2.
dtype	np.dtype	Always float32.
size	int	N * 7.
quat_slice	slice	Class-level, slice(3, 7) — the last-axis range checked for unit norm in every row.
quat_norm_atol	float	Class-level, 1e-3 — max allowed abs(norm - 1) per row.
quat_order	str	Class-level, "wxyz" — this class's native scalar-first quaternion order.

Methods

Method	Description
Poses3D.to_xyzw(q)	Inherited from QuaternionValidationMixin. Converts a quaternion array (or batch, shape (..., 4)) from quat_order ("wxyz") to scalar-last [x, y, z, w], e.g. before handing it to scipy.
Poses3D.from_xyzw(q)	Inherited from QuaternionValidationMixin. Converts a quaternion array (or batch) from scalar-last [x, y, z, w] to quat_order ("wxyz").
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 Poses3D too.
copy()	Returns a new Poses3D with an independent copy of the data.
Poses3D.coerce(value)	Returns value unchanged if it's already a Poses3D; otherwise wraps an array-like into one (running full validation). Raises TypeError for any other input.

Operators

Operation	Behavior
p == other	True only if other is also a Poses3D 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 (rotated basis axes from that row's quaternion) 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 Poses3D datatype."""

from loguru import logger
import rerun as rr

from telekinesis import datatypes


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

    # ======================= Create ============================================
    poses3d = datatypes.Poses3D(
        [[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0], [1.0, 2.0, 3.0, 0.0, 0.0, 0.0, 1.0]]
    )
    logger.info(f"Original Poses3D: {poses3d}")

    # ======================= Inspect ===========================================
    data = poses3d.data
    logger.info(f"Underlying Poses3D data: {data}")

    # ======================= Visualize =========================================
    rr.init("poses3d_example", spawn=True)
    datatypes.visualize(poses3d, entity_path="/Poses3D", label=["My Poses3D 0", "My Poses3D 1"])


if __name__ == "__main__":
    poses3d_example()