OrientedBox3D

SUMMARY

An oriented bounding box in 3D space.

python

from telekinesis import datatypes
oriented_box3d = datatypes.OrientedBox3D([0.5, 0.5, 0.5, 1.0, 1.0, 1.0, 0.0, 0.0, 0.0])

Parameters

Parameter	Type	Default	Description
`data`	`np.ndarray \| list \| tuple`	Required	Box coordinates `[cx, cy, cz, width, height, depth, roll_deg, pitch_deg, yaw_deg]` (center, size, and Euler-XYZ rotation in degrees).

Raises

Exception	Condition
`TypeError`	`data` can't be converted into a uniform float32 array (e.g. ragged nested lists)
`ValueError`	`data` is not rank-1 (e.g. a `(N, 9)` batch — use OrientedBoxes3D instead)
`ValueError`	`data` does not have exactly 9 elements
`ValueError`	Any element is non-finite (`NaN`/`Inf`)
`ValueError`	`width`, `height`, or `depth` (`data[3:6]`) is negative

A zero-sized width/height/depth is allowed but logs a warning (volume will be 0). roll_deg/pitch_deg/yaw_deg are otherwise unconstrained — any finite degree values are accepted.

Attributes

Attribute	Type	Description
`data`	`np.ndarray`	Defensive copy of the underlying `(9,)` array `[cx, cy, cz, width, height, depth, roll_deg, pitch_deg, yaw_deg]`. Reading it returns a copy; writing re-validates the same way as construction.
`shape`	`tuple[int, ...]`	Always `(9,)`.
`ndim`	`int`	Always `1`.
`dtype`	`np.dtype`	Always `float32`.
`size`	`int`	Always `9`.
`shape_spec`	`tuple[int, ...]`	Class-level shape spec `(9,)`.
`center`	`np.ndarray`	`[cx, cy, cz]` — `data[:3]` directly.
`dimensions`	`np.ndarray`	`[width, height, depth]` (`data[3:6]`), non-negative, unaffected by rotation.
`rotation`	`np.ndarray`, shape `(3,)`	`[roll_deg, pitch_deg, yaw_deg]` — `data[6:9]`, Euler-XYZ rotation angles in degrees.
`volume`	`np.ndarray` (scalar)	`width * height * depth` (rotation-invariant).

Methods

Method	Type	Description
`OrientedBox3D.coerce(value)`	`OrientedBox3D`	Converts array-like data into an `OrientedBox3D`. Accepts a `[cx, cy, cz, width, height, depth, roll_deg, pitch_deg, yaw_deg]` array-like of shape `(9,)`, checked the same way as the constructor. If `value` is already an `OrientedBox3D`, it is returned unchanged.
`OrientedBox3D.from_xyzwhd(data)`	`OrientedBox3D`	Builds an `OrientedBox3D` from `[x_min, y_min, z_min, width, height, depth, roll_deg, pitch_deg, yaw_deg]` coordinates (shape `(9,)`), converting the position and size into the native center-based format. The rotation angles pass through unchanged.
`OrientedBox3D.from_xyzxyz(data)`	`OrientedBox3D`	Builds an `OrientedBox3D` from `[x_min, y_min, z_min, x_max, y_max, z_max, roll_deg, pitch_deg, yaw_deg]` corner coordinates (shape `(9,)`), converting them into the native center-based format. The rotation angles pass through unchanged.
`as_xyzwhd()`	`np.ndarray`	Returns this box's coordinates as `[x_min, y_min, z_min, width, height, depth, roll_deg, pitch_deg, yaw_deg]`. The rotation angles pass through unchanged.
`as_xyzxyz()`	`np.ndarray`	Returns this box's coordinates as `[x_min, y_min, z_min, x_max, y_max, z_max, roll_deg, pitch_deg, yaw_deg]`. The rotation angles pass through unchanged.
`to_numpy(copy=True)`	`np.ndarray`	Returns the box's 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 `OrientedBox3D`.
`copy()`	`OrientedBox3D`	Returns a new, independent `OrientedBox3D` with the same coordinates.

Operators

Operation	Behavior
`box == other`	`True` only if `other` is also an `OrientedBox3D` with element-equal `data`. `False` for anything else.
`len(box)`	Returns `9` — the length of the coordinate vector, not a box count (a single box is conceptually one item).
`box[i]`	Raises `TypeError` — `OrientedBox3D` defines no `__getitem__`, so a single box isn't indexable like a batch. Use `.data[i]` for raw coordinate access instead.
`for x in box`	Raises `TypeError` — with no `__getitem__`/`__iter__`, a single `OrientedBox3D` isn't iterable.
`np.asarray(box)`	Returns a copy of `data` as an `np.ndarray`; NumPy functions accept an `OrientedBox3D` directly.

Visualization

python

import rerun as rr

# Your code block
# ....

