API reference

The reference is generated from the package's public docstrings, but organized around the way you use the library rather than dumped into one long page.

Main model

Bbox

Bases: BaseModel

A class to represent a Bbox (inherits from Pydantic BaseModel).

The bbox is stored in Pascal_VOC format: top-left, bottom-right with a top-left origin (PIL coord system). (meaning that top < bottom)

The bottom and right edges are considered excluded from the Bbox for compatibility with array slicing and PIL image cropping features (in case of Int Bboxes).

Attributes:

Name	Type	Description
left	float	The left coordinate of the bounding box.
top	float	The top coordinate of the bounding box.
right	float	The right coordinate of the bounding box.
bottom	float	The bottom coordinate of the bounding box.

width property

width: float

The width of the Bbox.

height property

height: float

The height of the Bbox.

area property

area: float

The area of the Bbox

center property

center: Tuple[float, float]

The center of the Bbox in (x, y) format.

aspect_ratio property

aspect_ratio: float

The aspect ratio of the Bbox (width over height).

check_bbox_validity

check_bbox_validity() -> Self

Checks that the Bbox is valid.

from_tlbr classmethod

from_tlbr(tlbr: Sequence[float]) -> Bbox

Initializes the bounding box from top-left and bottom-right coordinates.

Parameters:

Name	Type	Description	Default
tlbr	Sequence[float]	A sequence containing the top-left and bottom-right coordinates of the bounding box in the format (left, top, right, bottom).	required

Returns:

Name	Type	Description
Bbox	Bbox	The Bbox instance.

Raises:

Type	Description
ValueError	If the length of the sequence is not 4, or if the Bbox is not valid (ie left > right or top > bottom).

Examples:

>>> bbox = Bbox.from_tlbr((10, 20, 30, 40))
>>> print(bbox.left, bbox.top, bbox.right, bbox.bottom)
10 20 30 40

from_tlwh classmethod

from_tlwh(tlwh: Sequence[float]) -> Bbox

Initializes the bounding box from top-left and width-height coordinates.

Parameters:

Name	Type	Description	Default
tlwh	Sequence[float]	A sequence containing the top-left and width-height coordinates of the bounding box in the format (left, top, width, height).	required

Returns:

Name	Type	Description
Bbox	Bbox	The Bbox instance.

Raises:

Type	Description
ValueError	If the length of the sequence is not 4, or if the Bbox is not valid (ie width < 0 or height < 0).

Examples:

>>> bbox = Bbox.from_tlwh((10, 20, 20, 30))
>>> print(bbox.left, bbox.top, bbox.right, bbox.bottom)
10 20 30 50

from_cwh classmethod

from_cwh(cwh: Sequence[float]) -> Bbox

Initializes the bounding box from center and width-height coordinates.

Parameters:

Name	Type	Description	Default
cwh	Sequence[float]	A sequence containing the center and width-height coordinates of the bounding box in the format (center_x, center_y, width, height).	required

Returns:

Name	Type	Description
Bbox	Bbox	The Bbox instance.

Raises:

Type	Description
ValueError	If the length of the sequence is not 4, or if the Bbox is not valid (ie width < 0 or height < 0).

Examples:

>>> bbox = Bbox.from_cwh((20, 35, 20, 30))
>>> print(bbox.left, bbox.top, bbox.right, bbox.bottom)
10 20 30 50

to_tlbr

to_tlbr() -> Tuple[float, float, float, float]

Returns the bounding box coordinates in Top-Left, Bottom-Right format.

Returns:

Type	Description
Tuple[float, float, float, float]	Tuple[float, float, float, float]: The bounding box coordinates (x_min, y_min, x_max, y_max). x_min and y_min are the coordinates of the top-left corner of the bounding box. x_max and y_max are the coordinates of the bottom-right corner of the bounding box.

to_list

to_list() -> List[float]

Returns the bounding box coordinates in Top-Left, Bottom-Right format.

Returns:

Type	Description
List[float]	List[float]: The bounding box coordinates [x_min, y_min, x_max, y_max]. x_min and y_min are the coordinates of the top-left corner of the bounding box. x_max and y_max are the coordinates of the bottom-right corner of the bounding box.

