Vectors2D

Represents a batch of 2D vectors.

Parameters

Field	Type	Description
data	np.ndarray | list | tuple	Array-like data of shape (N, 2), converted to a contiguous float32 array.

Raises

Exception	Condition
TypeError	data can't be converted to a float32 array (e.g. non-numeric elements)
ValueError	data's rank isn't 2, its last axis isn't length 2, or it contains a non-finite value (NaN/Inf)

Attributes

Attribute	Type	Description
shape_spec	ClassVar[tuple[int | None, ...]]	Class-level shape spec, (None, 2) — None means the batch size is variable.
data	np.ndarray	The wrapped batch, shape (N, 2). Reading it returns a copy, so mutating the result doesn't affect the Vectors2D; assigning a new value re-validates it the same way as construction.
shape	tuple[int, ...]	(N, 2).
ndim	int	Always 2.
dtype	np.dtype	Always float32.
size	int	2 * N.

Methods

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

Operators

Operation	Behavior
v1 == v2	True only if other is exactly a Vectors2D (not a subclass, not another datatype) with element-equal data. False for anything else.
len(v)	Batch size N. 0 for an empty batch (shape (0, 2)) — that's a valid, constructible batch.
np.asarray(v)	Works directly — NumPy functions (e.g. np.reshape, np.sum) accept a Vectors2D in place of an np.ndarray. Always returns a copy; use to_numpy(copy=False) for a zero-copy view.
hash(v)	Not supported — a Vectors2D can't be used as a dict key or set member.

Visualization

datatypes.visualize(vectors, entity_path=..., label=...) logs the batch as N 2D arrows (rr.Arrows2D), each drawn from the world origin. Passing label as a list[str] of length N attaches one floating text label per arrow.

Example

"""Demonstrates the Telekinesis Vectors2D datatype."""

import time

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

from telekinesis import datatypes

def vectors2d_example():
    """Demonstrate creation, access, update, NumPy interop, serialization, and empty batches."""

    # ======================= Create ============================================
    vectors = [[1.0, 2.0], [3.0, 4.0]]
    vectors2d = datatypes.Vectors2D(vectors)

    logger.info(f"Created Vectors2D: {vectors2d}")

    # ======================= Inspect ===========================================
    data = vectors2d.data
    shape = vectors2d.shape
    size = vectors2d.size
    dtype = vectors2d.dtype
    ndim = vectors2d.ndim
    numpy_array = vectors2d.to_numpy()
    vectors2d_copy = vectors2d.copy()

    logger.info(f"shape={shape}, size={size}, ndim={ndim}, dtype={dtype}")
    logger.info(f"Vectors2D data: {data}")
    logger.info(f"NumPy array: {numpy_array}")
    logger.info(f"Copied Vectors2D: {vectors2d_copy}")

    # ======================= Visualize =========================================
    rr.init("vectors2d_example", spawn=True)
    datatypes.visualize(vectors2d, entity_path="/Vectors2D", label=["Vector 1", "Vector 2"])

    # ======================= Update ============================================
    new_data = [[5.0, 6.0], [7.0, 8.0]]
    vectors2d.data = new_data

    logger.info(f"Updated Vectors2D: {vectors2d}")
    datatypes.visualize(
        vectors2d,
        entity_path="/Vectors2D/updated",
        label=["Updated Vector 1", "Updated Vector 2"],
    )

    # ======================= NumPy Interop =====================================
    sum_result = vectors2d + np.array([1.0, 1.0])

    logger.info(f"Sum of Vectors2D with numpy array: {sum_result}")

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

    # ======================= Empty Batch =======================================
    empty = datatypes.Vectors2D(np.empty((0, 2), dtype=np.float32))

    logger.info(f"Empty Vectors2D: {empty}")
    logger.info(f"Empty Vectors2D shape: {empty.shape}")


if __name__ == "__main__":
    vectors2d_example()

See also Vector2D for a single 2D vector.