Skip to content

Helper functions for working with bounding boxes (augmentations.bbox_utils)

calculate_bbox_area(bbox, rows, cols)

Calculate the area of a bounding box in pixels.

Parameters:

Name Type Description Default
bbox tuple

A bounding box (x_min, y_min, x_max, y_max).

required
rows int

Image height.

required
cols int

Image width.

required

Returns:

Type Description
int

Area of a bounding box in pixels.

check_bbox(bbox)

Check if bbox boundaries are in range 0, 1 and minimums are lesser then maximums

check_bboxes(bboxes)

Check if bboxes boundaries are in range 0, 1 and minimums are lesser then maximums

convert_bbox_from_albumentations(bbox, target_format, rows, cols, check_validity=False)

Convert a bounding box from the format used by albumentations to a format, specified in target_format.

Parameters:

Name Type Description Default
bbox tuple

An albumentation bounding box (x_min, y_min, x_max, y_max).

required
target_format str

required format of the output bounding box. Should be 'coco', 'pascal_voc' or 'yolo'.

required
rows int

Image height.

required
cols int

Image width.

required
check_validity bool

Check if all boxes are valid boxes.

False

Returns:

Type Description
tuple

A bounding box.

Note

The coco format of a bounding box looks like [x_min, y_min, width, height], e.g. [97, 12, 150, 200]. The pascal_voc format of a bounding box looks like [x_min, y_min, x_max, y_max], e.g. [97, 12, 247, 212]. The yolo format of a bounding box looks like [x, y, width, height], e.g. [0.3, 0.1, 0.05, 0.07].

Exceptions:

Type Description
ValueError

if target_format is not equal to coco, pascal_voc or yolo.

convert_bbox_to_albumentations(bbox, source_format, rows, cols, check_validity=False)

Convert a bounding box from a format specified in source_format to the format used by albumentations: normalized coordinates of bottom-left and top-right corners of the bounding box in a form of (x_min, y_min, x_max, y_max) e.g. (0.15, 0.27, 0.67, 0.5).

Parameters:

Name Type Description Default
bbox tuple

A bounding box tuple.

required
source_format str

format of the bounding box. Should be 'coco', 'pascal_voc', or 'yolo'.

required
check_validity bool

Check if all boxes are valid boxes.

False
rows int

Image height.

required
cols int

Image width.

required

Returns:

Type Description
tuple

A bounding box (x_min, y_min, x_max, y_max).

Note

The coco format of a bounding box looks like (x_min, y_min, width, height), e.g. (97, 12, 150, 200). The pascal_voc format of a bounding box looks like (x_min, y_min, x_max, y_max), e.g. (97, 12, 247, 212). The yolo format of a bounding box looks like (x, y, width, height), e.g. (0.3, 0.1, 0.05, 0.07); where x, y coordinates of the center of the box, all values normalized to 1 by image height and width.

Exceptions:

Type Description
ValueError

if target_format is not equal to coco or pascal_voc, ot yolo.

ValueError

If in YOLO format all labels not in range (0, 1).

convert_bboxes_from_albumentations(bboxes, target_format, rows, cols, check_validity=False)

Convert a list of bounding boxes from the format used by albumentations to a format, specified in target_format.

Parameters:

Name Type Description Default
bboxes List[tuple]

List of albumentation bounding box (x_min, y_min, x_max, y_max).

required
target_format str

required format of the output bounding box. Should be 'coco', 'pascal_voc' or 'yolo'.

required
rows int

Image height.

required
cols int

Image width.

required
check_validity bool

Check if all boxes are valid boxes.

False

Returns:

Type Description
list[tuple]

List of bounding box.

convert_bboxes_to_albumentations(bboxes, source_format, rows, cols, check_validity=False)

Convert a list bounding boxes from a format specified in source_format to the format used by albumentations

denormalize_bbox(bbox, rows, cols)

Denormalize coordinates of a bounding box. Multiply x-coordinates by image width and y-coordinates by image height. This is an inverse operation for :func:~albumentations.augmentations.bbox.normalize_bbox.

