Boxes3D

SUMMARY

A batch of axis-aligned bounding boxes in 3D space.

from telekinesis import datatypes
boxes3d = datatypes.Boxes3D([[0, 0, 0, 1, 1, 1], [2, 2, 2, 3, 3, 3]])

API Reference

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

View Reference →

Parameters

Parameter	Type	Default	Description
data	np.ndarray | list | tuple	Required	Batch of box coordinates, each row [cx, cy, cz, width, height, depth] (center point + size, the native CXCYCZWHD format) with shape (N, 6)

Raises

Exception	Condition
TypeError	data can't be converted into a uniform float32 array (e.g. ragged nested lists)
ValueError	data is not rank-2 (e.g. a flat (6,) single box — wrap it as [[...]], or use Box3D)
ValueError	The last axis is not exactly length 6
ValueError	Any element is non-finite (NaN/Inf)
ValueError	Any box's width, height, or depth (data[:, 3:6]) is negative

A zero-sized width/height/depth on any box is allowed but logs a warning (that box's volume will be 0).

Attributes

Attribute	Type	Description
data	np.ndarray	Defensive copy of the underlying (N, 6) array. Reading it returns a copy; writing re-validates the same way as construction.
shape	tuple[int, ...]	(N, 6).
ndim	int	Always 2.
dtype	np.dtype	Always float32.
size	int	N * 6.
shape_spec	tuple[int | None, ...]	Class-level shape spec (None, 6) — None means variable batch size.
centers	np.ndarray, shape (N, 3)	Per-box [cx, cy, cz] — data[:, :3] directly.
dimensions	np.ndarray, shape (N, 3)	Per-box [width, height, depth] (data[:, 3:6]), non-negative.
volumes	np.ndarray, shape (N,)	Per-box width * height * depth.

Methods

Method	Type	Description
Boxes3D.coerce(value)	Boxes3D	Converts array-like data into a Boxes3D. If value is already a Boxes3D, it is returned unchanged; otherwise it goes through the same checks as constructing one directly.
Boxes3D.from_xyzwhd(data)	Boxes3D	Builds a batch from rows of [x_min, y_min, z_min, width, height, depth], converting each one to the native center-based format.
Boxes3D.from_xyzxyz(data)	Boxes3D	Builds a batch from rows of [x_min, y_min, z_min, x_max, y_max, z_max], converting each one to the native center-based format.
as_xyzwhd()	np.ndarray	Returns these boxes as rows of [x_min, y_min, z_min, width, height, depth] instead of the native center-based format.
as_xyzxyz()	np.ndarray	Returns these boxes as rows of [x_min, y_min, z_min, x_max, y_max, z_max] instead of the native center-based format.
to_numpy(copy=True)	np.ndarray	Returns the boxes as a plain array. Pass copy=False for a zero-copy view instead — mutating it mutates the Boxes3D.
copy()	Boxes3D	Returns a new, independent Boxes3D with the same data.

Operators

Operation	Behavior
boxes == other	True only if other is also a Boxes3D with element-equal data (same N, same values). False for anything else.
len(boxes)	Number of boxes, N.
boxes[i] (int)	Returns a Box3D for row i. Negative indices count from the end; out-of-range raises IndexError.
boxes[i:j] (slice)	Returns a new Boxes3D with the selected rows.
boxes[mask] (boolean np.ndarray)	Returns a new Boxes3D with the rows where mask is True. Raises ValueError if the mask isn't a 1-D boolean array of length N.
for box in boxes	Iterates via indexed access (Boxes3D defines __getitem__ but not __iter__); yields one Box3D per row, stopping at the IndexError from an out-of-range index.
np.asarray(boxes)	Returns a copy of data as an np.ndarray; NumPy functions accept a Boxes3D directly.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("boxes3d_example", spawn=True)
datatypes.visualize(boxes3d, entity_path="/boxes3d", label="Boxes3D")

Example

"""Demonstrates the Telekinesis Boxes3D datatype."""

import time

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

from telekinesis import datatypes

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

    # ======================= Create ============================================
    # Boxes3D format is CXCYCZWHD = [[cx, cy, cz, width, height, depth], ...]
    box3d_1 = [[0, 0, 0, 1, 1, 1]]
    box3d_2 = [[2, 2, 2, 3, 3, 3]]
    coords = np.concatenate([box3d_1, box3d_2], axis=0)
    boxes3d = datatypes.Boxes3D(coords)
    logger.info(f"Original Boxes3D: {boxes3d}")

    xyzxyz_coords = [[0, 0, 0, 1, 1, 1], [2, 2, 2, 3, 3, 3]]
    boxes3d_from_xyzxyz = datatypes.Boxes3D.from_xyzxyz(xyzxyz_coords)
    logger.info(f"Boxes3D created from xyzxyz format: {boxes3d_from_xyzxyz}")

    xyzwhd_coords = [[0, 0, 0, 1, 1, 1], [2, 2, 2, 1, 1, 1]]
    boxes3d_from_xyzwhd = datatypes.Boxes3D.from_xyzwhd(xyzwhd_coords)
    logger.info(f"Boxes3D created from xyzwhd format: {boxes3d_from_xyzwhd}")

    # ======================= Inspect ===========================================
    logger.info(f"data={boxes3d.data}")
    logger.info(f"dtype={boxes3d.dtype}")
    logger.info(f"ndim={boxes3d.ndim}")
    logger.info(f"shape={boxes3d.shape}")
    logger.info(f"size={boxes3d.size}")
    logger.info(f"dimensions={boxes3d.dimensions}")
    logger.info(f"volumes={boxes3d.volumes}")
    logger.info(f"centers={boxes3d.centers}")

    # ======================= Operations =========================================
    updated_box = [3, 3, 3, 1, 1, 1]
    data = boxes3d.data
    data[1] = updated_box
    boxes3d.data = data
    logger.info(f"Updated Boxes3D: {boxes3d}")

    xyzxyz_view = boxes3d.as_xyzxyz()
    logger.info(f"Boxes3D converted to xyzxyz format: {xyzxyz_view}")

    xyzwhd_view = boxes3d.as_xyzwhd()
    logger.info(f"Boxes3D converted to xyzwhd format: {xyzwhd_view}")

    boxes3d_copy = boxes3d.copy()
    logger.info(f"Copied Boxes3D: {boxes3d_copy}")

    # Returns the internal data as a NumPy array. If copy=True, returns a copy; otherwise, returns a view.
    boxes3d_numpy = boxes3d.to_numpy(copy=False)
    logger.info(f"NumPy Boxes3D:\n{boxes3d_numpy}")

    numpy_boxes3d = np.asarray(boxes3d)
    logger.info(f"Boxes3D via __array__:\n{numpy_boxes3d}")

    logger.info(f"Number of boxes: {len(boxes3d)}")
    first_box3d = boxes3d[0]
    sub_batch = boxes3d[1:]
    logger.info(f"First box: {first_box3d}")
    logger.info(f"Sub-batch [1:]: {sub_batch}")

    # Translate and scale by operating on the underlying NumPy array directly.
    translation = [2, 3, 1]
    translated_data = boxes3d.data.copy()
    translated_data[:, :3] += translation
    translated_boxes3d = datatypes.Boxes3D(translated_data)
    logger.info(f"Translated Boxes3D: {translated_boxes3d}")

    scale_factors = [0.5, 0.5, 0.5]
    scaled_data = boxes3d.data.copy()
    scaled_data[:, 3:] *= np.asarray(scale_factors, dtype=np.float32)
    scaled_boxes3d = datatypes.Boxes3D(scaled_data)
    logger.info(f"Scaled Boxes3D: {scaled_boxes3d}")

    # ======================= Visualize =========================================
    rr.init("boxes3d_example", spawn=True)
    datatypes.visualize(
        boxes3d, entity_path="/boxes3d/updated", label=["Updated Box3D 1", "Updated Box3D 2"]
    )
    datatypes.visualize(
        translated_boxes3d,
        entity_path="/boxes3d/translated",
        label=["Translated Box3D 1", "Translated Box3D 2"],
    )
    datatypes.visualize(
        scaled_boxes3d,
        entity_path="/boxes3d/scaled",
        label=["Scaled Box3D 1", "Scaled Box3D 2"],
    )

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


if __name__ == "__main__":
    boxes3d_example()