`tlc.data_types.obb`¶

Defines representations of oriented bounding boxes in 3LC.

Module Contents¶

Classes¶

Class	Description
`OrientedBoundingBoxes2D`	Container for 2D oriented bounding boxes.
`OrientedBoundingBoxes3D`	Container for 3D oriented bounding boxes.

API¶

class OrientedBoundingBoxes2D¶

Bases: tlc.data_types._geometry_base.Geometry2DBase

Container for 2D oriented bounding boxes.

Storage: (N, 5) array with [x_center, y_center, width, height, rotation] per box. Serialization is handled by the oriented_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
obbs = OrientedBoundingBoxes2D(
    obbs=np.array([[50, 50, 80, 60, 0.5], [100, 100, 40, 30, 1.0]], dtype=np.float32),
    labels=[0, 1],
    x_max=640.0,
    y_max=480.0,
)

# Build incrementally
obbs = OrientedBoundingBoxes2D.create_empty(image_width=640, image_height=480)
obbs.add_instance(
    obb=[320, 240, 100, 50, 0.785],  # center_x, center_y, width, height, rotation
    label=0,
    confidence=0.95,
)

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

Add a single oriented bounding box instance to the object.

Parameters:

obb – Oriented bounding box in the format [x_center, y_center, width, height, rotation]. Rotation should be in radians in the range [0, pi/2). Can be provided as a list, tuple, or numpy array.
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 OBB does not have exactly 5 elements.

Example:

obbs = OrientedBoundingBoxes2D.create_empty(image_width=640, image_height=480)
obbs.add_instance(obb=[320, 240, 100, 50, 0.785], label=0, confidence=0.95)
obbs.add_instance(obb=[200, 150, 80, 60, 1.571], label=1, confidence=0.88)

Create an empty OrientedBoundingBoxes2D object to build up incrementally.

Useful for creating OBB 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 OrientedBoundingBoxes2D object ready for adding instances.

Example:

obbs = OrientedBoundingBoxes2D.create_empty(image_width=640, image_height=480)
obbs.add_instance(
    obb=[320, 240, 100, 50, 0.785],
    label=0,
    confidence=0.95,
    per_instance_extras={"track_id": 42, "quality_score": 0.87},
)

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 obbs spatial coordinates are normalized to [0, 1].

When True, center (cx, cy) and size (w, h) are denormalized to absolute pixel values using the image dimensions derived from bounds. Rotation is not affected. Bounds must be set.

property num_instances: int¶: Return the number of OBB instances.

obbs: ndarray[tuple[int, int], dtype[numpy.float32]] = field(...)¶: A numpy array of shape (num_instances, 5) with [x_center, y_center, width, height, rotation] per instance.

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 oriented bounding boxes.

Parameters:

classes – A class map 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 OrientedBoundingBoxes3D¶

Bases: tlc.data_types._geometry_base.Geometry3DBase

Container for 3D oriented bounding boxes.

Storage: (N, 9) array with [cx, cy, cz, sx, sy, sz, yaw, pitch, roll] per box. Serialization is handled by the oriented_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
obbs = OrientedBoundingBoxes3D(
    obbs=np.array([[0, 0, 0, 2, 3, 4, 0.1, 0.2, 0.3]], dtype=np.float32),
    labels=[1],
    x_max=10.0, y_max=20.0, z_max=5.0,
)

# Build incrementally
obbs = OrientedBoundingBoxes3D.create_empty(x_max=10, y_max=20, z_max=5)
obbs.add_instance(obb=[0, 0, 0, 2, 3, 4, 0.1, 0.2, 0.3], label=0, confidence=0.95)

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

Add a single 3D oriented bounding box instance.

Parameters:

obb – Oriented bounding box as [cx, cy, cz, sx, sy, sz, yaw, pitch, roll].
label – Optional integer class label for this instance.
confidence – Optional confidence score for this instance.
per_instance_extras – Optional dictionary of per-instance attributes. The first call establishes which keys are expected; subsequent calls must provide the same keys.

Raises:

ValueError – If the OBB does not have exactly 9 elements.

Create an empty OrientedBoundingBoxes3D object to build up incrementally.

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 OrientedBoundingBoxes3D 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 obbs spatial coordinates are normalized to [0, 1].

When True, center (cx, cy, cz) and size (sx, sy, sz) are denormalized to absolute values using the dimensions derived from bounds. Angles are not affected. Bounds must be set.

property num_instances: int¶: Return the number of OBB instances.

obbs: ndarray[tuple[int, int], dtype[numpy.float32]] = field(...)¶: Array of shape (num_instances, 9): [cx, cy, cz, sx, sy, sz, yaw, pitch, roll].

Build the column Schema describing 3D oriented bounding boxes.

Parameters:

classes – A class map 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.obb¶

Module Contents¶

Classes¶

API¶

`tlc.data_types.obb`¶