Skip to content

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

def albumentations.augmentations.bbox_utils.calculate_bbox_area (bbox, rows, cols) [view source on GitHub]

Calculate the area of a bounding box in pixels.

Parameters:

Name Type Description
bbox tuple

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

rows int

Image height.

cols int

Image width.

Returns:

Type Description
int

Area of a bounding box in pixels.

def albumentations.augmentations.bbox_utils.check_bbox (bbox) [view source on GitHub]

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

def albumentations.augmentations.bbox_utils.check_bboxes (bboxes) [view source on GitHub]

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

def albumentations.augmentations.bbox_utils.convert_bbox_from_albumentations (bbox, target_format, rows, cols, check_validity=False) [view source on GitHub]

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

Parameters:

Name Type Description
bbox tuple

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

target_format str

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

rows int

Image height.

cols int

Image width.

check_validity bool

Check if all boxes are valid boxes.

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.

def albumentations.augmentations.bbox_utils.convert_bbox_to_albumentations (bbox, source_format, rows, cols, check_validity=False) [view source on GitHub]

Convert a bounding box from a format specified in source_format to the format used by albumentations: normalized coordinates of top-left and bottom-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
bbox tuple

A bounding box tuple.

source_format str

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

check_validity bool

Check if all boxes are valid boxes.

rows int

Image height.

cols int

Image width.

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).

def albumentations.augmentations.bbox_utils.convert_bboxes_from_albumentations (bboxes, target_format, rows, cols, check_validity=False) [view source on GitHub]

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

Parameters:

Name Type Description
bboxes List[tuple]

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

target_format str

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

rows int

Image height.

cols int

Image width.

check_validity bool

Check if all boxes are valid boxes.

Returns:

Type Description
list[tuple]

List of bounding box.

def albumentations.augmentations.bbox_utils.convert_bboxes_to_albumentations (bboxes, source_format, rows, cols, check_validity=False) [view source on GitHub]

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

def albumentations.augmentations.bbox_utils.denormalize_bbox (bbox, rows, cols) [view source on GitHub]

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
bbox tuple

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

rows int

Image height.

cols int

Image width.

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

def albumentations.augmentations.bbox_utils.denormalize_bboxes (bboxes, rows, cols) [view source on GitHub]

Denormalize a list of bounding boxes.

Parameters:

Name Type Description
bboxes List[tuple]

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

rows int

Image height.

cols int

Image width.

Returns:

Type Description
List[tuple]

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

def albumentations.augmentations.bbox_utils.filter_bboxes (bboxes, rows, cols, min_area=0.0, min_visibility=0.0) [view source on GitHub]

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
bboxes List[tuple]

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

rows int

Image height.

cols int

Image width.

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.

min_visibility float

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

Returns:

Type Description
List[tuple]

List of bounding box.

def albumentations.augmentations.bbox_utils.filter_bboxes_by_visibility (original_shape, bboxes, transformed_shape, transformed_bboxes, threshold=0.0, min_area=0.0) [view source on GitHub]

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
original_shape tuple

Original image shape (height, width).

bboxes List[tuple]

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

transformed_shape tuple

Transformed image shape (height, width).

transformed_bboxes List[tuple]

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

threshold float

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

min_area float

Minimal area threshold.

Returns:

Type Description
List[tuple]

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

def albumentations.augmentations.bbox_utils.normalize_bbox (bbox, rows, cols) [view source on GitHub]

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

Parameters:

Name Type Description
bbox tuple

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

rows int

Image height.

cols int

Image width.

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

def albumentations.augmentations.bbox_utils.normalize_bboxes (bboxes, rows, cols) [view source on GitHub]

Normalize a list of bounding boxes.

Parameters:

Name Type Description
bboxes List[tuple]

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

rows int

Image height.

cols int

Image width.

Returns:

Type Description
List[tuple]

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

def albumentations.augmentations.bbox_utils.union_of_bboxes (height, width, bboxes, erosion_rate=0.0) [view source on GitHub]

Calculate union of bounding boxes.

Parameters:

Name Type Description
height float

Height of image or space.

width float

Width of image or space.

bboxes List[tuple]

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

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.

Returns:

Type Description
tuple

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