Skip to content

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

class albumentations.core.bbox_utils.BboxParams (format, label_fields=None, min_area=0.0, min_visibility=0.0, min_width=0.0, min_height=0.0, check_each_transform=True) [view source on GitHub]

Parameters of bounding boxes

Parameters:

Name Type Description
format str

format of bounding boxes. Should be 'coco', 'pascal_voc', 'albumentations' or 'yolo'.

The coco format [x_min, y_min, width, height], e.g. [97, 12, 150, 200]. The pascal_voc format [x_min, y_min, x_max, y_max], e.g. [97, 12, 247, 212]. The albumentations format is like pascal_voc, but normalized, in other words: [x_min, y_min, x_max, y_max], e.g. [0.2, 0.3, 0.4, 0.5]. The yolo format [x, y, width, height], e.g. [0.1, 0.2, 0.3, 0.4]; x, y - normalized bbox center; width, height - normalized bbox width and height.
label_fields list

list of fields that are joined with boxes, e.g labels. Should be same type as boxes.
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.
min_width float

Minimum width of a bounding box. All bounding boxes whose width is less than this value will be removed. Default: 0.0.
min_height float

Minimum height of a bounding box. All bounding boxes whose height is less than this value will be removed. Default: 0.0.
check_each_transform bool

if True, then bboxes will be checked after each dual transform. Default: True

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

Calculate the area of a bounding box in (fractional) pixels.

Parameters:

Name Type Description
bbox Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]

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

Image height.
cols int

Image width.

Returns:

Type Description
float

Area in (fractional) pixels of the (denormalized) bounding box.

def albumentations.core.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.core.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.core.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 Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]

An albumentations 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
Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]

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.core.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 Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]

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
Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]

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, or yolo.
ValueError

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

def albumentations.core.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 Sequence[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]]

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[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]]

List of bounding boxes.

def albumentations.core.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.core.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 ~TBox

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

Image height.
cols int

Image width.

Returns:

Type Description
~TBox

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.core.bbox_utils.denormalize_bboxes (bboxes, rows, cols) [view source on GitHub]

Denormalize a list of bounding boxes.

Parameters:

Name Type Description
bboxes Sequence[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]]

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

Image height.
cols int

Image width.

Returns:

Type Description
List[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]]

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

def albumentations.core.bbox_utils.filter_bboxes (bboxes, rows, cols, min_area=0.0, min_visibility=0.0, min_width=0.0, min_height=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 Sequence[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]]

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.
min_width float

Minimum width of a bounding box. All bounding boxes whose width is less than this value will be removed. Default: 0.0.
min_height float

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

Returns:

Type Description
List[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]]

List of bounding boxes.

def albumentations.core.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 Sequence[int]

Original image shape (height, width, ...).
bboxes Sequence[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]]

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

Transformed image shape (height, width).
transformed_bboxes Sequence[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]]

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[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]]

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

def albumentations.core.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 ~TBox

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

Image height.
cols int

Image width.

Returns:

Type Description
~TBox

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.core.bbox_utils.normalize_bboxes (bboxes, rows, cols) [view source on GitHub]

Normalize a list of bounding boxes.

Parameters:

Name Type Description
bboxes Sequence[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]]

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

Image height.
cols int

Image width.

Returns:

Type Description
List[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]]

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

def albumentations.core.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 int

Height of image or space.
width int

Width of image or space.
bboxes Sequence[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]]

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
Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]

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