to_norm_tlbr

to_norm_tlbr(
    img_w: int, img_h: int
) -> Tuple[float, float, float, float]

Returns the bounding box coordinates in Top-Left, Bottom-Right format, normalized based on the image dimensions.

Parameters:

Name	Type	Description	Default
img_w	int	The image width in pixels.	required
img_h	int	The image height in pixels.	required

Returns:

Type	Description
Tuple[float, float, float, float]	Tuple[float, float, float, float]: The bounding box coordinates (x_min, y_min, x_max, y_max). x_min and y_min are the coordinates of the top-left corner of the bounding box. x_max and y_max are the coordinates of the bottom-right corner of the bounding box. All the returned values are NORMALIZED based on the image dimensions.

to_tlwh

to_tlwh() -> Tuple[float, float, float, float]

Returns the bounding box coordinates in Top-Left, Width-Height format.

Returns:

Type	Description
Tuple[float, float, float, float]	Tuple[float, float, float, float]: The bounding box coordinates (x_min, y_min, width, height). x_min and y_min are coordinates of the top-left corner of the bounding box.

to_norm_tlwh

to_norm_tlwh(
    img_w: int, img_h: int
) -> Tuple[float, float, float, float]

Returns the bounding box coordinates in Top-Left, Width-Height format, normalized based on the image dimensions.

Parameters:

Name	Type	Description	Default
img_w	int	The image width in pixels.	required
img_h	int	The image height in pixels.	required

Returns:

Type	Description
Tuple[float, float, float, float]	Tuple[float, float, float, float]: The bounding box coordinates [x_min, y_min, width, height]. x_min and y_min are the coordinates of the top-left corner of the bounding box. All the returned values are NORMALIZED based on the image dimensions.

to_cwh

to_cwh() -> Tuple[float, float, float, float]

Returns the bounding box coordinates in Center, Width-Height format.

Returns:

Type	Description
Tuple[float, float, float, float]	Tuple[float, float, float, float]: The bounding box coordinates (x_center, y_center, width, height).

to_norm_cwh

to_norm_cwh(
    img_w: int, img_h: int
) -> Tuple[float, float, float, float]

Returns the bounding box coordinates in Center, Width-Height format, normalized based on the image dimensions.

Parameters:

Name	Type	Description	Default
img_w	int	The image width in pixels.	required
img_h	int	The image height in pixels.	required

Returns:

Type	Description
Tuple[float, float, float, float]	Tuple[float, float, float, float]: The NORMALIZED bounding box coordinates (x_center, y_center, width, height).

to_polygon

to_polygon() -> Tuple[
    Tuple[float, float],
    Tuple[float, float],
    Tuple[float, float],
    Tuple[float, float],
]

Returns the bounding box corners as points.

Returns:

Type	Description
Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float], Tuple[float, float]]	The corners coordinates in (x, y) format. The order is top_left > top_right > bottom_right > bottom_left

to_int_tuple

to_int_tuple(
    rounding_method: RoundingMethod = RoundingMethod.ROUND,
) -> Tuple[int, int, int, int]

Returns the bounding box coordinates in Top-Left, Bottom-Right format, with values rounded to int.

Parameters:

Name	Type	Description	Default
rounding_method	RoundingMethod	The rounding method to use. Defaults to RoundingMethod.ROUND.	ROUND

Returns:

Type	Description
Tuple[int, int, int, int]	Tuple[int, int, int, int]: The coordinates as integers.

Raises:

Type	Description
ValueError	If a wrong rounding method is provided.

shift

shift(
    horizontal_shift: float = 0, vertical_shift: float = 0
) -> Bbox

Return a shifted Bbox by the specified horizontal and vertical amounts.

Parameters:

Name	Type	Description	Default
horizontal_shift	float	The amount to shift the bounding box horizontally. Defaults to 0.	0
vertical_shift	float	The amount to shift the bounding box vertically. Defaults to 0.	0

Returns:

Name	Type	Description
Bbox	Bbox	The shifted Bbox instance.

scale

scale(scale_factor: float) -> Bbox

Return a scaled Bbox by the specified scale factor. The scaling will be from the center.

Parameters:

