Vectors4D

SUMMARY

A batch of vectors in 4D space.

from telekinesis import datatypes
vectors4d = datatypes.Vectors4D([[1.0, 2.0, 3.0, 4.0], [5.0, 6.0, 7.0, 8.0]])

API Reference

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

View Reference →

Parameters

Parameter	Type	Default	Description
data	np.ndarray | list | tuple	Required	Array-like data of shape (N, 4).

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 4, or it contains a non-finite value (NaN/Inf)

Attributes

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

Methods

Method	Type	Description
Vectors4D.coerce(value)	Vectors4D	Converts array-like data of shape (N, 4) into a Vectors4D. Accepts a np.ndarray, list, or tuple. If value is already a Vectors4D, it is returned unchanged.
to_numpy(copy=True)	np.ndarray	Returns the vectors 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 Vectors4D.
copy()	Vectors4D	Returns a new, independent Vectors4D with the same data.

Operators

Operation	Behavior
v1 == v2	True only if other is exactly a Vectors4D (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, 4)) — that's a valid, constructible batch.
np.asarray(v)	Returns a copy of data as an np.ndarray; NumPy functions accept a Vectors4D directly.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("vectors4d_example", spawn=True)
datatypes.visualize(vectors4d, entity_path="/vectors4d", label="Vectors4D")

Example

"""Demonstrates the Telekinesis Vectors4D datatype."""

import time

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

from telekinesis import datatypes

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

    # ======================= Create ============================================
    vectors = [[1.0, 2.0, 3.0, 4.0], [5.0, 6.0, 7.0, 8.0]]
    vectors4d = datatypes.Vectors4D(vectors)
    logger.info(f"Created Vectors4D: {vectors4d}")

    empty_vectors4d = datatypes.Vectors4D(np.empty((0, 4), dtype=np.float32))
    logger.info(f"Created empty Vectors4D batch: {empty_vectors4d}")

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

    # ======================= Operations =========================================
    vectors4d.data = [[9.0, 10.0, 11.0, 12.0], [13.0, 14.0, 15.0, 16.0]]
    logger.info(f"Updated Vectors4D: {vectors4d}")

    vectors4d_copy = vectors4d.copy()
    logger.info(f"Copied Vectors4D: {vectors4d_copy}")

    vectors4d_numpy = vectors4d.to_numpy(copy=True)
    logger.info(f"NumPy Vectors4D:\n{vectors4d_numpy}")

    numpy_array = np.asarray(vectors4d)
    column_sums = np.sum(vectors4d, axis=0)
    logger.info(f"NumPy array:\n{numpy_array}")
    logger.info(f"Column sums: {column_sums}")

    # ======================= Visualize =========================================
    rr.init("vectors4d_example", spawn=True)
    datatypes.visualize(vectors4d, entity_path="/vectors4d")

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


if __name__ == "__main__":
    vectors4d_example()

See also Vector4D for a single 4D vector.