tlc.core.builtins.types.bounding_box

Module Contents

Classes

Class

Description

BoundingBox

The base class for all bounding boxes.

XYWHBoundingBox

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

TopLeftXYWHBoundingBox

CenteredXYWHBoundingBox

XYXYBoundingBox

SegmentationBoundingBox

API

class tlc.core.builtins.types.bounding_box.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

abstract classmethod from_top_left_xywh(box: tlc.core.builtins.types.bounding_box.TopLeftXYWHBoundingBox) → tlc.core.builtins.types.bounding_box.BoundingBox

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

abstract to_top_left_xywh() → tlc.core.builtins.types.bounding_box.TopLeftXYWHBoundingBox

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

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

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) → tlc.core.builtins.types.bounding_box.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

denormalize(image_width: int, image_height: int) → tlc.core.builtins.types.bounding_box.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: tlc.core.schema.Schema) → Callable[..., tlc.core.builtins.types.bounding_box.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])
class tlc.core.builtins.types.bounding_box.XYWHBoundingBox(box: list[float], normalized: bool = False)

Bases: tlc.core.builtins.types.bounding_box.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 tlc.core.builtins.types.bounding_box.TopLeftXYWHBoundingBox(box: list[float], normalized: bool = False)

Bases: tlc.core.builtins.types.bounding_box.XYWHBoundingBox

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

Bases: tlc.core.builtins.types.bounding_box.XYWHBoundingBox

classmethod from_top_left_xywh(box: tlc.core.builtins.types.bounding_box.TopLeftXYWHBoundingBox) → tlc.core.builtins.types.bounding_box.CenteredXYWHBoundingBox
to_top_left_xywh() → tlc.core.builtins.types.bounding_box.TopLeftXYWHBoundingBox
class tlc.core.builtins.types.bounding_box.XYXYBoundingBox(box: list[float], normalized: bool = False)

Bases: tlc.core.builtins.types.bounding_box.BoundingBox

classmethod from_top_left_xywh(box: tlc.core.builtins.types.bounding_box.TopLeftXYWHBoundingBox) → tlc.core.builtins.types.bounding_box.XYXYBoundingBox
to_top_left_xywh() → tlc.core.builtins.types.bounding_box.TopLeftXYWHBoundingBox
class tlc.core.builtins.types.bounding_box.SegmentationBoundingBox(box: list[float], normalized: bool = False)

Bases: tlc.core.builtins.types.bounding_box.BoundingBox

classmethod from_top_left_xywh(box: tlc.core.builtins.types.bounding_box.TopLeftXYWHBoundingBox) → tlc.core.builtins.types.bounding_box.SegmentationBoundingBox
to_top_left_xywh() → tlc.core.builtins.types.bounding_box.TopLeftXYWHBoundingBox