`tlc.data_types.bounding_boxes`¶

Defines representations of axis-aligned bounding boxes in 3LC.

Module Contents¶

Classes¶

Class	Description
`BoundingBoxes2D`	Container for 2D axis-aligned bounding boxes.
`BoundingBoxes3D`	Container for 3D axis-aligned bounding boxes.

API¶

class BoundingBoxes2D¶

Bases: tlc.data_types._geometry_base.Geometry2DBase

Container for 2D axis-aligned bounding boxes.

Storage: (N, 4) array with [x_min, y_min, x_max, y_max] per box. Serialization is handled by the bounding_boxes_2d sample type.

Objects can be created in two ways:

Direct construction: Pass all data at once.
Build incrementally: Use create_empty() and add_instance().

Example:

import numpy as np

# Direct construction
bounding_boxes = BoundingBoxes2D(
    bounding_boxes=np.array([
        [10, 10, 100, 100],
        [50, 50, 150, 150],
        [200, 100, 300, 250],
    ], dtype=np.float32),
    labels=[0, 1, 0],
    confidences=[0.95, 0.88, 0.92],
    image_width=640,
    image_height=480,
)

# Build incrementally
bounding_boxes = BoundingBoxes2D.create_empty(image_width=640, image_height=480)
bounding_boxes.add_instance(bounding_box=[10, 20, 100, 120], label=0, confidence=0.95)

# COCO / YOLO input — converted to xyxy in __post_init__
bounding_boxes = BoundingBoxes2D(
    bounding_boxes=coco_xywh, bounding_box_format="xywh", image_width=640, image_height=480,
)

# YOLO normalized cxywh — denormalized to absolute xyxy
bounding_boxes = BoundingBoxes2D(
    bounding_boxes=yolo_cxywh, bounding_box_format="cxywh", normalized=True,
    image_width=640, image_height=480,
)

# Serialization — convert to/from 3LC Table row format
row = bounding_boxes.to_row()
bounding_boxes = BoundingBoxes2D.from_row(row)

Add a single bounding box instance to the object.

Parameters:

bounding_box – Bounding box in xyxy format [x_min, y_min, x_max, y_max]. Can be provided as a list, tuple, or numpy array with 4 elements.
label – Optional integer class label for this instance.
confidence – Optional confidence score for this instance.
per_instance_extras – Optional dictionary of per-instance attributes (e.g., {"track_id": 42, "area": 1500}). Values should be scalars. The first call establishes which keys are expected; subsequent calls must provide the same keys.

Raises:

ValueError – If the bounding_box does not have exactly 4 elements.

Example:

bounding_boxes = BoundingBoxes2D.create_empty(image_width=640, image_height=480)
bounding_boxes.add_instance(bounding_box=[10, 20, 100, 120], label=0, confidence=0.95)
bounding_boxes.add_instance(
    bounding_box=[200, 150, 350, 300],
    label=1,
    confidence=0.88,
    per_instance_extras={"track_id": 42},
)

bounding_box_format: InitVar['xyxy' | 'xywh' | 'cxywh'] = xyxy¶

Format of the input bounding_boxes array. Storage is always "xyxy" regardless.

Use "xywh" for COCO-style [x_min, y_min, width, height] or "cxywh" for YOLO-style [cx, cy, width, height].

bounding_boxes: ndarray[tuple[int, int], dtype[numpy.float32]] = field(...)¶

A numpy array of shape (num_instances, 4). Always stored as [x_min, y_min, x_max, y_max] (xyxy).

The constructor accepts other formats via bounding_box_format= and normalizes to xyxy in __post_init__. Direct attribute assignment (bb.bounding_boxes = ...) bypasses normalization — pre-convert with xywh_to_xyxy / cxywh_to_xyxy from tlc.data_types._bb_conversions.

property bounding_boxes_cxywh: ndarray¶

Return the bounding boxes in centered xywh format.

Converts from the internal xyxy format [x_min, y_min, x_max, y_max] to centered xywh format [center_x, center_y, width, height], which is commonly used by YOLO-style frameworks.

Returns:: A numpy array of shape (num_instances, 4) with bounding boxes in [cx, cy, w, h] format.

property bounding_boxes_xywh: ndarray¶

Return the bounding boxes in xywh format.

Converts from the internal xyxy format [x_min, y_min, x_max, y_max] to xywh format [x_min, y_min, width, height], which is commonly used by some training frameworks (e.g. COCO).

