Vector3D

SUMMARY

A vector in 3D space.

from telekinesis import datatypes
vector3d = datatypes.Vector3D([1.0, 2.0, 3.0])

API Reference

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

View Reference →

Parameters

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

Raises

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

Attributes

Attribute	Type	Description
shape_spec	ClassVar[tuple[int, ...]]	Class-level shape spec, (3,).
data	np.ndarray	The wrapped vector. Reading it returns a copy, so mutating the result doesn't affect the Vector3D; assigning a new value re-validates it the same way as construction.
shape	tuple[int, ...]	Always (3,).
ndim	int	Always 1.
dtype	np.dtype	Always float32.
size	int	Always 3.

Methods

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

Operators

Operation	Behavior
v1 == v2	True only if other is exactly a Vector3D (not a subclass, not another datatype) with element-equal data. False for anything else.
len(v)	Always 3 (length of the single axis).
np.asarray(v)	Returns a copy of data as an np.ndarray; NumPy functions accept a Vector3D directly.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("vector3d_example", spawn=True)
datatypes.visualize(vector3d, entity_path="/vector3d", label="Vector3D")

Example

"""Demonstrates the Telekinesis Vector3D datatype."""

import time

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

from telekinesis import datatypes


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

    # ======================= Create ============================================
    vector3d = datatypes.Vector3D([1.0, 2.0, 3.0])
    logger.info(f"Created Vector3D: {vector3d}")

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

    # ======================= Operations =========================================
    vector3d.data = [4.0, 5.0, 6.0]
    logger.info(f"Updated Vector3D: {vector3d}")

    vector3d_copy = vector3d.copy()
    logger.info(f"Copied Vector3D: {vector3d_copy}")

    vector3d_numpy = vector3d.to_numpy(copy=True)
    logger.info(f"NumPy Vector3D: {vector3d_numpy}")

    numpy_array = np.asarray(vector3d)
    logger.info(f"NumPy array: {numpy_array}")

    sum_with_numpy = vector3d + np.array([1.0, 1.0, 1.0])
    logger.info(f"Sum of Vector3D with NumPy array: {sum_with_numpy}")

    norm = np.linalg.norm(vector3d)
    logger.info(f"Norm (np.linalg.norm): {norm}")

    # ======================= Visualize =========================================
    rr.init("vector3d_example", spawn=True)
    datatypes.visualize(vector3d, entity_path="/vector3d", label="Updated Vector3D")

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


if __name__ == "__main__":
    vector3d_example()

See also Vectors3D for batches of 3D vectors.