albumentations.augmentations.crops.transforms
Transform classes for cropping operations on images and other data types. This module provides various crop transforms that can be applied to images, masks, bounding boxes, and keypoints. The transforms include simple cropping, random cropping, center cropping, cropping near bounding boxes, and other specialized cropping operations that maintain the integrity of bounding boxes. These transforms are designed to work within the albumentations pipeline and can be used for data augmentation in computer vision tasks.
Members
- classAtLeastOneBBoxRandomCrop
- classBBoxSafeRandomCrop
- classBaseCrop
- classBaseCropAndPad
- classBaseRandomSizedCropInitSchema
- classCenterCrop
- classCrop
- classCropAndPad
- classCropNonEmptyMaskIfExists
- classCropSizeError
- classRandomCrop
- classRandomCropFromBorders
- classRandomCropNearBBox
- classRandomResizedCrop
- classRandomSizedBBoxSafeCrop
- classRandomSizedCrop
AtLeastOneBBoxRandomCropclass
AtLeastOneBBoxRandomCrop(
height: int,
width: int,
erosion_factor: float = 0.0,
p: float = 1.0
)Crop an area from image while ensuring at least one bounding box is present in the crop. Similar to BBoxSafeRandomCrop, but with a key difference: - BBoxSafeRandomCrop ensures ALL bounding boxes are preserved in the crop - AtLeastOneBBoxRandomCrop ensures AT LEAST ONE bounding box is present in the crop This makes AtLeastOneBBoxRandomCrop more flexible for scenarios where: - You want to focus on individual objects rather than all objects - You're willing to lose some bounding boxes to get more varied crops - The image has many bounding boxes and keeping all of them would be too restrictive The algorithm: 1. If bounding boxes exist: - Randomly selects a reference bounding box from available boxes - Computes an eroded version of this box (shrunk by erosion_factor) - Calculates valid crop bounds that ensure overlap with the eroded box - Randomly samples crop coordinates within these bounds 2. If no bounding boxes exist: - Uses full image dimensions as valid bounds - Randomly samples crop coordinates within these bounds
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| height | int | - | Fixed height of the crop |
| width | int | - | Fixed width of the crop |
| erosion_factor | float | 0.0 | Factor by which to erode (shrink) the reference bounding box when computing valid crop regions. Must be in range [0.0, 1.0]. - 0.0 means no erosion (crop must fully contain the reference box) - 1.0 means maximum erosion (crop can be anywhere that intersects the reference box) Defaults to 0.0. |
| p | float | 1.0 | Probability of applying the transform. Defaults to 1.0. |
Example
>>> import albumentations as A
>>> transform = A.AtLeastOneBBoxRandomCrop(height=100, width=100)
>>> result = transform(
... image=image,
... bboxes=[[0.1, 0.2, 0.5, 0.7, 'cat']],
... bbox_format='yolo' # or 'coco', 'pascal_voc'
... )
>>> transformed_image = result['image']
>>> transformed_bboxes = result['bboxes']Notes
- Uses fixed crop dimensions (height and width) - Bounding boxes that end up partially outside the crop will be adjusted - Bounding boxes that end up completely outside the crop will be removed - If no bounding boxes are provided, acts as a regular random crop
BBoxSafeRandomCropclass
BBoxSafeRandomCrop(
erosion_rate: float = 0.0,
p: float = 1.0
)Crop an area from image while ensuring all bounding boxes are preserved in the crop. Similar to AtLeastOneBboxRandomCrop, but with a key difference: - BBoxSafeRandomCrop ensures ALL bounding boxes are preserved in the crop - AtLeastOneBboxRandomCrop ensures AT LEAST ONE bounding box is present in the crop This makes BBoxSafeRandomCrop more suitable for scenarios where: - You need to preserve all objects in the scene - Losing any bounding box would be problematic (e.g., rare object classes) - You're training a model that needs to detect multiple objects simultaneously The algorithm: 1. If bounding boxes exist: - Computes the union of all bounding boxes - Applies erosion based on erosion_rate to this union - Clips the eroded union to valid image coordinates [0,1] - Randomly samples crop coordinates within the clipped union area 2. If no bounding boxes exist: - Computes crop height based on erosion_rate - Sets crop width to maintain original aspect ratio - Randomly places the crop within the image
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| erosion_rate | float | 0.0 | Controls how much the valid crop region can deviate from the bbox union. Must be in range [0.0, 1.0]. - 0.0: crop must contain the exact bbox union - 1.0: crop can deviate maximally from the bbox union while still containing all boxes Defaults to 0.0. |
| p | float | 1.0 | Probability of applying the transform. Defaults to 1.0. |
Example
>>> import albumentations as A
>>> transform = A.BBoxSafeRandomCrop(erosion_rate=0.2)
>>> result = transform(
... image=image,
... bboxes=[[0.1, 0.2, 0.5, 0.7, 'cat'], [0.3, 0.4, 0.6, 0.8, 'dog']],
... bbox_format='yolo' # or 'coco', 'pascal_voc'
... )
>>> transformed_image = result['image']
>>> transformed_bboxes = result['bboxes']Notes
- All bounding boxes will be preserved in their entirety - Aspect ratio is preserved only when no bounding boxes are present - May be more restrictive in crop placement compared to AtLeastOneBboxRandomCrop - The crop size is determined by the bounding boxes when present
BaseCropclass
BaseCrop(
p: float = 0.5
)Base class for transforms that only perform cropping.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| p | float | 0.5 | - |
BaseCropAndPadclass
BaseCropAndPad(
pad_if_needed: bool,
border_mode: Literal[cv2.BORDER_CONSTANT, cv2.BORDER_REPLICATE, cv2.BORDER_REFLECT, cv2.BORDER_WRAP, cv2.BORDER_REFLECT_101],
fill: tuple[float, ...] | float,
fill_mask: tuple[float, ...] | float,
pad_position: Literal['center', 'top_left', 'top_right', 'bottom_left', 'bottom_right', 'random'],
p: float
)Base class for transforms that need both cropping and padding.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| pad_if_needed | bool | - | - |
| border_mode | One of:
| - | - |
| fill | One of:
| - | - |
| fill_mask | One of:
| - | - |
| pad_position | One of:
| - | - |
| p | float | - | - |
BaseRandomSizedCropInitSchemaclass
BaseRandomSizedCropInitSchema(
p: Annotated,
strict: bool = False,
size: Annotated
)Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| p | Annotated | - | - |
| strict | bool | False | - |
| size | Annotated | - | - |
CenterCropclass
CenterCrop(
height: int,
width: int,
pad_if_needed: bool = False,
pad_position: Literal['center', 'top_left', 'top_right', 'bottom_left', 'bottom_right', 'random'] = center,
border_mode: Literal[cv2.BORDER_CONSTANT, cv2.BORDER_REPLICATE, cv2.BORDER_REFLECT, cv2.BORDER_WRAP, cv2.BORDER_REFLECT_101] = 0,
fill: tuple[float, ...] | float = 0.0,
fill_mask: tuple[float, ...] | float = 0.0,
p: float = 1.0
)Crop the central part of the input. This transform crops the center of the input image, mask, bounding boxes, and keypoints to the specified dimensions. It's useful when you want to focus on the central region of the input, discarding peripheral information.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| height | int | - | The height of the crop. Must be greater than 0. |
| width | int | - | The width of the crop. Must be greater than 0. |
| pad_if_needed | bool | False | Whether to pad if crop size exceeds image size. Default: False. |
| pad_position | One of:
| center | Position of padding. Default: 'center'. |
| border_mode | One of:
| 0 | OpenCV border mode used for padding. Default: cv2.BORDER_CONSTANT. |
| fill | One of:
| 0.0 | Padding value for images if border_mode is cv2.BORDER_CONSTANT. Default: 0. |
| fill_mask | One of:
| 0.0 | Padding value for masks if border_mode is cv2.BORDER_CONSTANT. Default: 0. |
| p | float | 1.0 | Probability of applying the transform. Default: 1.0. |
Notes
- If pad_if_needed is False and crop size exceeds image dimensions, it will raise a CropSizeError. - If pad_if_needed is True and crop size exceeds image dimensions, the image will be padded. - For bounding boxes and keypoints, coordinates are adjusted appropriately for both padding and cropping.
Cropclass
Crop(
x_min: int = 0,
y_min: int = 0,
x_max: int = 1024,
y_max: int = 1024,
pad_if_needed: bool = False,
pad_position: Literal['center', 'top_left', 'top_right', 'bottom_left', 'bottom_right', 'random'] = center,
border_mode: Literal[cv2.BORDER_CONSTANT, cv2.BORDER_REPLICATE, cv2.BORDER_REFLECT, cv2.BORDER_WRAP, cv2.BORDER_REFLECT_101] = 0,
fill: tuple[float, ...] | float = 0,
fill_mask: tuple[float, ...] | float = 0,
p: float = 1.0
)Crop a specific region from the input image. This transform crops a rectangular region from the input image, mask, bounding boxes, and keypoints based on specified coordinates. It's useful when you want to extract a specific area of interest from your inputs.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| x_min | int | 0 | Minimum x-coordinate of the crop region (left edge). Must be >= 0. Default: 0. |
| y_min | int | 0 | Minimum y-coordinate of the crop region (top edge). Must be >= 0. Default: 0. |
| x_max | int | 1024 | Maximum x-coordinate of the crop region (right edge). Must be > x_min. Default: 1024. |
| y_max | int | 1024 | Maximum y-coordinate of the crop region (bottom edge). Must be > y_min. Default: 1024. |
| pad_if_needed | bool | False | Whether to pad if crop coordinates exceed image dimensions. Default: False. |
| pad_position | One of:
| center | Position of padding. Default: 'center'. |
| border_mode | One of:
| 0 | OpenCV border mode used for padding. Default: cv2.BORDER_CONSTANT. |
| fill | One of:
| 0 | Padding value if border_mode is cv2.BORDER_CONSTANT. Default: 0. |
| fill_mask | One of:
| 0 | Padding value for masks. Default: 0. |
| p | float | 1.0 | Probability of applying the transform. Default: 1.0. |
Notes
- The crop coordinates are applied as follows: x_min <= x < x_max and y_min <= y < y_max. - If pad_if_needed is False and crop region extends beyond image boundaries, it will be clipped. - If pad_if_needed is True, image will be padded to accommodate the full crop region. - For bounding boxes and keypoints, coordinates are adjusted appropriately for both padding and cropping.
CropAndPadclass
CropAndPad(
px: int | list[int] | None = None,
percent: float | list[float] | None = None,
keep_size: bool = True,
sample_independently: bool = True,
interpolation: Literal[cv2.INTER_NEAREST, cv2.INTER_NEAREST_EXACT, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4, cv2.INTER_LINEAR_EXACT] = 1,
mask_interpolation: Literal[cv2.INTER_NEAREST, cv2.INTER_NEAREST_EXACT, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4, cv2.INTER_LINEAR_EXACT] = 0,
border_mode: Literal[cv2.BORDER_CONSTANT, cv2.BORDER_REPLICATE, cv2.BORDER_REFLECT, cv2.BORDER_WRAP, cv2.BORDER_REFLECT_101] = 0,
fill: tuple[float, ...] | float = 0,
fill_mask: tuple[float, ...] | float = 0,
p: float = 1.0
)Crop and pad images by pixel amounts or fractions of image sizes. This transform allows for simultaneous cropping and padding of images. Cropping removes pixels from the sides (i.e., extracts a subimage), while padding adds pixels to the sides (e.g., black pixels). The amount of cropping/padding can be specified either in absolute pixels or as a fraction of the image size.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| px | One of:
| None | The number of pixels to crop (negative values) or pad (positive values) on each side of the image. Either this or the parameter `percent` may be set, not both at the same time. - If int: crop/pad all sides by this value. - If tuple of 2 ints: crop/pad by (top/bottom, left/right). - If tuple of 4 ints: crop/pad by (top, right, bottom, left). - Each int can also be a tuple of 2 ints for a range, or a list of ints for discrete choices. Default: None. |
| percent | One of:
| None | The fraction of the image size to crop (negative values) or pad (positive values) on each side. Either this or the parameter `px` may be set, not both at the same time. - If float: crop/pad all sides by this fraction. - If tuple of 2 floats: crop/pad by (top/bottom, left/right) fractions. - If tuple of 4 floats: crop/pad by (top, right, bottom, left) fractions. - Each float can also be a tuple of 2 floats for a range, or a list of floats for discrete choices. Default: None. |
| keep_size | bool | True | If True, the output image will be resized to the input image size after cropping/padding. Default: True. |
| sample_independently | bool | True | If True and ranges are used for px/percent, sample a value for each side independently. If False, sample one value and use it for all sides. Default: True. |
| interpolation | One of:
| 1 | OpenCV interpolation flag used for resizing if keep_size is True. Default: cv2.INTER_LINEAR. |
| mask_interpolation | One of:
| 0 | OpenCV interpolation flag used for resizing if keep_size is True. Should be one of: cv2.INTER_NEAREST, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4. Default: cv2.INTER_NEAREST. |
| border_mode | One of:
| 0 | OpenCV border mode used for padding. Default: cv2.BORDER_CONSTANT. |
| fill | One of:
| 0 | The constant value to use for padding if border_mode is cv2.BORDER_CONSTANT. Default: 0. |
| fill_mask | One of:
| 0 | Same as fill but used for mask padding. Default: 0. |
| p | float | 1.0 | Probability of applying the transform. Default: 1.0. |
Example
>>> import albumentations as A
>>> transform = A.Compose([
... A.CropAndPad(px=(-10, 20, 30, -40), border_mode=cv2.BORDER_REFLECT, fill=128, p=1.0),
... ])
>>> transformed = transform(image=image, mask=mask, bboxes=bboxes, keypoints=keypoints)
>>> transformed_image = transformed['image']
>>> transformed_mask = transformed['mask']
>>> transformed_bboxes = transformed['bboxes']
>>> transformed_keypoints = transformed['keypoints']Notes
- This transform will never crop images below a height or width of 1. - When using pixel values (px), the image will be cropped/padded by exactly that many pixels. - When using percentages (percent), the amount of crop/pad will be calculated based on the image size. - Bounding boxes that end up fully outside the image after cropping will be removed. - Keypoints that end up outside the image after cropping will be removed.
CropNonEmptyMaskIfExistsclass
CropNonEmptyMaskIfExists(
height: int,
width: int,
ignore_values: list[int] | None = None,
ignore_channels: list[int] | None = None,
p: float = 1.0
)Crop area with mask if mask is non-empty, else make random crop. This transform attempts to crop a region containing a mask (non-zero pixels). If the mask is empty or not provided, it falls back to a random crop. This is particularly useful for segmentation tasks where you want to focus on regions of interest defined by the mask.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| height | int | - | Vertical size of crop in pixels. Must be > 0. |
| width | int | - | Horizontal size of crop in pixels. Must be > 0. |
| ignore_values | One of:
| None | Values to ignore in mask, `0` values are always ignored. For example, if background value is 5, set `ignore_values=[5]` to ignore it. Default: None. |
| ignore_channels | One of:
| None | Channels to ignore in mask. For example, if background is the first channel, set `ignore_channels=[0]` to ignore it. Default: None. |
| p | float | 1.0 | Probability of applying the transform. Default: 1.0. |
Example
>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> mask = np.zeros((100, 100), dtype=np.uint8)
>>> mask[25:75, 25:75] = 1 # Create a non-empty region in the mask
>>> transform = A.Compose([
... A.CropNonEmptyMaskIfExists(height=50, width=50, p=1.0),
... ])
>>> transformed = transform(image=image, mask=mask)
>>> transformed_image = transformed['image']
>>> transformed_mask = transformed['mask']
# The resulting crop will likely include part of the non-zero region in the maskNotes
- If a mask is provided, the transform will try to crop an area containing non-zero (or non-ignored) pixels. - If no suitable area is found in the mask or no mask is provided, it will perform a random crop. - The crop size (height, width) must not exceed the original image dimensions. - Bounding boxes and keypoints are also cropped along with the image and mask.
CropSizeErrorclass
CropSizeError()RandomCropclass
RandomCrop(
height: int,
width: int,
pad_if_needed: bool = False,
pad_position: Literal['center', 'top_left', 'top_right', 'bottom_left', 'bottom_right', 'random'] = center,
border_mode: Literal[cv2.BORDER_CONSTANT, cv2.BORDER_REPLICATE, cv2.BORDER_REFLECT, cv2.BORDER_WRAP, cv2.BORDER_REFLECT_101] = 0,
fill: tuple[float, ...] | float = 0.0,
fill_mask: tuple[float, ...] | float = 0.0,
p: float = 1.0
)Crop a random part of the input.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| height | int | - | height of the crop. |
| width | int | - | width of the crop. |
| pad_if_needed | bool | False | Whether to pad if crop size exceeds image size. Default: False. |
| pad_position | One of:
| center | Position of padding. Default: 'center'. |
| border_mode | One of:
| 0 | OpenCV border mode used for padding. Default: cv2.BORDER_CONSTANT. |
| fill | One of:
| 0.0 | Padding value for images if border_mode is cv2.BORDER_CONSTANT. Default: 0. |
| fill_mask | One of:
| 0.0 | Padding value for masks if border_mode is cv2.BORDER_CONSTANT. Default: 0. |
| p | float | 1.0 | Probability of applying the transform. Default: 1.0. |
Notes
If pad_if_needed is True and crop size exceeds image dimensions, the image will be padded before applying the random crop.
RandomCropFromBordersclass
RandomCropFromBorders(
crop_left: float = 0.1,
crop_right: float = 0.1,
crop_top: float = 0.1,
crop_bottom: float = 0.1,
p: float = 1.0
)Randomly crops the input from its borders without resizing. This transform randomly crops parts of the input (image, mask, bounding boxes, or keypoints) from each of its borders. The amount of cropping is specified as a fraction of the input's dimensions for each side independently.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| crop_left | float | 0.1 | The maximum fraction of width to crop from the left side. Must be in the range [0.0, 1.0]. Default: 0.1 |
| crop_right | float | 0.1 | The maximum fraction of width to crop from the right side. Must be in the range [0.0, 1.0]. Default: 0.1 |
| crop_top | float | 0.1 | The maximum fraction of height to crop from the top. Must be in the range [0.0, 1.0]. Default: 0.1 |
| crop_bottom | float | 0.1 | The maximum fraction of height to crop from the bottom. Must be in the range [0.0, 1.0]. Default: 0.1 |
| p | float | 1.0 | Probability of applying the transform. Default: 1.0 |
Example
>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.RandomCropFromBorders(
... crop_left=0.1, crop_right=0.2, crop_top=0.2, crop_bottom=0.1, p=1.0
... )
>>> result = transform(image=image)
>>> transformed_image = result['image']
# The resulting image will have random crops from each border, with the maximum
# possible crops being 10% from the left, 20% from the right, 20% from the top,
# and 10% from the bottom. The image size will be reduced accordingly.Notes
- The actual amount of cropping for each side is randomly chosen between 0 and the specified maximum for each application of the transform. - The sum of crop_left and crop_right must not exceed 1.0, and the sum of crop_top and crop_bottom must not exceed 1.0. Otherwise, a ValueError will be raised. - This transform does not resize the input after cropping, so the output dimensions will be smaller than the input dimensions. - Bounding boxes that end up fully outside the cropped area will be removed. - Keypoints that end up outside the cropped area will be removed.
RandomCropNearBBoxclass
RandomCropNearBBox(
max_part_shift: tuple[float, float] | float = (0, 0.3),
cropping_bbox_key: str = cropping_bbox,
p: float = 1.0
)Crop bbox from image with random shift by x,y coordinates
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| max_part_shift | One of:
| (0, 0.3) | Max shift in `height` and `width` dimensions relative to `cropping_bbox` dimension. If max_part_shift is a single float, the range will be (0, max_part_shift). Default (0, 0.3). |
| cropping_bbox_key | str | cropping_bbox | Additional target key for cropping box. Default `cropping_bbox`. |
| p | float | 1.0 | probability of applying the transform. Default: 1. |
RandomResizedCropclass
RandomResizedCrop(
size: tuple[int, int],
scale: tuple[float, float] = (0.08, 1.0),
ratio: tuple[float, float] = (0.75, 1.3333333333333333),
interpolation: Literal[cv2.INTER_NEAREST, cv2.INTER_NEAREST_EXACT, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4, cv2.INTER_LINEAR_EXACT] = 1,
mask_interpolation: Literal[cv2.INTER_NEAREST, cv2.INTER_NEAREST_EXACT, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4, cv2.INTER_LINEAR_EXACT] = 0,
p: float = 1.0
)Crop a random part of the input and rescale it to a specified size. This transform first crops a random portion of the input image (or mask, bounding boxes, keypoints) and then resizes the crop to a specified size. It's particularly useful for training neural networks on images of varying sizes and aspect ratios.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| size | tuple[int, int] | - | Target size for the output image, i.e. (height, width) after crop and resize. |
| scale | tuple[float, float] | (0.08, 1.0) | Range of the random size of the crop relative to the input size. For example, (0.08, 1.0) means the crop size will be between 8% and 100% of the input size. Default: (0.08, 1.0) |
| ratio | tuple[float, float] | (0.75, 1.3333333333333333) | Range of aspect ratios of the random crop. For example, (0.75, 1.3333) allows crop aspect ratios from 3:4 to 4:3. Default: (0.75, 1.3333333333333333) |
| interpolation | One of:
| 1 | Flag that is used to specify the interpolation algorithm. Should be one of: cv2.INTER_NEAREST, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4. Default: cv2.INTER_LINEAR |
| mask_interpolation | One of:
| 0 | Flag that is used to specify the interpolation algorithm for mask. Should be one of: cv2.INTER_NEAREST, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4. Default: cv2.INTER_NEAREST |
| p | float | 1.0 | Probability of applying the transform. Default: 1.0 |
Example
>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.RandomResizedCrop(size=80, scale=(0.5, 1.0), ratio=(0.75, 1.33), p=1.0)
>>> result = transform(image=image)
>>> transformed_image = result['image']
# transformed_image will be a 80x80 crop from a random location in the original image,
# with the crop's size between 50% and 100% of the original image size,
# and the crop's aspect ratio between 3:4 and 4:3.Notes
- This transform attempts to crop a random area with an aspect ratio and relative size specified by 'ratio' and 'scale' parameters. If it fails to find a suitable crop after 10 attempts, it will return a crop from the center of the image. - The crop's aspect ratio is defined as width / height. - Bounding boxes that end up fully outside the cropped area will be removed. - Keypoints that end up outside the cropped area will be removed. - After cropping, the result is resized to the specified size.
RandomSizedBBoxSafeCropclass
RandomSizedBBoxSafeCrop(
height: int,
width: int,
erosion_rate: float = 0.0,
interpolation: Literal[cv2.INTER_NEAREST, cv2.INTER_NEAREST_EXACT, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4, cv2.INTER_LINEAR_EXACT] = 1,
mask_interpolation: Literal[cv2.INTER_NEAREST, cv2.INTER_NEAREST_EXACT, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4, cv2.INTER_LINEAR_EXACT] = 0,
p: float = 1.0
)Crop a random part of the input and rescale it to a specific size without loss of bounding boxes. This transform first attempts to crop a random portion of the input image while ensuring that all bounding boxes remain within the cropped area. It then resizes the crop to the specified size. This is particularly useful for object detection tasks where preserving all objects in the image is crucial while also standardizing the image size.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| height | int | - | Height of the output image after resizing. |
| width | int | - | Width of the output image after resizing. |
| erosion_rate | float | 0.0 | A value between 0.0 and 1.0 that determines the minimum allowable size of the crop as a fraction of the original image size. For example, an erosion_rate of 0.2 means the crop will be at least 80% of the original image height and width. Default: 0.0 (no minimum size). |
| interpolation | One of:
| 1 | Flag that is used to specify the interpolation algorithm. Should be one of: cv2.INTER_NEAREST, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.AREA, cv2.INTER_LANCZOS4. Default: cv2.INTER_LINEAR. |
| mask_interpolation | One of:
| 0 | Flag that is used to specify the interpolation algorithm for mask. Should be one of: cv2.INTER_NEAREST, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.AREA, cv2.INTER_LANCZOS4. Default: cv2.INTER_NEAREST. |
| p | float | 1.0 | Probability of applying the transform. Default: 1.0. |
Example
>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (300, 300, 3), dtype=np.uint8)
>>> bboxes = [(10, 10, 50, 50), (100, 100, 150, 150)]
>>> transform = A.Compose([
... A.RandomSizedBBoxSafeCrop(height=224, width=224, erosion_rate=0.2, p=1.0),
... ], bbox_params=A.BboxParams(format='pascal_voc', label_fields=['labels']))
>>> transformed = transform(image=image, bboxes=bboxes, labels=['cat', 'dog'])
>>> transformed_image = transformed['image']
>>> transformed_bboxes = transformed['bboxes']
# transformed_image will be a 224x224 image containing all original bounding boxes,
# with their coordinates adjusted to the new image size.Notes
- This transform ensures that all bounding boxes in the original image are fully contained within the cropped area. If it's not possible to find such a crop (e.g., when bounding boxes are too spread out), it will default to cropping the entire image. - After cropping, the result is resized to the specified (height, width) size. - Bounding box coordinates are adjusted to match the new image size. - Keypoints are moved along with the crop and scaled to the new image size. - If there are no bounding boxes in the image, it will fall back to a random crop.
RandomSizedCropclass
RandomSizedCrop(
min_max_height: tuple[int, int],
size: tuple[int, int],
w2h_ratio: float = 1.0,
interpolation: Literal[cv2.INTER_NEAREST, cv2.INTER_NEAREST_EXACT, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4, cv2.INTER_LINEAR_EXACT] = 1,
mask_interpolation: Literal[cv2.INTER_NEAREST, cv2.INTER_NEAREST_EXACT, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4, cv2.INTER_LINEAR_EXACT] = 0,
p: float = 1.0
)Crop a random part of the input and rescale it to a specific size. This transform first crops a random portion of the input and then resizes it to a specified size. The size of the random crop is controlled by the 'min_max_height' parameter.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| min_max_height | tuple[int, int] | - | Minimum and maximum height of the crop in pixels. |
| size | tuple[int, int] | - | Target size for the output image, i.e. (height, width) after crop and resize. |
| w2h_ratio | float | 1.0 | Aspect ratio (width/height) of crop. Default: 1.0 |
| interpolation | One of:
| 1 | Flag that is used to specify the interpolation algorithm. Should be one of: cv2.INTER_NEAREST, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4. Default: cv2.INTER_LINEAR. |
| mask_interpolation | One of:
| 0 | Flag that is used to specify the interpolation algorithm for mask. Should be one of: cv2.INTER_NEAREST, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4. Default: cv2.INTER_NEAREST. |
| p | float | 1.0 | Probability of applying the transform. Default: 1.0 |
Example
>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.RandomSizedCrop(
... min_max_height=(50, 80),
... size=(64, 64),
... w2h_ratio=1.0,
... interpolation=cv2.INTER_LINEAR,
... p=1.0
... )
>>> result = transform(image=image)
>>> transformed_image = result['image']
# transformed_image will be a 64x64 image, resulting from a crop with height
# between 50 and 80 pixels, and the same aspect ratio as specified by w2h_ratio,
# taken from a random location in the original image and then resized.Notes
- The crop size is randomly selected for each execution within the range specified by 'min_max_height'. - The aspect ratio of the crop is determined by the 'w2h_ratio' parameter. - After cropping, the result is resized to the specified 'size'. - Bounding boxes that end up fully outside the cropped area will be removed. - Keypoints that end up outside the cropped area will be removed. - This transform differs from RandomResizedCrop in that it allows more control over the crop size through the 'min_max_height' parameter, rather than using a scale parameter.