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 = _BOUNDS_EPS) → tuple[tlc.core.builtins.types.bounding_box.TopLeftXYWHBoundingBox, bool]#
remove_bounds_eps(image_width: int, image_height: int, tol: float = _BOUNDS_EPS) → tlc.core.builtins.types.bounding_box.TopLeftXYWHBoundingBox#
is_valid(image_width: int | None = None, image_height: int | None = None, tol: float = _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#