Returns:: A numpy array of shape (num_instances, 4) with bounding boxes in [x, y, width, height] format.

Create an empty BoundingBoxes2D object to build up incrementally.

Useful for creating bounding box data from scratch by adding instances one at a time using add_instance().

Parameters:

image_width – Convenience parameter, sets x_max = x_min + image_width.
image_height – Convenience parameter, sets y_max = y_min + image_height.
x_min – Minimum x coordinate (optional).
y_min – Minimum y coordinate (optional).
x_max – Maximum x coordinate (optional, provide this OR image_width if specifying bounds).
y_max – Maximum y coordinate (optional, provide this OR image_height if specifying bounds).

Returns:

An empty BoundingBoxes2D object ready for adding instances.

Example:

bounding_boxes = BoundingBoxes2D.create_empty(image_width=640, image_height=480)
bounding_boxes.add_instance(bounding_box=[10, 20, 100, 120], label=0, confidence=0.95)

classmethod from_legacy_row( row: Mapping[str, Any], schema: Schema, ) → BoundingBoxes2D¶

Construct a BoundingBoxes2D from a legacy bb_list-format row.

Bridges old-format table data (bb_list with x0/y0/x1/y1 dicts) to the new geometry-based representation. The coordinate format (XYXY, XYWH, centered-XYWH) and normalization are auto-detected from the schema’s number roles.

Parameters:

row – Row dict with keys "image_width", "image_height", "bb_list".
schema – The column-level schema (must contain a "bb_list" sub-schema whose number roles determine the coordinate format).

Returns:

A BoundingBoxes2D in absolute XYXY format with bounds set from image dimensions.

image_height: InitVar[float | None] = None¶: Convenience parameter: sets y_max = (y_min or 0) + image_height.

image_width: InitVar[float | None] = None¶: Convenience parameter: sets x_max = (x_min or 0) + image_width.

normalized: InitVar[bool] = False¶

Whether the input bounding_boxes coordinates are normalized to [0, 1].

When True, coordinates are denormalized to absolute pixel values using the image dimensions derived from bounds (x_max/y_max). Bounds must be set. Applied after bounding_box_format conversion.

property num_instances: int¶: Return the number of bounding box instances.

classmethod schema( classes: str | Sequence[str] | Sequence[dict[str, str]] | Sequence[MapElement] | dict[float, str] | dict[int, str] | dict[float, MapElement] | dict[int, MapElement] | None = None, *, include_per_instance_confidence: bool = False, x_min_default: float | None = None, y_min_default: float | None = None, x_max_default: float | None = None, y_max_default: float | None = None, display_name: str = '', description: str = '', writable: bool = True, default_visible: bool = True, display_importance: float = 0, per_instance_schemas: dict[str, Schema] | None = None, ) → Schema¶

Build the column Schema describing 2D axis-aligned bounding boxes.

Parameters:

classes – A class map (list of names, dict of numeric keys to names or MapElements, or a single class name) for per-instance labels, or None to skip labels.
include_per_instance_confidence – Whether to add a per-instance confidence field.
x_min_default – Default scene x_min bound.
y_min_default – Default scene y_min bound.
x_max_default – Default scene x_max bound.
y_max_default – Default scene y_max bound.
display_name – Column display name in the Dashboard.
description – Column description.
writable – Whether the column is editable in the Dashboard.
default_visible – Whether the column is visible by default.
display_importance – Ordering weight for column display.
per_instance_schemas – Additional per-instance schemas (advanced).

Returns:

A column schema describing the serialized form of this class.

class BoundingBoxes3D¶

Bases: tlc.data_types._geometry_base.Geometry3DBase

Container for 3D axis-aligned bounding boxes.

Storage: (N, 6) array with [x_min, y_min, z_min, x_max, y_max, z_max] per box. Serialization is handled by the bounding_boxes_3d sample type.

Objects can be created in two ways:

Direct construction: Pass all data at once.
Build incrementally: Use create_empty() and add_instance().

Example:

import numpy as np

# Direct construction
bounding_boxes = BoundingBoxes3D(
    bounding_boxes=np.array([
        [0, 0, 0, 1, 1, 1],
        [2, 2, 2, 4, 4, 4],
        [5, 5, 5, 8, 8, 8],
    ], dtype=np.float32),
    labels=[0, 1, 0],
    confidences=[0.95, 0.88, 0.92],
    x_max=10.0,
    y_max=10.0,
    z_max=10.0,
)

