Point3D

SUMMARY

A point in 3D space.

from telekinesis import datatypes
point3d = datatypes.Point3D([1.0, 2.0, 3.0])

API Reference

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

View Reference →

Parameters

Parameter	Type	Default	Description
data	np.ndarray | list | tuple	Required	Array-like input, shape (3,): [x, y, z].

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 1-D, its length isn't 3, or it contains a non-finite value (NaN/Inf)

Attributes

Attribute	Type	Description
data	np.ndarray	The wrapped point, shape (3,). Reading it returns a copy, so mutating the result doesn't affect the Point3D; 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.
shape_spec	ClassVar[tuple[int, ...]]	Class-level shape contract, (3,), inherited from Vector3D. Same for every Point3D instance.

Methods

Method	Type	Description
Point3D.coerce(value)	Point3D	Converts array-like data into a Point3D. Accepts a np.ndarray, list, or tuple of shape (3,): [x, y, z]. If value is already a Point3D, it is returned unchanged. A Vector3D with the same values is not accepted — pass its raw array instead.
to_numpy(copy=True)	np.ndarray	Returns the point as a plain array, shape (3,). 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 Point3D.
copy()	Point3D	Returns a new, independent Point3D with the same data.

Operators

Operation	Behavior
point == other	True only if other is also exactly a Point3D (not a Vector3D or any other type, even with identical coordinates) with equal values (NaN counts as equal to NaN). False for anything else.
len(point)	Always 3 — the length of axis 0 of the underlying (3,) array, not a "number of points" count.
np.asarray(point)	Returns a copy of data as an np.ndarray; NumPy functions accept a Point3D directly.
point + arr, point - arr, point * arr, point / arr	Not implemented on Point3D itself (no __add__/__array_ufunc__). With a NumPy array operand, NumPy coerces the Point3D via __array__ and performs plain elementwise arithmetic — the result is a plain np.ndarray, not a Point3D.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("point3d_example", spawn=True)
datatypes.visualize(point3d, entity_path="/point3d", label="Point3D")

Example

"""Demonstrates the Telekinesis Point3D datatype."""

import time

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

from telekinesis import datatypes

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

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

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

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

    point3d_copy = point3d.copy()
    logger.info(f"Copied Point3D: {point3d_copy}")

    point3d_numpy = point3d.to_numpy(copy=False)
    logger.info(f"NumPy Point3D: {point3d_numpy}")

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

    numpy_point3d = np.asarray(point3d)
    logger.info(f"NumPy array via __array__: {numpy_point3d}")

    # ======================= Visualize =========================================
    rr.init("point3d_example", spawn=True)
    datatypes.visualize(point3d, entity_path="/point3d/updated", label="Updated Point3D")
    datatypes.visualize(
        translated_point3d, entity_path="/point3d/translated", label="Translated Point3D"
    )

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


if __name__ == "__main__":
    point3d_example()