OrientedBoxes2D

SUMMARY

A batch of oriented bounding boxes in 2D space.

from telekinesis import datatypes
oriented_boxes2d = datatypes.OrientedBoxes2D([[0.5, 0.5, 0.5, 0.5, 30.0], [1.0, 1.0, 1.0, 1.0, 15.0]])

API Reference

Complete API documentation for OrientedBoxes2D, 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, width, height, yaw_deg] (center, size, and yaw rotation in degrees); shape (N, 5).

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 (5,) single box — wrap it as [[...]], or use OrientedBox2D)
ValueError	The last axis is not exactly length 5
ValueError	Any element is non-finite (NaN/Inf)
ValueError	Any box's width or height (data[:, 2], data[:, 3]) is negative

A zero-sized width/height on any box is allowed but logs a warning (that box's area will be 0). yaw_deg is otherwise unconstrained per box.

Attributes

Attribute	Type	Description
data	np.ndarray	Defensive copy of the underlying (N, 5) array. Reading it returns a copy; writing re-validates the same way as construction.
shape	tuple[int, ...]	(N, 5).
ndim	int	Always 2.
dtype	np.dtype	Always float32.
size	int	N * 5.
shape_spec	tuple[int | None, ...]	Class-level shape spec (None, 5) — None means variable batch size.
centers	np.ndarray, shape (N, 2)	Per-box [cx, cy] — data[:, :2] directly.
dimensions	np.ndarray, shape (N, 2)	Per-box [width, height] (data[:, 2:4]), non-negative, unaffected by rotation.
rotations	np.ndarray, shape (N, 1)	Per-box [yaw_deg] (data[:, 4:5]), the yaw rotation in degrees.
areas	np.ndarray, shape (N,)	Per-box width * height (rotation-invariant).

Methods

Method	Type	Description
OrientedBoxes2D.coerce(value)	OrientedBoxes2D	Converts array-like data into an OrientedBoxes2D. Accepts an (N, 5) array-like, one [cx, cy, width, height, yaw_deg] row per box, checked the same way as the constructor. If value is already an OrientedBoxes2D, it is returned unchanged.
OrientedBoxes2D.from_xywh(data)	OrientedBoxes2D	Builds an OrientedBoxes2D from rows of [x_min, y_min, width, height, yaw_deg] (shape (N, 5)), converting each box's position and size into the native center-based format. The yaw_deg column passes through unchanged.
OrientedBoxes2D.from_xyxy(data)	OrientedBoxes2D	Builds an OrientedBoxes2D from rows of [x_min, y_min, x_max, y_max, yaw_deg] (shape (N, 5)), converting each box's corner coordinates into the native center-based format. The yaw_deg column passes through unchanged.
as_xywh()	np.ndarray	Returns these boxes' coordinates as rows of [x_min, y_min, width, height, yaw_deg]. The yaw_deg column passes through unchanged.
as_xyxy()	np.ndarray	Returns these boxes' coordinates as rows of [x_min, y_min, x_max, y_max, yaw_deg]. The yaw_deg column passes through unchanged.
to_numpy(copy=True)	np.ndarray	Returns the boxes' coordinates 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 OrientedBoxes2D.
copy()	OrientedBoxes2D	Returns a new, independent OrientedBoxes2D with the same coordinates.

Operators

Operation	Behavior
boxes == other	True only if other is also an OrientedBoxes2D with element-equal data (same N, same values). False for anything else.
len(boxes)	Number of boxes, N.
boxes[i] (int)	Returns an OrientedBox2D for row i. Negative indices count from the end; out-of-range raises IndexError.
boxes[i:j] (slice)	Returns a new OrientedBoxes2D with the selected rows.
boxes[mask] (boolean np.ndarray)	Returns a new OrientedBoxes2D 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 (OrientedBoxes2D defines __getitem__ but not __iter__); yields one OrientedBox2D 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 an OrientedBoxes2D directly.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("oriented_boxes2d_example", spawn=True)
datatypes.visualize(oriented_boxes2d, entity_path="/oriented_boxes2d", label="OrientedBoxes2D")

Example

"""Demonstrates the Telekinesis OrientedBoxes2D datatype."""

import time

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

from telekinesis import datatypes

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

    # ======================= Create ============================================
    # OrientedBoxes2D format is CXCYWH = [[cx, cy, width, height], ...]
    # + rotation column [yaw_deg]
    oriented_box2d_1 = [0.5, 0.5, 0.5, 0.5, 30.0]
    oriented_box2d_2 = [1.0, 1.0, 1.0, 1.0, 15.0]
    oriented_boxes2d = datatypes.OrientedBoxes2D([oriented_box2d_1, oriented_box2d_2])
    logger.info(f"Created OrientedBoxes2D: {oriented_boxes2d}")

    xyxy_coords = [[1.0, 1.5, 3.5, 3.0, 60.0], [2.0, 2.5, 4.5, 4.0, 30.0]]
    oriented_boxes2d_from_xyxy = datatypes.OrientedBoxes2D.from_xyxy(xyxy_coords)
    logger.info(f"OrientedBoxes2D created from xyxy format: {oriented_boxes2d_from_xyxy}")

    xywh_coords = [[1.0, 1.5, 2.5, 1.5, 60.0], [2.0, 2.5, 2.5, 1.5, 30.0]]
    oriented_boxes2d_from_xywh = datatypes.OrientedBoxes2D.from_xywh(xywh_coords)
    logger.info(f"OrientedBoxes2D created from xywh format: {oriented_boxes2d_from_xywh}")

    # ======================= Inspect ===========================================
    logger.info(f"data={oriented_boxes2d.data}")
    logger.info(f"dtype={oriented_boxes2d.dtype}")
    logger.info(f"ndim={oriented_boxes2d.ndim}")
    logger.info(f"shape={oriented_boxes2d.shape}")
    logger.info(f"size={oriented_boxes2d.size}")
    logger.info(f"length={len(oriented_boxes2d)}")
    logger.info(f"centers={oriented_boxes2d.centers}")
    logger.info(f"dimensions={oriented_boxes2d.dimensions}")
    logger.info(f"areas={oriented_boxes2d.areas}")
    logger.info(f"rotations={oriented_boxes2d.rotations}")

    # ======================= Operations =========================================
    updated_data = [
        [2.0, 2.0, 1.5, 2.0, 60.0],
        [3.0, 3.0, 2.0, 2.5, 30.0],
    ]
    oriented_boxes2d.data = updated_data
    logger.info(f"Updated OrientedBoxes2D: {oriented_boxes2d}")

    xyxy_view = oriented_boxes2d.as_xyxy()
    logger.info(f"OrientedBoxes2D converted to xyxy format: {xyxy_view}")

    xywh_view = oriented_boxes2d.as_xywh()
    logger.info(f"OrientedBoxes2D converted to xywh format: {xywh_view}")

    first_oriented_box2d = oriented_boxes2d[0]
    logger.info(f"First OrientedBox2D (index 0): {first_oriented_box2d}")

    sub_batch = oriented_boxes2d[1:]
    logger.info(f"Sub-batch of OrientedBoxes2D [1:]: {sub_batch}")

    oriented_boxes2d_copy = oriented_boxes2d.copy()
    logger.info(f"Copied OrientedBoxes2D: {oriented_boxes2d_copy}")

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

    # Translate and rotate by operating on the underlying NumPy array directly.
    translation = [1.0, 1.0]
    translated_data = oriented_boxes2d.data.copy()
    translated_data[:, :2] += translation
    translated_oriented_boxes2d = datatypes.OrientedBoxes2D(translated_data)
    logger.info(f"Translated OrientedBoxes2D: {translated_oriented_boxes2d}")

    rotation_delta_deg = 15.0
    rotated_data = oriented_boxes2d.data.copy()
    rotated_data[:, 4] += rotation_delta_deg
    rotated_oriented_boxes2d = datatypes.OrientedBoxes2D(rotated_data)
    logger.info(f"Rotated OrientedBoxes2D: {rotated_oriented_boxes2d}")

    # NumPy interop: rank boxes by area (largest first) using the areas property.
    order = np.argsort(-oriented_boxes2d.areas)
    largest_first = datatypes.OrientedBoxes2D(oriented_boxes2d.data[order])
    logger.info(f"OrientedBoxes2D ranked by area (largest first): {largest_first.areas}")

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

    # ======================= Visualize =========================================
    rr.init("oriented_boxes2d_example", spawn=True)
    datatypes.visualize(
        oriented_boxes2d,
        entity_path="/oriented_boxes2d/updated",
        label=["Updated Oriented Box2D 1", "Updated Oriented Box2D 2"],
    )
    datatypes.visualize(
        translated_oriented_boxes2d,
        entity_path="/oriented_boxes2d/translated",
        label=["Translated Oriented Box2D 1", "Translated Oriented Box2D 2"],
    )
    datatypes.visualize(
        rotated_oriented_boxes2d,
        entity_path="/oriented_boxes2d/rotated",
        label=["Rotated Oriented Box2D 1", "Rotated Oriented Box2D 2"],
    )

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


if __name__ == "__main__":
    oriented_boxes2d_example()