Points2D

SUMMARY

A batch of points in 2D space.

from telekinesis import datatypes
points2d = datatypes.Points2D([[10.0, 20.0], [30.0, 40.0]])

API Reference

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

View Reference →

Parameters

Parameter	Type	Default	Description
data	np.ndarray | list | tuple	Required	Array-like input, shape (N, 2). N can be 0 — an empty batch is valid.

Raises

Exception	Condition
TypeError	data can't be converted to a float32 array (e.g. ragged nested lists, non-numeric elements)
ValueError	The converted array isn't 2-D, its second axis isn't length 2, or it contains a non-finite value (NaN/Inf)

Attributes

Attribute	Type	Description
data	np.ndarray	The wrapped batch, shape (N, 2). Reading it returns a copy, so mutating the result doesn't affect the Points2D; assigning a new value re-validates it the same way as construction.
shape	tuple[int, ...]	(N, 2), with N resolved to the batch's actual size.
ndim	int	Always 2.
dtype	np.dtype	Always float32.
size	int	Total element count, N * 2.
shape_spec	ClassVar[tuple[int | None, ...]]	Class-level shape contract, (None, 2) — None means the batch size is unconstrained.

Methods

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

Operators

Operation	Behavior
points == other	True only if other is also exactly a Points2D with the same shape and values (NaN counts as equal to NaN). False for anything else.
len(points)	The batch size, N.
points[i]	Not supported — Points2D defines no __getitem__ (confirmed empirically: raises TypeError: 'Points2D' object is not subscriptable). There's no per-row extraction into a Point2D; index .data directly (points.data[i]) and wrap the row in a Point2D yourself if needed.
np.asarray(points)	Returns a copy of data as an np.ndarray; NumPy functions accept a Points2D directly.
points + arr, points - arr, points * arr, points / arr	Not implemented on Points2D itself. A NumPy array operand causes NumPy to coerce points via __array__ and perform plain elementwise arithmetic — the result is a plain np.ndarray, not a Points2D.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("points2d_example", spawn=True)
datatypes.visualize(points2d, entity_path="/points2d", label="Points2D")

Example

"""Demonstrates the Telekinesis Points2D datatype."""

import time

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

from telekinesis import datatypes

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

    # ======================= Create ============================================
    points = [[10.0, 20.0], [30.0, 40.0], [50.0, 60.0]]
    points2d = datatypes.Points2D(points)
    logger.info(f"Created Points2D: {points2d}")

    empty_points2d = datatypes.Points2D(np.empty((0, 2), dtype=np.float32))
    logger.info(f"Created empty Points2D: {empty_points2d}")

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

    # ======================= Operations =========================================
    updated_data = [[70.0, 80.0], [90.0, 100.0], [110.0, 120.0]]
    points2d.data = updated_data
    logger.info(f"Updated Points2D: {points2d}")

    points2d_copy = points2d.copy()
    logger.info(f"Copied Points2D: {points2d_copy}")

    points2d_numpy = points2d.to_numpy(copy=False)
    logger.info(f"NumPy Points2D:\n{points2d_numpy}")

    # Translate by operating on the underlying NumPy array directly.
    translation = [1.0, 1.0]
    translated_data = points2d.data + np.asarray(translation, dtype=np.float32)
    translated_points2d = datatypes.Points2D(translated_data)
    logger.info(f"Translated Points2D: {translated_points2d}")

    numpy_points2d = np.asarray(points2d)
    logger.info(f"NumPy array via __array__:\n{numpy_points2d}")

    # ======================= Visualize =========================================
    rr.init("points2d_example", spawn=True)
    datatypes.visualize(
        points2d,
        entity_path="/points2d/updated",
        label=["Updated Point 1", "Updated Point 2", "Updated Point 3"],
    )
    datatypes.visualize(
        translated_points2d,
        entity_path="/points2d/translated",
        label=["Translated Point 1", "Translated Point 2", "Translated Point 3"],
    )

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


if __name__ == "__main__":
    points2d_example()