albumentations.augmentations.crops.basic

Crop a random region of fixed height and width. Optional pad when crop exceeds image. All targets cropped together. Common for fixed-resolution training. Args: height (int): height of the crop. width (int): width of the crop. pad_if_needed (bool): Whether to pad if crop size exceeds image size. Default: False. border_mode (OpenCV flag): OpenCV border mode used for padding. Default: cv2.BORDER_CONSTANT. fill (tuple[float, ...] | float): Padding value for images if border_mode is cv2.BORDER_CONSTANT. Default: 0. fill_mask (tuple[float, ...] | float): Padding value for masks if border_mode is cv2.BORDER_CONSTANT. Default: 0. pad_position (Literal['center', 'top_left', 'top_right', 'bottom_left', 'bottom_right', 'random']): Position of padding. Default: 'center'. p (float): Probability of applying the transform. Default: 1.0. Targets: image, mask, bboxes, keypoints, volume, mask3d Image types: uint8, float32 Supported bboxes: hbb, obb Note: If pad_if_needed is True and crop size exceeds image dimensions, the image will be padded before applying the random crop. Examples: >>> import numpy as np >>> import albumentations as A >>> import cv2 >>> >>> # Prepare sample data >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8) >>> bboxes = np.array([[10, 10, 50, 50], [40, 40, 80, 80]], dtype=np.float32) >>> bbox_labels = [1, 2] >>> keypoints = np.array([[20, 30], [60, 70]], dtype=np.float32) >>> keypoint_labels = [0, 1] >>> >>> # Example 1: Basic random crop >>> transform = A.Compose([ ... A.RandomCrop(height=64, width=64), ... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']), ... keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels'])) >>> >>> # Apply the transform >>> transformed = transform( ... image=image, ... mask=mask, ... bboxes=bboxes, ... bbox_labels=bbox_labels, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # Get the transformed data >>> transformed_image = transformed['image'] # Will be 64x64 >>> transformed_mask = transformed['mask'] # Will be 64x64 >>> transformed_bboxes = transformed['bboxes'] # Bounding boxes adjusted to the cropped area >>> transformed_bbox_labels = transformed['bbox_labels'] # Labels for boxes that remain after cropping >>> transformed_keypoints = transformed['keypoints'] # Keypoints adjusted to the cropped area >>> transformed_keypoint_labels = transformed['keypoint_labels'] # Labels for keypoints that remain >>> >>> # Example 2: Random crop with padding when needed >>> # This is useful when you want to crop to a size larger than some images >>> transform_padded = A.Compose([ ... A.RandomCrop( ... height=120, # Larger than original image height ... width=120, # Larger than original image width ... pad_if_needed=True, ... border_mode=cv2.BORDER_CONSTANT, ... fill=0, # Black padding for image ... fill_mask=0 # Zero padding for mask ... ), ... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']), ... keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels'])) >>> >>> # Apply the padded transform >>> padded_transformed = transform_padded( ... image=image, ... mask=mask, ... bboxes=bboxes, ... bbox_labels=bbox_labels, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # The result will be 120x120 with padding >>> padded_image = padded_transformed['image'] >>> padded_mask = padded_transformed['mask'] >>> padded_bboxes = padded_transformed['bboxes'] # Coordinates adjusted to the new dimensions

Parameters

Crop the center region of fixed height and width. Optional pad when crop exceeds image. All targets share the same center window. Good for center-focused data. 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. Args: 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): Whether to pad if crop size exceeds image size. Default: False. border_mode (OpenCV flag): OpenCV border mode used for padding. Default: cv2.BORDER_CONSTANT. fill (tuple[float, ...] | float): Padding value for images if border_mode is cv2.BORDER_CONSTANT. Default: 0. fill_mask (tuple[float, ...] | float): Padding value for masks if border_mode is cv2.BORDER_CONSTANT. Default: 0. pad_position (Literal['center', 'top_left', 'top_right', 'bottom_left', 'bottom_right', 'random']): Position of padding. Default: 'center'. p (float): Probability of applying the transform. Default: 1.0. Targets: image, mask, bboxes, keypoints, volume, mask3d Image types: uint8, float32 Supported bboxes: hbb, obb Note: - 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. Examples: >>> import numpy as np >>> import albumentations as A >>> import cv2 >>> >>> # Prepare sample data >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8) >>> bboxes = np.array([[10, 10, 50, 50], [40, 40, 80, 80]], dtype=np.float32) >>> bbox_labels = [1, 2] >>> keypoints = np.array([[20, 30], [60, 70]], dtype=np.float32) >>> keypoint_labels = [0, 1] >>> >>> # Example 1: Basic center crop without padding >>> transform = A.Compose([ ... A.CenterCrop(height=64, width=64), ... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']), ... keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels'])) >>> >>> # Apply the transform >>> transformed = transform( ... image=image, ... mask=mask, ... bboxes=bboxes, ... bbox_labels=bbox_labels, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # Get the transformed data >>> transformed_image = transformed['image'] # Will be 64x64 >>> transformed_mask = transformed['mask'] # Will be 64x64 >>> transformed_bboxes = transformed['bboxes'] # Bounding boxes adjusted to the cropped area >>> transformed_bbox_labels = transformed['bbox_labels'] # Labels for boxes that remain after cropping >>> transformed_keypoints = transformed['keypoints'] # Keypoints adjusted to the cropped area >>> transformed_keypoint_labels = transformed['keypoint_labels'] # Labels for keypoints that remain >>> >>> # Example 2: Center crop with padding when needed >>> transform_padded = A.Compose([ ... A.CenterCrop( ... height=120, # Larger than original image height ... width=120, # Larger than original image width ... pad_if_needed=True, ... border_mode=cv2.BORDER_CONSTANT, ... fill=0, # Black padding for image ... fill_mask=0 # Zero padding for mask ... ), ... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']), ... keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels'])) >>> >>> # Apply the padded transform >>> padded_transformed = transform_padded( ... image=image, ... mask=mask, ... bboxes=bboxes, ... bbox_labels=bbox_labels, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # The result will be 120x120 with padding >>> padded_image = padded_transformed['image'] >>> padded_mask = padded_transformed['mask'] >>> padded_bboxes = padded_transformed['bboxes'] # Coordinates adjusted to the new dimensions >>> padded_keypoints = padded_transformed['keypoints'] # Coordinates adjusted to the new dimensions