# Build incrementally
bounding_boxes = BoundingBoxes3D.create_empty(x_max=10, y_max=10, z_max=10)
bounding_boxes.add_instance(bounding_box=[0, 0, 0, 1, 2, 3], label=0, confidence=0.95)

# Top-corner + size input — converted to xyzxyz in __post_init__
bounding_boxes = BoundingBoxes3D(
    bounding_boxes=corner_size, bounding_box_format="xyzwhd", x_max=10, y_max=10, z_max=10,
)

# Normalized input — denormalized to absolute coordinates
bounding_boxes = BoundingBoxes3D(
    bounding_boxes=norm_xyzxyz, normalized=True, x_max=10, y_max=10, z_max=10,
)

# Serialization — convert to/from 3LC Table row format
row = bounding_boxes.to_row()
bounding_boxes = BoundingBoxes3D.from_row(row)

Add a single bounding box instance to the object.

Parameters:

bounding_box – Bounding box in format [x_min, y_min, z_min, x_max, y_max, z_max]. Can be provided as a list, tuple, or numpy array with 6 elements.
label – Optional integer class label for this instance.
confidence – Optional confidence score for this instance.
per_instance_extras – Optional dictionary of per-instance attributes (e.g., {"track_id": 42, "volume": 1500}). Values should be scalars. The first call establishes which keys are expected; subsequent calls must provide the same keys.

Raises:

ValueError – If the bounding_box does not have exactly 6 elements.

bounding_box_format: InitVar['xyzxyz' | 'xyzwhd'] = xyzxyz¶

Format of the input bounding_boxes array. Storage is always "xyzxyz" regardless.

Use "xyzwhd" for [x_min, y_min, z_min, width, height, depth] (top-corner + size).

bounding_boxes: ndarray[tuple[int, int], dtype[numpy.float32]] = field(...)¶: A numpy array of shape (num_instances, 6). Always stored as [x_min, y_min, z_min, x_max, y_max, z_max] (xyzxyz). Use bounding_box_format= to supply other layouts at construction time.

property bounding_boxes_xyzwhd: ndarray¶

Return the bounding boxes in xyzwhd format.

Converts from the internal format [x_min, y_min, z_min, x_max, y_max, z_max] to [x_min, y_min, z_min, width, height, depth] format.

Returns:: A numpy array of shape (num_instances, 6) with bounding boxes in [x, y, z, w, h, d] format.

Create an empty BoundingBoxes3D object to build up incrementally.

Useful for creating bounding box data from scratch by adding instances one at a time using add_instance().

Parameters:

x_min – Minimum x coordinate (optional).
y_min – Minimum y coordinate (optional).
z_min – Minimum z coordinate (optional).
x_max – Maximum x coordinate (optional).
y_max – Maximum y coordinate (optional).
z_max – Maximum z coordinate (optional).

Returns:

An empty BoundingBoxes3D object ready for adding instances.

image_height: InitVar[float | None] = None¶: Convenience parameter: sets y_max = (y_min or 0) + image_height.

image_width: InitVar[float | None] = None¶: Convenience parameter: sets x_max = (x_min or 0) + image_width.

normalized: InitVar[bool] = False¶

Whether the input bounding_boxes coordinates are normalized to [0, 1].

When True, coordinates are denormalized to absolute values using the dimensions derived from bounds (x_max/y_max/z_max). Bounds must be set. Applied after bounding_box_format conversion.

property num_instances: int¶: Return the number of bounding box instances.

Build the column Schema describing 3D axis-aligned bounding boxes.

Parameters:

classes – A class map (list of names, dict of numeric keys to names or MapElements, or a single class name) for per-instance labels, or None to skip labels.
include_per_instance_confidence – Whether to add a per-instance confidence field.
x_min_default – Default scene x_min bound.
y_min_default – Default scene y_min bound.
z_min_default – Default scene z_min bound.
x_max_default – Default scene x_max bound.
y_max_default – Default scene y_max bound.
z_max_default – Default scene z_max bound.
display_name – Column display name in the Dashboard.
description – Column description.
writable – Whether the column is editable in the Dashboard.
default_visible – Whether the column is visible by default.
display_importance – Ordering weight for column display.
per_instance_schemas – Additional per-instance schemas (advanced).

Returns:

A column schema describing the serialized form of this class.

tlc.data_types.bounding_boxes¶

Module Contents¶

Classes¶

API¶

`tlc.data_types.bounding_boxes`¶