rr.init("oriented_box3d_example", spawn=True)
datatypes.visualize(oriented_box3d, entity_path="/oriented_box3d", label="OrientedBox3D")

Example

python

"""Demonstrates the Telekinesis OrientedBox3D datatype."""

import time

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

from telekinesis import datatypes

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

    # ======================= Create ============================================
    # OrientedBox3D format is CXCYCZWHD = [cx, cy, cz, width, height, depth]
    # + rotation [roll_deg, pitch_deg, yaw_deg] (Euler XYZ, in degrees)
    coords = [0.5, 0.5, 0.5, 1.0, 1.0, 1.0, 0.0, 0.0, 0.0]
    oriented_box3d = datatypes.OrientedBox3D(coords)
    logger.info(f"Created OrientedBox3D: {oriented_box3d}")

    xyzxyz_coords = [0.5, 1.0, 1.5, 3.5, 3.0, 2.5, 0.0, 0.0, 0.0]
    oriented_box3d_from_xyzxyz = datatypes.OrientedBox3D.from_xyzxyz(xyzxyz_coords)
    logger.info(f"OrientedBox3D created from xyzxyz format: {oriented_box3d_from_xyzxyz}")

    xyzwhd_coords = [0.5, 1.0, 1.5, 3.0, 2.0, 1.0, 0.0, 0.0, 0.0]
    oriented_box3d_from_xyzwhd = datatypes.OrientedBox3D.from_xyzwhd(xyzwhd_coords)
    logger.info(f"OrientedBox3D created from xyzwhd format: {oriented_box3d_from_xyzwhd}")

    # ======================= Inspect ===========================================
    logger.info(f"data={oriented_box3d.data}")
    logger.info(f"dtype={oriented_box3d.dtype}")
    logger.info(f"ndim={oriented_box3d.ndim}")
    logger.info(f"shape={oriented_box3d.shape}")
    logger.info(f"size={oriented_box3d.size}")
    logger.info(f"center={oriented_box3d.center}")
    logger.info(f"dimensions={oriented_box3d.dimensions}")
    logger.info(f"volume={oriented_box3d.volume}")
    logger.info(f"rotation={oriented_box3d.rotation}")

    # ======================= Operations =========================================
    updated_coords = [2.0, 2.0, 2.0, 3.0, 1.0, 1.0, 0.0, 0.0, 0.0]
    oriented_box3d.data = updated_coords
    logger.info(f"Updated OrientedBox3D: {oriented_box3d}")

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

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

    oriented_box3d_copy = oriented_box3d.copy()
    logger.info(f"Copied OrientedBox3D: {oriented_box3d_copy}")

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

    # Translate, scale, and rotate by operating on the underlying NumPy array directly.
    translation = [1.0, 1.0, 1.0]
    translated_data = oriented_box3d.data.copy()
    translated_data[:3] += translation
    translated_oriented_box3d = datatypes.OrientedBox3D(translated_data)
    logger.info(f"Translated OrientedBox3D: {translated_oriented_box3d}")

    scale_factors = [1.5, 1.5, 1.5]
    scaled_data = oriented_box3d.data.copy()
    scaled_data[3:6] *= np.asarray(scale_factors, dtype=np.float32)
    scaled_oriented_box3d = datatypes.OrientedBox3D(scaled_data)
    logger.info(f"Scaled OrientedBox3D: {scaled_oriented_box3d}")

    # `rotation` stores Euler-XYZ degrees natively, so a rotation delta is
    # applied by adding directly to the [roll_deg, pitch_deg, yaw_deg] slice.
    rotation_delta_deg = [0.0, 0.0, 90.0]
    rotated_data = oriented_box3d.data.copy()
    rotated_data[6:9] += np.asarray(rotation_delta_deg, dtype=np.float32)
    rotated_oriented_box3d = datatypes.OrientedBox3D(rotated_data)
    logger.info(f"Rotated OrientedBox3D: {rotated_oriented_box3d}")

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

    # ======================= Visualize =========================================
    rr.init("oriented_box3d_example", spawn=True)
    datatypes.visualize(oriented_box3d, entity_path="/oriented_box3d/updated", label="Updated Oriented Box3D")
    datatypes.visualize(
        translated_oriented_box3d,
        entity_path="/oriented_box3d/translated",
        label="Translated Oriented Box3D",
    )
    datatypes.visualize(
        scaled_oriented_box3d, entity_path="/oriented_box3d/scaled", label="Scaled Oriented Box3D"
    )
    datatypes.visualize(
        rotated_oriented_box3d, entity_path="/oriented_box3d/rotated", label="Rotated Oriented Box3D"
    )

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


if __name__ == "__main__":
    oriented_box3d_example()

OrientedBox3D ​

Parameters ​

Raises ​

Attributes ​

Methods ​

Operators ​

Visualization ​

Example ​

OrientedBox3D

Parameters

Raises

Attributes

Methods

Operators

Visualization

Example