tlc.core.data_formats.bounding_boxes

Defines representations of bounding boxes in 3LC.

Module Contents

Classes

Class

Description

BoundingBox

The base class for all bounding boxes.

CenteredXYWHBoundingBox

SegmentationBoundingBox

TopLeftXYWHBoundingBox

XYWHBoundingBox

An abstract class representing a bounding box as a list of floats in the format [x, y, w, h]

XYXYBoundingBox

API

class BoundingBox(
box: list[float],
normalized: bool = False,
)

Bases: list

The base class for all bounding boxes.

The BoundingBox class aims to standardize the representation of bounding boxes across the codebase. It is a subclass of list, and represents a bounding box as a list of floats. The exact format of the list depends on the subclass, but the elements within the list are always floats which represent the parameters of the bounding box, in addition to a boolean attribute normalized which indicates whether the bounding box is normalized or not.

The base BoundingBox class implements utility methods like area, is_valid, normalize, and denormalize by calling their definitions in the TopLeftXYWHBoundingBox subclass. Any other BoundingBox format must simply implement the from_top_left_xywh and to_top_left_xywh in order to get access to these utility methods.

In many cases, needing to perform these conversions to and from TopLeftBoundingBox will not be the most efficient implementation of these methods. Where necessary, subclasses can override these methods to provide a more efficient implementation.

Initialize a BoundingBox.

Parameters:

  • box – The list of floats representing the bounding box

  • normalized – Whether the bounding box is normalized or not

area() → float

Compute the area of the bounding box by converting it to a TopLeftXYWHBoundingBox and calling its area method.

Returns:

The area of the bounding box

denormalize(
image_width: int,
image_height: int,
) → BoundingBox

Denormalize the bounding box by converting it to a TopLeftXYWHBoundingBox, calling its denormalize method, and converting it back to the original format.

Parameters:

  • image_width – The width of the image the bounding box is in

  • image_height – The height of the image the bounding box is in

Returns:

The denormalized bounding box

static from_schema(
schema: Schema,
) → Callable[..., BoundingBox]

Return an BoundingBox-factory based on the provided schema.

Parameters:

schema – The schema of the bounding box. Assumed to contain the following values: “x0”, “x1”, “y0”, “y1”.

Returns:

A callable which takes a list of floats and returns a BoundingBox.

Example:

# Instantiate a BoundingBox subclass with the values [0, 0, 1, 1] given the schema `schema`.
bounding_box = BoundingBox.from_schema(schema)([0, 0, 1, 1])
abstract classmethod from_top_left_xywh(
box: TopLeftXYWHBoundingBox,
) → BoundingBox

Create a BoundingBox from a TopLeftXYWHBoundingBox. An abstract method which must be implemented by all subclasses.

is_valid(
image_width: int | None = None,
image_height: int | None = None,
) → bool

Check if the bounding box is valid by converting it to a TopLeftXYWHBoundingBox and calling its is_valid method. The image_width and image_height parameters are required if and only if the bounding box is not normalized.

Parameters:

  • image_width – The width of the image the bounding box is in

  • image_height – The height of the image the bounding box is in

Returns:

True if the bounding box is valid, False otherwise

normalize(
image_width: int,
image_height: int,
) → BoundingBox

Normalize the bounding box by converting it to a TopLeftXYWHBoundingBox, calling its normalize method, and converting it back to the original format.

Parameters:

  • image_width – The width of the image the bounding box is in

  • image_height – The height of the image the bounding box is in

Returns:

The normalized bounding box

abstract to_top_left_xywh() → TopLeftXYWHBoundingBox

Create a TopLeftXYWHBoundingBox from this BoundingBox. An abstract method which must be implemented by all subclasses.

class CenteredXYWHBoundingBox(
box: list[float],
normalized: bool = False,
)

Bases: tlc.core.data_formats.bounding_boxes.XYWHBoundingBox

classmethod from_top_left_xywh(
box: TopLeftXYWHBoundingBox,
) → CenteredXYWHBoundingBox
to_top_left_xywh() → TopLeftXYWHBoundingBox
class SegmentationBoundingBox(
box: list[float],
normalized: bool = False,
)

Bases: tlc.core.data_formats.bounding_boxes.BoundingBox

classmethod from_top_left_xywh(
box: TopLeftXYWHBoundingBox,
) → SegmentationBoundingBox
to_top_left_xywh() → TopLeftXYWHBoundingBox
class TopLeftXYWHBoundingBox(
box: list[float],
normalized: bool = False,
)

Bases: tlc.core.data_formats.bounding_boxes.XYWHBoundingBox

area() → float
denormalize(
image_width: int,
image_height: int,
) → TopLeftXYWHBoundingBox
classmethod from_top_left_xywh(
box: TopLeftXYWHBoundingBox,
) → TopLeftXYWHBoundingBox
is_valid(
image_width: int | None = None,
image_height: int | None = None,
tol: float = _BB_BOUNDS_EPS,
) → bool
normalize(
image_width: int,
image_height: int,
) → TopLeftXYWHBoundingBox
remove_bounds_eps(
image_width: int,
image_height: int,
tol: float = _BB_BOUNDS_EPS,
) → TopLeftXYWHBoundingBox
snap_to(
image_width: int,
image_height: int,
tol: float = _BB_BOUNDS_EPS,
) → tuple[TopLeftXYWHBoundingBox, bool]
to_top_left_xywh() → TopLeftXYWHBoundingBox
class XYWHBoundingBox(
box: list[float],
normalized: bool = False,
)

Bases: tlc.core.data_formats.bounding_boxes.BoundingBox

An abstract class representing a bounding box as a list of floats in the format [x, y, w, h]

Subclasses of XYWH can further specify whether x and y represent the top left corner of the bounding box or the center of the bounding box, whether w and h represent the full or the half width and height of the bounding box, and other variations.

Initialize a BoundingBox.

Parameters:

  • box – The list of floats representing the bounding box

  • normalized – Whether the bounding box is normalized or not

class XYXYBoundingBox(
box: list[float],
normalized: bool = False,
)

Bases: tlc.core.data_formats.bounding_boxes.BoundingBox

classmethod from_top_left_xywh(
box: TopLeftXYWHBoundingBox,
) → XYXYBoundingBox
to_top_left_xywh() → TopLeftXYWHBoundingBox