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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
rows |
int |
Image height. |
cols |
int |
Image width. |
Returns:
Type | Description |
---|---|
~TBox |
Denormalized bounding box |
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 |
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 |
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 |
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 |
bboxes |
Sequence[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]] |
Original bounding boxes |
transformed_shape |
Sequence[int] |
Transformed image shape |
transformed_bboxes |
Sequence[Union[Tuple[float, float, float, float], Tuple[float, float, float, float, Any]]] |
Transformed bounding boxes |
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 |
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 |
rows |
int |
Image height. |
cols |
int |
Image width. |
Returns:
Type | Description |
---|---|
~TBox |
Normalized bounding box |
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 |
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 |
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 |
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 |