albumentations.augmentations.crops.functional
Functional implementations of image cropping operations. This module provides utility functions for performing various cropping operations on images, bounding boxes, and keypoints. It includes functions to calculate crop coordinates, crop images, and handle the corresponding transformations for bounding boxes and keypoints to maintain consistency between different data types during cropping operations.
Members
- functioncrop
- functioncrop_and_pad
- functioncrop_and_pad_bboxes
- functioncrop_and_pad_keypoints
- functioncrop_bboxes_by_coords
- functioncrop_keypoints_by_coords
- functionget_center_crop_coords
- functionget_crop_coords
- functionpad_along_axes
- functionvolume_crop_yx
- functionvolumes_crop_yx
cropfunction
crop(
img: np.ndarray,
x_min: int,
y_min: int,
x_max: int,
y_max: int
)Crop an image. This function crops an image.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| img | np.ndarray | - | Input image. |
| x_min | int | - | Minimum x coordinate. |
| y_min | int | - | Minimum y coordinate. |
| x_max | int | - | Maximum x coordinate. |
| y_max | int | - | Maximum y coordinate. |
Returns
- np.ndarray: Cropped image.
crop_and_padfunction
crop_and_pad(
img: np.ndarray,
crop_params: tuple[int, int, int, int] | None,
pad_params: tuple[int, int, int, int] | None,
pad_value: tuple[float, ...] | float | None,
image_shape: tuple[int, int],
interpolation: int,
pad_mode: int,
keep_size: bool
)Crop and pad an image. This function crops and pads an image.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| img | np.ndarray | - | Input image. |
| crop_params | One of:
| - | Crop parameters. |
| pad_params | One of:
| - | Pad parameters. |
| pad_value | One of:
| - | Pad value. |
| image_shape | tuple[int, int] | - | Original image shape. |
| interpolation | int | - | Interpolation method. |
| pad_mode | int | - | Pad mode. |
| keep_size | bool | - | Whether to keep the original size. |
Returns
- np.ndarray: Cropped and padded image.
crop_and_pad_bboxesfunction
crop_and_pad_bboxes(
bboxes: np.ndarray,
crop_params: tuple[int, int, int, int] | None,
pad_params: tuple[int, int, int, int] | None,
image_shape: tuple[int, int],
result_shape: tuple[int, int]
)Crop and pad bounding boxes. This function crops and pads bounding boxes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| bboxes | np.ndarray | - | Array of bounding boxes. |
| crop_params | One of:
| - | Crop parameters. |
| pad_params | One of:
| - | Pad parameters. |
| image_shape | tuple[int, int] | - | Original image shape. |
| result_shape | tuple[int, int] | - | Result image shape. |
Returns
- np.ndarray: Array of cropped and padded bounding boxes.
crop_and_pad_keypointsfunction
crop_and_pad_keypoints(
keypoints: np.ndarray,
crop_params: tuple[int, int, int, int] | None = None,
pad_params: tuple[int, int, int, int] | None = None,
image_shape: tuple[int, int] = (0, 0),
result_shape: tuple[int, int] = (0, 0),
keep_size: bool = False
)Crop and pad multiple keypoints simultaneously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | Array of keypoints with shape (N, 4+) where each row is (x, y, angle, scale, ...). |
| crop_params | One of:
| None | Crop parameters [crop_x1, crop_y1, ...]. |
| pad_params | One of:
| None | Pad parameters [top, bottom, left, right]. |
| image_shape | tuple[int, int] | (0, 0) | Original image shape (rows, cols). |
| result_shape | tuple[int, int] | (0, 0) | Result image shape (rows, cols). |
| keep_size | bool | False | Whether to keep the original size. |
Returns
- np.ndarray: Array of transformed keypoints with the same shape as input.
crop_bboxes_by_coordsfunction
crop_bboxes_by_coords(
bboxes: np.ndarray,
crop_coords: tuple[int, int, int, int],
image_shape: tuple[int, int],
normalized_input: bool = True
)Crop bounding boxes based on given crop coordinates. This function adjusts bounding boxes to fit within a cropped image.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| bboxes | np.ndarray | - | Array of bounding boxes with shape (N, 4+) where each row is [x_min, y_min, x_max, y_max, ...]. The bounding box coordinates can be either normalized (in [0, 1]) if normalized_input=True or absolute pixel values if normalized_input=False. |
| crop_coords | tuple[int, int, int, int] | - | Crop coordinates (x_min, y_min, x_max, y_max) in absolute pixel values. |
| image_shape | tuple[int, int] | - | Original image shape (height, width). |
| normalized_input | bool | True | Whether input boxes are in normalized coordinates. If True, assumes input is normalized [0,1] and returns normalized coordinates. If False, assumes input is in absolute pixels and returns absolute coordinates. Default: True for backward compatibility. |
Returns
- np.ndarray: Array of cropped bounding boxes. Coordinates will be in the same format as input
Notes
Bounding boxes that fall completely outside the crop area will be removed. Bounding boxes that partially overlap with the crop area will be adjusted to fit within it.
crop_keypoints_by_coordsfunction
crop_keypoints_by_coords(
keypoints: np.ndarray,
crop_coords: tuple[int, int, int, int]
)Crop keypoints using the provided coordinates of bottom-left and top-right corners in pixels.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | An array of keypoints with shape (N, 4+) where each row is (x, y, angle, scale, ...). |
| crop_coords | tuple[int, int, int, int] | - | Crop box coords (x1, y1, x2, y2). |
Returns
- np.ndarray: An array of cropped keypoints with the same shape as the input.
get_center_crop_coordsfunction
get_center_crop_coords(
image_shape: tuple[int, int],
crop_shape: tuple[int, int]
)Get center crop coordinates. This function gets the center crop coordinates.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| image_shape | tuple[int, int] | - | Original image shape. |
| crop_shape | tuple[int, int] | - | Crop shape. |
Returns
- tuple[int, int, int, int]: Center crop coordinates.
get_crop_coordsfunction
get_crop_coords(
image_shape: tuple[int, int],
crop_shape: tuple[int, int],
h_start: float,
w_start: float
)Get crop coordinates. This function gets the crop coordinates.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| image_shape | tuple[int, int] | - | Original image shape. |
| crop_shape | tuple[int, int] | - | Crop shape. |
| h_start | float | - | Start height. |
| w_start | float | - | Start width. |
Returns
- tuple[int, int, int, int]: Crop coordinates.
pad_along_axesfunction
pad_along_axes(
arr: np.ndarray,
pad_top: int,
pad_bottom: int,
pad_left: int,
pad_right: int,
h_axis: int,
w_axis: int,
border_mode: int,
pad_value: float | Sequence[float] = 0
)Pad an array along specified height (H) and width (W) axes using np.pad.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| arr | np.ndarray | - | Input array. |
| pad_top | int | - | Padding added to the top (start of H axis). |
| pad_bottom | int | - | Padding added to the bottom (end of H axis). |
| pad_left | int | - | Padding added to the left (start of W axis). |
| pad_right | int | - | Padding added to the right (end of W axis). |
| h_axis | int | - | Index of the height axis (Y). |
| w_axis | int | - | Index of the width axis (X). |
| border_mode | int | - | OpenCV border mode. |
| pad_value | One of:
| 0 | Value for constant padding. |
Returns
- np.ndarray: Padded array.
volume_crop_yxfunction
volume_crop_yx(
volume: np.ndarray,
x_min: int,
y_min: int,
x_max: int,
y_max: int
)Crop a single volume along Y (height) and X (width) axes only.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume | np.ndarray | - | Input volume with shape (D, H, W) or (D, H, W, C). |
| x_min | int | - | Minimum width coordinate. |
| y_min | int | - | Minimum height coordinate. |
| x_max | int | - | Maximum width coordinate. |
| y_max | int | - | Maximum height coordinate. |
Returns
- np.ndarray: Cropped volume (D, H_new, W_new, [C]).
volumes_crop_yxfunction
volumes_crop_yx(
volumes: np.ndarray,
x_min: int,
y_min: int,
x_max: int,
y_max: int
)Crop a batch of volumes along Y (height) and X (width) axes only.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volumes | np.ndarray | - | Input batch of volumes with shape (B, D, H, W) or (B, D, H, W, C). |
| x_min | int | - | Minimum width coordinate. |
| y_min | int | - | Minimum height coordinate. |
| x_max | int | - | Maximum width coordinate. |
| y_max | int | - | Maximum height coordinate. |
Returns
- np.ndarray: Cropped batch of volumes (B, D, H_new, W_new, [C]).