Twist3D

SUMMARY

Linear and angular velocity in 3D space.

from telekinesis import datatypes
twist = datatypes.Twist3D([0.1, 0.0, 0.0, 0.0, 0.0, 0.2])

API Reference

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

View Reference →

Parameters

Parameter	Type	Default	Description
data	np.ndarray | list | tuple	Required	Linear and angular velocity [vx, vy, vz, wx, wy, wz] with shape (6,).

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 (6,)
ValueError	data contains a non-finite value (NaN/Inf)

Attributes

Attribute	Type	Description
data	np.ndarray	Defensive copy of the underlying (6,) float32 array. Assigning a new value re-validates it the same way as construction.
shape	tuple[int, ...]	Always (6,).
ndim	int	Always 1.
dtype	np.dtype	Always float32.
size	int	Always 6.

Methods

Method	Type	Description
Twist3D.coerce(value)	Twist3D	Converts array-like data into a Twist3D. Accepts a np.ndarray, list, or tuple of shape (6,): [vx, vy, vz, wx, wy, wz]. If value is already a Twist3D, it is returned unchanged.
to_numpy(copy=True)	np.ndarray	Returns the twist 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 Twist3D.
copy()	Twist3D	Returns a new, independent Twist3D with the same data.

Operators

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

Visualization

import rerun as rr

# Your code block
# ....

rr.init("twist3d_example", spawn=True)
datatypes.visualize(twist, entity_path="/twist", label="Twist3D")

Example

"""Demonstrates the Telekinesis Twist3D datatype."""

import time

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

from telekinesis import datatypes

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

    # ======================= Create ============================================
    values = np.array([0.1, 0.0, 0.0, 0.0, 0.0, 0.2], dtype=np.float32)
    twist3d = datatypes.Twist3D(values)
    logger.info(f"Created Twist3D: {twist3d}")

    twist3d_from_coerce = datatypes.Twist3D.coerce(values)
    logger.info(f"Twist3D created via coerce: {twist3d_from_coerce}")

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

    # ======================= Operations =========================================
    twist3d.data = np.array([0.0, 0.3, 0.0, 0.1, 0.0, 0.0], dtype=np.float32)
    logger.info(f"Updated Twist3D: {twist3d}")

    twist3d_copy = twist3d.copy()
    logger.info(f"Copied Twist3D: {twist3d_copy}")

    twist3d_numpy = twist3d.to_numpy(copy=True)
    logger.info(f"NumPy Twist3D: {twist3d_numpy}")

    numpy_array = np.asarray(twist3d)
    logger.info(f"NumPy array: {numpy_array}")
    logger.info(f"Sum: {np.sum(twist3d)}")
    logger.info(f"length={len(twist3d)}")

    # ======================= Visualize =========================================
    rr.init("twist3d_example", spawn=True)
    datatypes.visualize(
        twist3d_from_coerce, entity_path="/twist3d/coerced", label="Coerced Twist3D"
    )
    datatypes.visualize(twist3d, entity_path="/twist3d/updated", label="Updated Twist3D")

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


if __name__ == "__main__":
    twist3d_example()