Oriented Bounding Boxes (OBBs) in 3LC¶

What are Oriented Bounding Boxes?¶

Oriented bounding boxes describe objects with a rectangle that can rotate, allowing a tighter fit than axis-aligned boxes. A 2D OBB is typically represented by its center, size, and rotation.

Working with OBBs in 3LC¶

The structure of an OBB column is defined by its Schema. The OrientedBoundingBoxes2DSchema class is used to define the schema of a 2D OBB column.

Creating OBB Tables¶

Create OBB Tables from YOLO Format: Build Tables from YOLO-OBB datasets (corner vertices format)
Create Custom OBB Tables: Create OBB Tables programmatically

When working directly with OBB Tables—during custom data loading or prediction writing—the OBB2DInstances helper simplifies conversion between Table rows and numpy arrays.

This helper provides:

Reading from Tables: Convert a Table row to structured numpy arrays with from_row()
Writing to Tables: Convert numpy arrays back to Table row format with to_row()
Building from scratch: Create empty instances with create_empty() and add data incrementally with add_instance()

from tlc import OBB2DInstances

# Reading: Convert Table row to numpy arrays
obbs = OBB2DInstances.from_row(table_row)
obbs.obbs.shape            # (num_instances, 5) with [cx, cy, w, h, rotation]
obbs.instance_labels.shape # (num_instances,) if labels are present

# Writing: Convert numpy arrays back to Table format
updated_row = obbs.to_row()

Building OBBs Programmatically¶

from tlc import OBB2DInstances

obbs = OBB2DInstances.create_empty(image_height=480, image_width=640)
obbs.add_instance(
    obb=[320.0, 240.0, 100.0, 50.0, 0.785],  # [cx, cy, w, h, rotation-radians]
    label=0,
    confidence=0.95,
)
row = obbs.to_row()

Angle and Normalization Conventions¶

Representation: Each OBB instance is stored as [center_x, center_y, width, height, rotation].
Units: center_x/center_y/width/height are in pixels in Table rows; rotation is in radians.
YOLO-OBB import: The YOLO-OBB reader expects 8 normalized coordinates (four vertices in [0, 1]) and converts them to a minimal-area rectangle. Values are denormalized to pixels and the angle is normalized to ([0, \pi/2)).

Framework Integration¶

Currently Supported¶

Ultralytics YOLO OBB: Full integration for rotated detection via YOLO-OBB datasets
Custom PyTorch Models: Use direct Table access with OBB2DInstances in your training loops

Examples and Tutorials¶

Train YOLO OBB Detector: Complete training example with Ultralytics YOLO-OBB

Additional Resources¶

Examples repository: Additional tutorials and workflows
Discord community: Support and discussions