Parameters

Crop a fixed region by (x_min, y_min, x_max, y_max). Deterministic; optional pad when region exceeds image. Use for fixed ROI or sliding-window pipelines. 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. Args: x_min (int): Minimum x-coordinate of the crop region (left edge). Must be >= 0. Default: 0. y_min (int): Minimum y-coordinate of the crop region (top edge). Must be >= 0. Default: 0. x_max (int): Maximum x-coordinate of the crop region (right edge). Must be > x_min. Default: 1024. y_max (int): Maximum y-coordinate of the crop region (bottom edge). Must be > y_min. Default: 1024. pad_if_needed (bool): Whether to pad if crop coordinates exceed image dimensions. Default: False. border_mode (OpenCV flag): OpenCV border mode used for padding. Default: cv2.BORDER_CONSTANT. fill (tuple[float, ...] | float): Padding value if border_mode is cv2.BORDER_CONSTANT. Default: 0. fill_mask (tuple[float, ...] | float): Padding value for masks. Default: 0. pad_position (Literal['center', 'top_left', 'top_right', 'bottom_left', 'bottom_right', 'random']): Position of padding. Default: 'center'. p (float): Probability of applying the transform. Default: 1.0. Targets: image, mask, bboxes, keypoints, volume, mask3d Image types: uint8, float32 Supported bboxes: hbb, obb Note: - 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. Examples: >>> import numpy as np >>> import albumentations as A >>> import cv2 >>> >>> # Prepare sample data >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8) >>> bboxes = np.array([[10, 10, 50, 50], [40, 40, 80, 80]], dtype=np.float32) >>> bbox_labels = [1, 2] >>> keypoints = np.array([[20, 30], [60, 70]], dtype=np.float32) >>> keypoint_labels = [0, 1] >>> >>> # Example 1: Basic crop with fixed coordinates >>> transform = A.Compose([ ... A.Crop(x_min=20, y_min=20, x_max=80, y_max=80), ... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']), ... keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels'])) >>> >>> # Apply the transform >>> transformed = transform( ... image=image, ... mask=mask, ... bboxes=bboxes, ... bbox_labels=bbox_labels, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # Get the transformed data >>> transformed_image = transformed['image'] # Will be 60x60 - cropped from (20,20) to (80,80) >>> transformed_mask = transformed['mask'] # Will be 60x60 >>> transformed_bboxes = transformed['bboxes'] # Bounding boxes adjusted to the cropped area >>> transformed_bbox_labels = transformed['bbox_labels'] # Labels for boxes that remain after cropping >>> >>> # Example 2: Crop with padding when the crop region extends beyond image dimensions >>> transform_padded = A.Compose([ ... A.Crop( ... x_min=50, y_min=50, x_max=150, y_max=150, # Extends beyond the 100x100 image ... pad_if_needed=True, ... border_mode=cv2.BORDER_CONSTANT, ... fill=0, # Black padding for image ... fill_mask=0 # Zero padding for mask ... ), ... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']), ... keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels'])) >>> >>> # Apply the padded transform >>> padded_transformed = transform_padded( ... image=image, ... mask=mask, ... bboxes=bboxes, ... bbox_labels=bbox_labels, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # The result will be 100x100 (50:150, 50:150) with padding on right and bottom >>> padded_image = padded_transformed['image'] # 100x100 with 50 pixels of original + 50 pixels of padding >>> padded_mask = padded_transformed['mask'] >>> padded_bboxes = padded_transformed['bboxes'] # Coordinates adjusted to the cropped and padded area >>> >>> # Example 3: Crop with reflection padding and custom position >>> transform_reflect = A.Compose([ ... A.Crop( ... x_min=-20, y_min=-20, x_max=80, y_max=80, # Negative coordinates (outside image) ... pad_if_needed=True, ... border_mode=cv2.BORDER_REFLECT_101, # Reflect image for padding ... pad_position="top_left" # Apply padding at top-left ... ), ... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels'])) >>> >>> # The resulting crop will use reflection padding for the negative coordinates >>> reflect_result = transform_reflect( ... image=image, ... bboxes=bboxes, ... bbox_labels=bbox_labels ... )