Name	Type	Description	Default
scale_factor	float	The factor to scale the bounding box by. Width and height will be scaled by this factor.	required

Returns:

Name	Type	Description
Bbox	Bbox	The scaled Bbox instance.

Raises:

Type	Description
ValueError	If the scale is strictly negative.

scale_area

scale_area(scale_factor: float) -> Bbox

Return a scaled Bbox such that new area/old area == scale_factor. The scaling will be from the center.

Parameters:

Name	Type	Description	Default
scale_factor	float	The factor to scale the bounding box by. The area will be scaled by this factor. (Meaning width and height will be scaled by the square root of this factor.)	required

Returns:

Name	Type	Description
Bbox	Bbox	The scaled Bbox instance.

Raises:

Type	Description
ValueError	If the scale is strictly negative.

expand_uniform

expand_uniform(padding: float) -> Bbox

Return an expanded Bbox by the specified padding.

Parameters:

Name	Type	Description	Default
padding	float	The amount to expand the bounding box by.	required

Returns:

Name	Type	Description
Bbox	Bbox	The expanded Bbox instance.

expand

expand(
    left: float = 0,
    top: float = 0,
    right: float = 0,
    bottom: float = 0,
) -> Bbox

Return an expanded Bbox by the specified padding for each side.

Parameters:

Name	Type	Description	Default
left	float	The amount to expand the left side of the bounding box by. Defaults to 0.	0
top	float	The amount to expand the top side of the bounding box by. Defaults to 0.	0
right	float	The amount to expand the right side of the bounding box by. Defaults to 0.	0
bottom	float	The amount to expand the bottom side of the bounding box by. Defaults to 0.	0

Returns:

Name	Type	Description
Bbox	Bbox	The expanded Bbox instance.

pad_to_square

pad_to_square() -> Bbox

Returns a padded Bbox to make it a square.

pad_to_aspect_ratio

pad_to_aspect_ratio(target_ratio: float) -> Bbox

Returns a padded Bbox to achieve the target aspect ratio.

Parameters:

Name	Type	Description	Default
target_ratio	float	The target aspect ratio.	required

Returns:

Name	Type	Description
Bbox	Bbox	A Bbox instance padded to the correct ratio.

Raises:

Type	Description
ValueError	If target_ratio is <= 0.

clip_to_img

clip_to_img(img_w: int, img_h: int) -> Bbox

Returns a clipped Bbox to the image dimensions.

Remember that the bottom and right edges are considered excluded from the bbox, so Bbox(left=-10, top=-20, right=100, bottom=120).clip_to_img(img_w=32, img_h=64) returns Bbox(left=0, top=0, right=32, bottom=64)

Note that this method can return a zero area bounding box if the bbox is completely out of the image.

Parameters:

Name	Type	Description	Default
img_w	int	The image width in pixels.	required
img_h	int	The image height in pixels.	required

Returns:

Name	Type	Description
Bbox	Bbox	The clipped Bbox.

overlaps

overlaps(other: Bbox) -> bool

Checks if the current bounding box overlaps with another bounding box.

Two bboxes are considered as overlapping if they intersect with a non-zero area.

Parameters:

Name	Type	Description	Default
other	Bbox	The other bounding box to check for overlap.	required

Returns:

Name	Type	Description
bool	bool	True if the bounding boxes overlap, False otherwise.

contains_point

contains_point(x: float, y: float) -> bool

Checks if a point is inside the bounding box. Note that point on the right or bottom edges are not considered inside.

Parameters:

Name	Type	Description	Default
x	float	The x-coordinate of the point.	required
y	float	The y-coordinate of the point.	required

Returns:

Name	Type	Description
bool	bool	True if the point is inside the bounding box, False otherwise.

contains

contains(other: Bbox) -> bool

Checks if the other Bbox is contained by this one.

Parameters:

Name	Type	Description	Default
other	Bbox	The other bounding box.	required

Returns:

Name	Type	Description
bool	bool	True if this bounding box contains the other one.

is_inside

is_inside(other: Bbox) -> bool

Checks if this Bbox is contained by the other one.

Parameters:

Name	Type	Description	Default
other	Bbox	The other bounding box.	required

