albumentations.core.bbox_utils

Parameters for bounding box transforms.

Parameters

Examples

>>> # Create BboxParams for COCO format with class labels
>>> bbox_params = BboxParams(
...     coord_format='coco',
...     label_fields=['class_labels'],
...     min_area=1024,
...     min_visibility=0.1
... )

>>> # Create BboxParams that clips and filters invalid boxes
>>> bbox_params = BboxParams(
...     coord_format='pascal_voc',
...     clip_bboxes_on_input=True,
...     filter_invalid_bboxes=True
... )
>>> # Create BboxParams that filters extremely elongated boxes
>>> bbox_params = BboxParams(
...     coord_format='yolo',
...     max_accept_ratio=5.0,  # Filter boxes with aspect ratio > 5:1
...     clip_bboxes_on_input=True
... )
>>> # Create BboxParams for OBB with clipping after transforms
>>> bbox_params = BboxParams(
...     coord_format='albumentations',
...     bbox_type='obb',
...     clip_after_transform=True,  # Clip all corners inside bounds
... )
>>> # Create BboxParams with lenient clipping (allows temporary excursions)
>>> bbox_params = BboxParams(
...     coord_format='yolo',
...     clip_bboxes_on_input=True,  # Fix input errors
...     clip_after_transform=False  # Allow boxes to go outside temporarily
... )
>>> # Create BboxParams for cxcywh (center + wh in pixels)
>>> bbox_params = BboxParams(
...     coord_format='cxcywh',
...     label_fields=['class_ids'],
... )

Processor for bounding box transformations. This class handles the preprocessing and postprocessing of bounding boxes during augmentation pipeline, including format conversion, validation, clipping, and filtering.

Parameters

Examples

>>> import albumentations as A
>>> # Process COCO format bboxes with class labels
>>> params = A.BboxParams(
...     format='coco',
...     label_fields=['class_labels'],
...     min_area=1024,
...     min_visibility=0.1
... )
>>> processor = BboxProcessor(params)
>>>
>>> # Process multiple bbox fields
>>> params = A.BboxParams('pascal_voc')
>>> processor = BboxProcessor(
...     params,
...     additional_targets={'bbox2': 'bboxes'}
... )

Create bounding boxes from binary masks (fast version)

Parameters

Returns

• np.ndarray: An array of bounding boxes with shape (N, 4), where each row is

Convert bounding boxes to a single mask.

Parameters

Returns

• np.ndarray: A numpy array of shape (height, width) with 1s where any bounding box is present.

Calculate areas for multiple bounding boxes. This function computes the areas of bounding boxes given their normalized coordinates and the dimensions of the image they belong to. The bounding boxes are expected to be in the format [x_min, y_min, x_max, y_max] with normalized coordinates (0 to 1).

Parameters

Returns

• np.ndarray: A 1D numpy array of shape (N,) containing the areas of the bounding boxes in pixels.

Examples

>>> bboxes = np.array([[0.1, 0.1, 0.5, 0.5], [0.2, 0.2, 0.8, 0.8]])
>>> image_shape = (100, 100)
>>> areas = calculate_bbox_areas(bboxes, image_shape)
>>> print(areas)
[1600. 3600.]

Notes

- The function assumes that the input bounding boxes are valid (i.e., x_max > x_min and y_max > y_min). Invalid bounding boxes may result in negative areas. - The function preserves the input array and creates a copy for internal calculations. - The returned areas are in pixel units, not normalized.

Check if bounding boxes are valid.

Parameters

Clip bounding boxes to the image shape.

Parameters

Returns

• np.ndarray: A numpy array of bounding boxes with shape (num_bboxes, 4+).

Clip bounding boxes based on actual geometry. This function provides geometry-aware clipping that works correctly for both HBB and OBB: - For HBB: clips (x_min, y_min, x_max, y_max) coordinates to [0, 1] (fast path) - For OBB: clips all 4 rotated corners and returns axis-aligned wrapping box with angle=0

Parameters

Returns

• np.ndarray: Clipped bounding boxes. For OBB, returns (N, 5+) with angle set to 0.

Examples

>>> # HBB - simple coordinate clipping
>>> hbb = np.array([[0.2, 0.3, 1.2, 0.8]])
>>> clipped = clip_bboxes_geometry(hbb, (100, 100), "hbb")
>>> # Result: [[0.2, 0.3, 1.0, 0.8]]

>>> # OBB - clips corners and returns wrapping HBB with angle=0
>>> obb = np.array([[0.2, 0.3, 1.2, 0.8, 45.0]])  # rotated 45 degrees
>>> clipped = clip_bboxes_geometry(obb, (100, 100), "obb")
>>> # Result: [[x_min, y_min, x_max, y_max, 0.0]] - angle reset to 0

Notes

For HBB, this is equivalent to clip_bboxes() (fast coordinate clipping). For OBB, clips the 4 rotated corners and returns the axis-aligned bounding box that wraps them, with angle set to 0 since the result is axis-aligned. cv2.minAreaRect is NOT used for clipping - only for actual rotations.

Convert bounding boxes from the format used by albumentations to a specified format.

Parameters

Returns

• np.ndarray: An array of bounding boxes in the target format with shape (num_bboxes, 4+).

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

Parameters

Returns

• np.ndarray: An array of bounding boxes in albumentations format with shape (num_bboxes, 4+).

Denormalize array of bounding boxes.

Parameters

Returns

• np.ndarray: Denormalized bounding boxes `[(x_min, y_min, x_max, y_max, ...)]`.

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

Parameters

Returns

• np.ndarray: Filtered bounding boxes.

Convert masks back to bounding boxes.

Parameters

Returns

• np.ndarray: A numpy array of bounding boxes with shape (num_masks, 4+) for HBB

Convert bounding boxes to masks.

Parameters

Returns

• np.ndarray: A numpy array of masks with shape (num_bboxes, height, width).

Normalize denormalized bounding boxes.

Parameters

Returns

• np.ndarray: Normalized bounding boxes `[(x_min, y_min, x_max, y_max, ...)]`.

Convert oriented bounding boxes to corner polygons (vectorized). Same convention as cv2.minAreaRect/cv2.boxPoints for consistency with polygons_to_obb. Base rect corners [-w/2,-h/2], [w/2,-h/2], [w/2,h/2], [-w/2,h/2] rotated by angle and translated to center.

Parameters

Returns

• np.ndarray: Array of shape (N, 4, 2) containing the corner coordinates of each

Fit oriented bbox from corner polygons. Uses cv2.minAreaRect only to get the 4 corners (via boxPoints). From those corners we derive (w, h, angle) with our convention: width = edge more parallel to horizontal, angle in [-90, 90). This ensures obb_to_polygons and cv2.boxPoints produce visually correct results regardless of minAreaRect's internal (w,h,angle) representation. The function is coordinate-system agnostic - it preserves the input coordinate system.

Parameters

Returns

• : Array of OBB bounding boxes in the same coordinate system as input polygons.

Calculate union of bounding boxes. Boxes could be in albumentations or Pascal Voc format.

Parameters

Returns

• np.ndarray | None: A bounding box `(x_min, y_min, x_max, y_max)` or None if no bboxes are given or if