Stay updated

News & Insights
functionaltransforms
utils

albumentations.augmentations.crops.functional

View Source on GitHub

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

get_crop_coordsfunction

get_crop_coords(
    image_shape: tuple[int, int],
    crop_shape: tuple[int, int],
    h_start: float,
    w_start: float
)

Return (x_min, y_min, x_max, y_max) in pixels for crop_shape. h_start, w_start in [0, 1) choose the window; maps to [0, image_size - crop_size]. This function gets the crop coordinates. Args: 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.

Parameters

NameTypeDefaultDescription
image_shapetuple[int, int]--
crop_shapetuple[int, int]--
h_startfloat--
w_startfloat--

crop_bboxes_by_coordsfunction

crop_bboxes_by_coords(
    bboxes: np.ndarray,
    crop_coords: tuple[int, int, int, int],
    image_shape: tuple[int, int]
)

Shift and renormalize bboxes to the crop region from crop_coords. Supports HBB and OBB; clipping/filtering happens in Compose via clamping_mode. This function adjusts bounding boxes to fit within a cropped image. Supports both HBB (axis-aligned) and OBB (oriented) bounding boxes. Simply shifts the bounding rectangle coordinates - clipping/filtering happens later in Compose via clamping_mode. Args: bboxes (np.ndarray): Array of normalized bounding boxes (Albumentations format) with shape (N, 4+) where each row is [x_min, y_min, x_max, y_max, ...] for HBB or [x_min, y_min, x_max, y_max, angle, ...] for OBB. 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). Returns: np.ndarray: Array of cropped bounding boxes in normalized coordinates (Albumentations format).

Parameters

NameTypeDefaultDescription
bboxesnp.ndarray--
crop_coordstuple[int, int, int, int]--
image_shapetuple[int, int]--

crop_keypoints_by_coordsfunction

crop_keypoints_by_coords(
    keypoints: np.ndarray,
    crop_coords: tuple[int, int, int, int]
)

Shift keypoint (x,y) by crop origin; crop_coords are bottom-left and top-right in pixels. Keypoints outside crop are not filtered here. Args: 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.

Parameters

NameTypeDefaultDescription
keypointsnp.ndarray--
crop_coordstuple[int, int, int, int]--

get_center_crop_coordsfunction

get_center_crop_coords(
    image_shape: tuple[int, int],
    crop_shape: tuple[int, int]
)

Return (x_min, y_min, x_max, y_max) in pixels for center crop. Crop is centered in image_shape; crop_shape may be smaller than or equal to image dimensions. This function gets the center crop coordinates. Args: image_shape (tuple[int, int]): Original image shape. crop_shape (tuple[int, int]): Crop shape. Returns: tuple[int, int, int, int]: Center crop coordinates.

Parameters

NameTypeDefaultDescription
image_shapetuple[int, int]--
crop_shapetuple[int, int]--

cropfunction

crop(
    img: ImageType,
    x_min: int,
    y_min: int,
    x_max: int,
    y_max: int
)

Extract pixel region [x_min:x_max, y_min:y_max]. Bounds: x_min < x_max, y_min < y_max. Use for crop transforms or ROI. Same channel count. This function crops an image. Args: img (ImageType): 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: ImageType: Cropped image.

Parameters

NameTypeDefaultDescription
imgImageType--
x_minint--
y_minint--
x_maxint--
y_maxint--

crop_and_padfunction