Returns:

Name	Type	Description
bool	bool	True if this bounding box is contained by the other one.

union

union(other: Bbox) -> Bbox

Calculates the minimal Bbox that englobes this one AND the other.

Parameters:

Name	Type	Description	Default
other	Bbox	The other bounding box to calculate the union with.	required

Returns:

Name	Type	Description
Bbox	Bbox	The minimal englobing Bbox.

intersection

intersection(other: Bbox) -> Optional[Bbox]

Calculates the intersection with another Bbox. If the resulting Bbox is not valid (ie left > right or top > bottom, returns None.

This operation can return a zero area Bbox if the two bounding boxes are just touching.

Parameters:

Name	Type	Description	Default
other	Bbox	The other bounding box to calculate the intersection with.	required

Returns:

Type	Description
Optional[Bbox]	Optional[Bbox]: The intersection of the two bounding boxes if valid.

iou

iou(other: Bbox) -> float

Calculates the Intersection over Union (IoU) with another bounding box.

Parameters:

Name	Type	Description	Default
other	Bbox	The other Bbox.	required

Returns:

Name	Type	Description
float	float	The IoU between the two bounding boxes.

distance_to_point

distance_to_point(
    x: float,
    y: float,
    dist: DistanceMetric = DistanceMetric.L2,
) -> float

Calculates the distance from the bounding box to a point.

Parameters:

Name	Type	Description	Default
x	float	The x-coordinate of the point.	required
y	float	The y-coordinate of the point.	required
dist	DistanceMetric	The distance metric to use. Defaults to DistanceMetric.L2.	L2

Returns:

Name	Type	Description
float	float	The distance from the bounding box to the point.

Raises:

Type	Description
ValueError	If a wrong distance metric is provided.

distance_to_bbox

distance_to_bbox(
    other: Bbox, dist: DistanceMetric = DistanceMetric.L2
) -> float

Calculates the distance between the edges of this Bbox and another Bbox. Distance is zero if the boxes overlap or touch.

Parameters:

Name	Type	Description	Default
other	Bbox	The other bounding box.	required
dist	DistanceMetric	The distance metric to use. Defaults to DistanceMetric.L2.	L2

Returns:

Name	Type	Description
float	float	The distance between the two bounding boxes.

Raises:

Type	Description
ValueError	If a wrong distance metric is provided.

Enums

DistanceMetric

Bases: Enum

RoundingMethod

Bases: Enum

Utilities

nms

nms(
    bboxes: List[Bbox],
    scores: List[float],
    iou_threshold: float = 0.5,
) -> List[Tuple[Bbox, float]]

Perform Non-Maximum Suppression on a list of bounding boxes.

Parameters:

Name	Type	Description	Default
bboxes	List[Bbox]	List of bounding boxes.	required
scores	List[float]	List of confidence scores for each bounding box.	required
iou_threshold	float	IoU threshold for suppression. Defaults to 0.5.	0.5

Returns:

Type	Description
List[Tuple[Bbox, float]]	List[Tuple[Bbox, float]]: List of selected bounding boxes and their scores.

Raises:

Type	Description
ValueError	If the length of bboxes and scores do not match.

bbox_union

bbox_union(bboxes: Sequence[Bbox]) -> Bbox

Calculate the union of a list of bounding boxes.

Parameters:

Name	Type	Description	Default
bboxes	Sequence[Bbox]	A sequence of bounding boxes.	required

Returns:

Name	Type	Description
Bbox	Bbox	The bounding box that represents the union of all input bounding boxes.

Raises:

Type	Description
ValueError	If the input list of bounding boxes is empty.

bbox_intersection

bbox_intersection(bboxes: Sequence[Bbox]) -> Optional[Bbox]

Calculate the intersection of a list of bounding boxes.

Parameters:

Name	Type	Description	Default
bboxes	Sequence[Bbox]	A sequence of bounding boxes.	required

Returns:

Type	Description
Optional[Bbox]	Optional[Bbox]: The bounding box that represents the intersection of all input bounding boxes. If the resulting bounding box is not valid, returns None.

Raises:

Type	Description
ValueError	If the input list of bounding boxes is empty.