`tlc.core.data_formats.obb`¶

Defines representations of oriented bounding boxes in 3LC.

Module Contents¶

Classes¶

Class	Description
`OBB2DInstances`	A helper class for working with Oriented Bounding Box (OBB) instances in 3LC Tables.
`OBB3DInstances`	Helper class for working with 3D Oriented Bounding Box (OBB) instances in 3LC Tables.

API¶

class OBB2DInstances¶

A helper class for working with Oriented Bounding Box (OBB) instances in 3LC Tables.

This class handles conversion to and from the internal dictionary representation of OBB instances, providing a convenient numpy-based interface for reading, manipulating, and writing OBB data.

Objects can be created in three ways:

Standard initialization: Direct instantiation with numpy arrays
From table row: Use from_row() to convert a 3LC Table row to numpy arrays
Build incrementally: Use create_empty() and add_instance() to build up OBB data

Example:

# Read from table row
obbs = OBB2DInstances.from_row(table_row)
print(obbs.obbs.shape)  # (num_instances, 5)

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

# Write back to table
updated_row = obbs.to_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.
instance_extras – Optional dictionary of arbitrary per-instance attributes (e.g., {“track_id”: 42, “area”: 1500}). Values should be scalars. If an extra field is introduced after instances have been added, previous instances will be padded with NaN (float), -1 (int), or None (object).

Raises:

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

Example:

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

classmethod create_empty( image_width: float | None = None, image_height: float | None = None, x_min: float = 0.0, y_min: float = 0.0, x_max: float | None = None, y_max: float | None = None, include_instance_labels: bool = True, include_instance_confidences: bool = False, instance_extras_keys: Sequence[str] | None = None, ) → OBB2DInstances¶

Create an empty OBB2DInstances object to build up incrementally.

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

Parameters:

x_min – Minimum x coordinate (default 0.0)
y_min – Minimum y coordinate (default 0.0)
x_max – Maximum x coordinate (provide this OR image_width)
y_max – Maximum y coordinate (provide this OR image_height)
image_width – Convenience parameter, sets x_max = x_min + image_width
image_height – Convenience parameter, sets y_max = y_min + image_height
include_instance_labels – If True, initialize for storing per-instance labels
include_instance_confidences – If True, initialize for storing per-instance confidence values
instance_extras_keys – Sequence of keys for additional per-instance attributes to initialize

Returns:

An empty OBB2DInstances object ready for adding instances.

Raises:

ValueError – If bounds are not properly specified

Example:

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

classmethod from_row( row: Mapping[str, object], ) → OBB2DInstances¶

Create an OBB2DInstances object from a 3LC Table row.

Parses the hierarchical table row dictionary into structured numpy arrays for easier manipulation.

Parameters:: row – A dictionary representing a single row from a 3LC Table with OBB data. Must contain the ‘instances’ key with a list of instance dictionaries, each containing an ‘oriented_bbs_2d’ entry with ‘center_x’, ‘center_y’, ‘width’, ‘height’, and ‘rotation’ keys.
Returns:: An OBB2DInstances object with all OBB data converted to numpy arrays.
Raises:: ValueError – If the row does not contain instances or if the number of labels doesn’t match the number of instances.
Example:

table = tlc.Table.from_names(...)
for row in table:
    obbs = OBB2DInstances.from_row(row)
    # Manipulate OBB data
    obbs.obbs[:, 4] += 0.1  # Rotate all boxes by 0.1 radians
    # Write back to table
    updated_row = obbs.to_row()

property image_height: float¶: Convenience property: height of the coordinate system.

property image_width: float¶: Convenience property: width of the coordinate system.

instance_confidences: ndarray | None = None¶: Optional numpy array of shape (num_instances,) of float confidences per instance.

instance_extras: dict[str, ndarray] = None¶: Dictionary of arbitrary per-instance attributes as arrays with leading dimension (num_instances, …). Scalars and fixed-size vectors are supported. Always initialized, may be empty.

instance_labels: ndarray[tuple[int], dtype[numpy.int32]] | None = None¶: Optional numpy array of shape (num_instances,) with integer class labels per instance.

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

to_row() → dict[str, Any]¶

Convert an OBB2DInstances object to the internal 3LC Table row format.

Converts the numpy arrays back into the hierarchical dictionary structure expected by 3LC Tables.

Returns:: A dictionary with the structure expected by 3LC Tables, containing ‘instances’ and ‘instances_additional_data’ keys.
Example:

obbs = OBB2DInstances.from_row(row)
# Modify OBBs
obbs.obbs[:, :2] += [10, 10]  # Shift all centers by (10, 10)
# Convert back to table format
updated_row = obbs.to_row()

x_max: float = None¶: Maximum x coordinate of the coordinate system.

x_min: float = None¶: Minimum x coordinate of the coordinate system.

y_max: float = None¶: Maximum y coordinate of the coordinate system.

y_min: float = None¶: Minimum y coordinate of the coordinate system.

class OBB3DInstances¶

Helper class for working with 3D Oriented Bounding Box (OBB) instances in 3LC Tables.

Representation per instance: [center_x, center_y, center_z, size_x, size_y, size_z, yaw, pitch, roll].

Add a single 3D oriented bounding box instance.

obb must be [cx, cy, cz, sx, sy, sz, yaw, pitch, roll].

classmethod create_empty( x_min: float = 0.0, y_min: float = 0.0, z_min: float = 0.0, x_max: float = 0.0, y_max: float = 0.0, z_max: float = 0.0, include_instance_labels: bool = True, include_instance_confidences: bool = False, instance_extras_keys: Sequence[str] | None = None, ) → OBB3DInstances¶

Create an empty OBB3DInstances object to build up incrementally.

Provide either x_max/y_max/z_max or volume_width/height/depth for each axis.

classmethod from_row( row: Mapping[str, object], ) → OBB3DInstances¶

Create an OBB3DInstances object from a 3LC Table row.

Expects bounding box data under instances.oriented_bbs_3d with keys center_x, center_y, center_z, size_x, size_y, size_z, yaw, pitch, roll.

instance_confidences: ndarray | None = None¶

instance_extras: dict[str, ndarray] = None¶

instance_labels: ndarray[tuple[int], dtype[numpy.int32]] | None = None¶

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

to_row() → dict[str, Any]¶: Convert an OBB3DInstances object to the internal 3LC Table row format.

x_max: float = None¶

x_min: float = None¶

y_max: float = None¶

y_min: float = None¶

z_max: float = None¶

z_min: float = None¶

tlc.core.data_formats.obb¶

Module Contents¶

Classes¶

API¶

`tlc.core.data_formats.obb`¶