Parameters:

Name Type Description Default
bbox tuple

Normalized bounding box (x_min, y_min, x_max, y_max).

required
rows int

Image height.

required
cols int

Image width.

required

Returns:

Type Description
tuple

Denormalized bounding box (x_min, y_min, x_max, y_max).

Exceptions:

Type Description
ValueError

If rows or cols is less or equal zero

denormalize_bboxes(bboxes, rows, cols)

Denormalize a list of bounding boxes.

Parameters:

Name Type Description Default
bboxes List[tuple]

Normalized bounding boxes [(x_min, y_min, x_max, y_max)].

required
rows int

Image height.

required
cols int

Image width.

required

Returns:

Type Description
List[tuple]

Denormalized bounding boxes [(x_min, y_min, x_max, y_max)].

filter_bboxes(bboxes, rows, cols, min_area=0.0, min_visibility=0.0)

Remove bounding boxes that either lie outside of the visible area by more then min_visibility or whose area in pixels is under the threshold set by min_area. Also it crops boxes to final image size.

Parameters:

Name Type Description Default
bboxes List[tuple]

List of albumentation bounding box (x_min, y_min, x_max, y_max).

required
rows int

Image height.

required
cols int

Image width.

required
min_area float

Minimum area of a bounding box. All bounding boxes whose visible area in pixels. is less than this value will be removed. Default: 0.0.

0.0
min_visibility float

Minimum fraction of area for a bounding box to remain this box in list. Default: 0.0.

0.0

Returns:

Type Description
List[tuple]

List of bounding box.

filter_bboxes_by_visibility(original_shape, bboxes, transformed_shape, transformed_bboxes, threshold=0.0, min_area=0.0)

Filter bounding boxes and return only those boxes whose visibility after transformation is above the threshold and minimal area of bounding box in pixels is more then min_area.

Parameters:

Name Type Description Default
original_shape tuple

Original image shape (height, width).

required
bboxes List[tuple]

Original bounding boxes [(x_min, y_min, x_max, y_max)].

required
transformed_shape tuple

Transformed image shape (height, width).

required
transformed_bboxes List[tuple]

Transformed bounding boxes [(x_min, y_min, x_max, y_max)].

required
threshold float

visibility threshold. Should be a value in the range [0.0, 1.0].

0.0
min_area float

Minimal area threshold.

0.0

Returns:

Type Description
List[tuple]

Filtered bounding boxes [(x_min, y_min, x_max, y_max)].

normalize_bbox(bbox, rows, cols)

Normalize coordinates of a bounding box. Divide x-coordinates by image width and y-coordinates by image height.

Parameters:

Name Type Description Default
bbox tuple

Denormalized bounding box (x_min, y_min, x_max, y_max).

required
rows int

Image height.

required
cols int

Image width.

required

Returns:

Type Description
tuple

Normalized bounding box (x_min, y_min, x_max, y_max).

Exceptions:

Type Description
ValueError

If rows or cols is less or equal zero

normalize_bboxes(bboxes, rows, cols)

Normalize a list of bounding boxes.

Parameters:

Name Type Description Default
bboxes List[tuple]

Denormalized bounding boxes [(x_min, y_min, x_max, y_max)].

required
rows int

Image height.

required
cols int

Image width.

required

Returns:

Type Description
List[tuple]

Normalized bounding boxes [(x_min, y_min, x_max, y_max)].

union_of_bboxes(height, width, bboxes, erosion_rate=0.0)

Calculate union of bounding boxes.

Parameters:

Name Type Description Default
height float

Height of image or space.

required
width float

Width of image or space.

required
bboxes List[tuple]

List like bounding boxes. Format is [(x_min, y_min, x_max, y_max)].

required
erosion_rate float

How much each bounding box can be shrinked, useful for erosive cropping. Set this in range [0, 1]. 0 will not be erosive at all, 1.0 can make any bbox to lose its volume.

0.0

Returns:

Type Description
tuple

A bounding box (x_min, y_min, x_max, y_max).