Position2D

SUMMARY

A position in 2D space.

from telekinesis import datatypes
position = datatypes.Position2D([10.0, 20.0])

API Reference

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

View Reference →

Parameters

Parameter	Type	Default	Description
data	np.ndarray | list | tuple	Required	Position coordinates [x, y] with shape (2,).

Raises

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

Attributes

Attribute	Type	Description
data	np.ndarray	Defensive copy of the underlying (2,) float32 array. Assigning a new value re-validates it the same way as construction.
shape	tuple[int, ...]	Always (2,).
ndim	int	Always 1.
dtype	np.dtype	Always float32.
size	int	Always 2.

Methods

Method	Type	Description
Position2D.coerce(value)	Position2D	Converts array-like data into a Position2D. If value is already a Position2D, it is returned unchanged; otherwise it goes through the same checks as constructing one directly.
to_numpy(copy=True)	np.ndarray	Returns the position 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 Position2D.
copy()	Position2D	Returns a new, independent Position2D with the same data.

Operators

Operation	Behavior
pos == other	True only if other is also a Position2D with element-equal data. False for anything else, including a Vector2D with the same values — comparison requires the exact same type.
len(pos)	Always 2.
np.asarray(pos)	Returns a copy of data as an np.ndarray; NumPy functions accept a Position2D directly.
pos + array, pos - array	Not implemented on Position2D — Python falls back to NumPy's array coercion (__array__), so e.g. pos + np.array([5.0, 10.0]) returns a plain np.ndarray, not a Position2D.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("position2d_example", spawn=True)
datatypes.visualize(position, entity_path="/position", label="Position2D")

Example

"""Demonstrates the Telekinesis Position2D datatype."""

import time

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

from telekinesis import datatypes


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

    # ======================= Create ============================================
    position2d = datatypes.Position2D([10.0, 20.0])
    logger.info(f"Created Position2D: {position2d}")

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

    # ======================= Operations =========================================
    position2d.data = [30.0, 40.0]
    logger.info(f"Updated Position2D: {position2d}")

    position2d_copy = position2d.copy()
    logger.info(f"Copied Position2D: {position2d_copy}")

    position2d_numpy = position2d.to_numpy(copy=True)
    logger.info(f"NumPy Position2D: {position2d_numpy}")

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

    sum_with_numpy = position2d + np.array([5.0, 10.0])
    logger.info(f"Sum of Position2D with NumPy array: {sum_with_numpy}")

    distance_from_origin = np.linalg.norm(position2d)
    logger.info(f"Distance from origin (np.linalg.norm): {distance_from_origin}")

    # ======================= Visualize =========================================
    rr.init("position2d_example", spawn=True)
    datatypes.visualize(position2d, entity_path="/position2d", label="Updated Position2D")

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


if __name__ == "__main__":
    position2d_example()