crop_and_pad(
    img: ImageType,
    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/or pad from crop_params and pad_params. keep_size, interpolation, pad_mode, pad_value (scalar or per-channel). Returns resized when keep_size. This function crops and pads an image. Args: img (ImageType): Input image. crop_params (tuple[int, int, int, int] | None): Crop parameters. pad_params (tuple[int, int, int, int] | None): Pad parameters. pad_value (tuple[float, ...] | float | None): 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: ImageType: Cropped and padded image.

Parameters

NameTypeDefaultDescription
imgImageType--
crop_params
One of:
  • tuple[int, int, int, int]
  • None
--
pad_params
One of:
  • tuple[int, int, int, int]
  • None
--
pad_value
One of:
  • tuple[float, ...]
  • float
  • None
--
image_shapetuple[int, int]--
interpolationint--
pad_modeint--
keep_sizebool--

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

Shift bboxes by crop then pad offset; renormalize to result_shape. Supports HBB and OBB; clipping/filtering in Compose via clamping_mode. This function crops and pads bounding boxes. Supports both HBB and OBB. Simply shifts coordinates - clipping/filtering happens in Compose via clamping_mode. Args: bboxes (np.ndarray): Array of bounding boxes (HBB or OBB) with any number of columns. First 4 columns are [x_min, y_min, x_max, y_max], rest are preserved. crop_params (tuple[int, int, int, int] | None): Crop parameters. pad_params (tuple[int, int, int, int] | None): 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.

Parameters

NameTypeDefaultDescription
bboxesnp.ndarray--
crop_params
One of:
  • tuple[int, int, int, int]
  • None
--
pad_params
One of:
  • tuple[int, int, int, int]
  • None
--
image_shapetuple[int, int]--
result_shapetuple[int, int]--

crop_and_pad_keypointsfunction

crop_and_pad_keypoints(
    keypoints: np.ndarray,
    crop_params: tuple[int, int, int, int] | None,
    pad_params: tuple[int, int, int, int] | None,
    image_shape: tuple[int, int] = (0, 0),
    result_shape: tuple[int, int] = (0, 0),
    keep_size: bool = False
)

Shift keypoint (x,y) by crop then pad; optional keep_size scaling. crop_params, pad_params, image_shape, result_shape define the geometry. Args: keypoints (np.ndarray): Array of keypoints with shape (N, 4+) where each row is (x, y, angle, scale, ...). crop_params (tuple[int, int, int, int] | None): Crop parameters [crop_x1, crop_y1, ...]. pad_params (tuple[int, int, int, int] | None): Pad parameters [top, bottom, left, right]. image_shape (tuple[int, int]): Original image shape (rows, cols). result_shape (tuple[int, int]): Result image shape (rows, cols). keep_size (bool): Whether to keep the original size. Returns: np.ndarray: Array of transformed keypoints with the same shape as input.

Parameters

NameTypeDefaultDescription
keypointsnp.ndarray--
crop_params
One of:
  • tuple[int, int, int, int]
  • None
--
pad_params
One of:
  • tuple[int, int, int, int]
  • None
--
image_shapetuple[int, int](0, 0)-
result_shapetuple[int, int](0, 0)-
keep_sizeboolFalse-

volume_crop_yxfunction

volume_crop_yx(
    volume: ImageType,
    x_min: int,
    y_min: int,
    x_max: int,
    y_max: int
)

Crop volume (D, H, W[, C]) along Y and X only; depth unchanged. Validates bounds; returns volume[:, y_min:y_max, x_min:x_max]. Args: volume (ImageType): 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: ImageType: Cropped volume (D, H_new, W_new, [C]). Raises: ValueError: If crop coordinates are invalid.

Parameters

NameTypeDefaultDescription
volumeImageType--
x_minint--
y_minint--
x_maxint--
y_maxint--

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 (B, D, H, W[, C]) along Y and X axes only; depth unchanged. Pixel bounds validated; returns volumes[:, :, y_min:y_max, x_min:x_max]. Args: 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]). Raises: ValueError: If crop coordinates are invalid or volumes shape is incorrect.

Parameters

NameTypeDefaultDescription
volumesnp.ndarray--
x_minint--
y_minint--
x_maxint--
y_maxint--

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 array along height (H) and width (W) axes via np.pad. Params: pad_top/bottom/ left/right, h_axis, w_axis, border_mode, pad_value (scalar or sequence). Args: 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 (float | Sequence[float]): Value for constant padding. Returns: np.ndarray: Padded array. Raises: ValueError: If border_mode is unsupported or axis indices are out of bounds.

Parameters

NameTypeDefaultDescription
arrnp.ndarray--
pad_topint--
pad_bottomint--
pad_leftint--
pad_rightint--
h_axisint--
w_axisint--
border_modeint--
pad_value
One of:
  • float
  • Sequence[float]
0-