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	True only if other is also an Array with the same dtype, shape, and values (NaN counts as equal to NaN here). False for anything else.
len(arr)	Length of the first axis, like a NumPy array. Raises TypeError if arr is 0-dimensional.
np.asarray(arr)	Returns a copy of data as an np.ndarray; NumPy functions accept an Array directly.

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()