Array

SUMMARY

A generic multidimensional NumPy array.

from telekinesis import datatypes
array = datatypes.Array([1, 2, 5])

API Reference

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

View Reference →

Parameters

Parameter	Type	Default	Description
data	np.ndarray | list | tuple	Required	The array-like data to store, with a supported dtype (see below).

Raises

Exception	Condition
TypeError	data can't be converted into a uniform array (e.g. ragged nested lists)
ValueError	The resulting dtype is unsupported (see Supported Dtypes below)

Supported Dtypes

Category	Dtypes
Boolean	bool
Signed / unsigned integer	int8…int64, uint8…uint64
Floating-point	float16, float32, float64

object, structured, datetime64, and complex (complex64/complex128) dtypes are not supported.

Attributes

Attribute	Type	Description
data	np.ndarray	The wrapped array. Reading it returns a copy, so mutating the result doesn't affect the Array; assigning a new value re-validates it the same way as construction.
shape	tuple[int, ...]	Shape of the array.
ndim	int	Number of dimensions.
dtype	np.dtype	Dtype of the array.
size	int	Total number of elements.

Methods

Method	Type	Description
Array.coerce(value, name="value")	Array	Converts array-like data into an Array. Accepts a np.ndarray, list, or tuple. If value is already an Array, it is returned unchanged. The optional name is only used to make validation error messages more descriptive.
to_numpy(copy=True)	np.ndarray	Returns the data 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 Array.
copy()	Array	Returns a new, independent Array with the same data.

Operators

Operation	Behavior
arr == other	Compare with another Array value.
len(arr)	Returns the length of the first axis.
np.asarray(arr)	Convert to a NumPy array with np.asarray(arr).

Visualization

import rerun as rr

# Your code block
# ....

rr.init("array_example", spawn=True)
datatypes.visualize(array, entity_path="/array", label="Array")

Example

"""Demonstrates the Telekinesis Array datatype."""

import time

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

from telekinesis import datatypes

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

    # ======================= Create ============================================
    data = np.arange(12, dtype=np.int32).reshape(3, 4)
    array = datatypes.Array(data)
    logger.info(f"Created Array: {array}")

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

    # ======================= Operations =========================================
    array.data = np.arange(24, dtype=np.float32).reshape(4, 6)
    logger.info(f"Updated Array: {array}")

    array_copy = array.copy()
    logger.info(f"Copied Array: {array_copy}")

    array_numpy = array.to_numpy(copy=True)
    logger.info(f"NumPy Array:\n{array_numpy}")

    numpy_array = np.asarray(array)
    reshaped = np.reshape(array, (2, 12))
    logger.info(f"NumPy array:\n{numpy_array}")
    logger.info(f"Reshaped array:\n{reshaped}")
    logger.info(f"Sum: {np.sum(array)}")

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

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


if __name__ == "__main__":
    array_example()