Parameters

Crop or pad each side by pixels (px) or fractions (percent). Positive pad, negative crop. Per-side control via tuples. Good for letterboxing or trimming. 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. Args: px (int, tuple of int, tuple of tuples of int, or 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. Default: None. percent (float, tuple of float, tuple of tuples of float, or 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. Default: None. border_mode (int): OpenCV border mode used for padding. Default: cv2.BORDER_CONSTANT. fill (tuple[float, ...] | float): The constant value to use for padding if border_mode is cv2.BORDER_CONSTANT. Default: 0. fill_mask (tuple[float, ...] | float): Same as fill but used for mask padding. Default: 0. keep_size (bool): If True, the output image will be resized to the input image size after cropping/padding. Default: True. sample_independently (bool): 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 (int): OpenCV interpolation flag used for resizing if keep_size is True. Default: cv2.INTER_LINEAR. mask_interpolation (int): 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. p (float): Probability of applying the transform. Default: 1.0. Targets: image, mask, bboxes, keypoints, volume, mask3d Image types: uint8, float32 Supported bboxes: hbb, obb Note: - 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. Examples: >>> import numpy as np >>> import albumentations as A >>> import cv2 >>> >>> # Prepare sample data >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8) >>> bboxes = np.array([[10, 10, 50, 50], [40, 40, 80, 80]], dtype=np.float32) >>> bbox_labels = [1, 2] >>> keypoints = np.array([[20, 30], [60, 70]], dtype=np.float32) >>> keypoint_labels = [0, 1] >>> >>> # Example 1: Using px parameter with specific values for each side >>> # Crop 10px from top, pad 20px on right, pad 30px on bottom, crop 40px from left >>> transform_px = A.Compose([ ... A.CropAndPad( ... px=(-10, 20, 30, -40), # (top, right, bottom, left) ... border_mode=cv2.BORDER_CONSTANT, ... fill=128, # Gray padding color ... fill_mask=0, ... keep_size=False, # Don't resize back to original dimensions ... p=1.0 ... ), ... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']), ... keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels'])) >>> >>> # Apply the transform >>> result_px = transform_px( ... image=image, ... mask=mask, ... bboxes=bboxes, ... bbox_labels=bbox_labels, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # Get the transformed data with px parameters >>> transformed_image_px = result_px['image'] # Shape will be different from original >>> transformed_mask_px = result_px['mask'] >>> transformed_bboxes_px = result_px['bboxes'] # Adjusted to new dimensions >>> transformed_bbox_labels_px = result_px['bbox_labels'] # Bounding box labels after crop >>> transformed_keypoints_px = result_px['keypoints'] # Adjusted to new dimensions >>> transformed_keypoint_labels_px = result_px['keypoint_labels'] # Keypoint labels after crop >>> >>> # Example 2: Using percent parameter as a single value >>> # This will pad all sides by 10% of image dimensions >>> transform_percent = A.Compose([ ... A.CropAndPad( ... percent=0.1, # Pad all sides by 10% ... border_mode=cv2.BORDER_REFLECT, # Use reflection padding ... keep_size=True, # Resize back to original dimensions ... p=1.0 ... ), ... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']), ... keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels'])) >>> >>> # Apply the transform >>> result_percent = transform_percent( ... image=image, ... mask=mask, ... bboxes=bboxes, ... bbox_labels=bbox_labels, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # Get the transformed data with percent parameters >>> # Since keep_size=True, image dimensions remain the same (100x100) >>> transformed_image_pct = result_percent['image'] >>> transformed_mask_pct = result_percent['mask'] >>> transformed_bboxes_pct = result_percent['bboxes'] >>> transformed_bbox_labels_pct = result_percent['bbox_labels'] >>> transformed_keypoints_pct = result_percent['keypoints'] >>> transformed_keypoint_labels_pct = result_percent['keypoint_labels'] >>> >>> # Example 3: Random padding within a range >>> # Pad top and bottom by 5-15%, left and right by 10-20% >>> transform_random = A.Compose([ ... A.CropAndPad( ... percent=[(0.05, 0.15), (0.1, 0.2), (0.05, 0.15), (0.1, 0.2)], # (top, right, bottom, left) ... sample_independently=True, # Sample each side independently ... border_mode=cv2.BORDER_CONSTANT, ... fill=0, # Black padding ... keep_size=False, ... p=1.0 ... ), ... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']), ... keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels'])) >>> >>> # Result dimensions will vary based on the random padding values chosen

Parameters