Add area to resized crop (#2537)

* Added downscale_area to ResizedCrop and SizedCrop

* Added downscale_area to ResizedCrop and SizedCrop

* Fix

* Typofix

* fix

Author: ternaus

.cursor/rules/albumentations-rules.mdc

@@ -9,3 +9,4 @@ alwaysApply: true
 - We use python 3.10+ typing. I.e. not Tuple, but tuple, not List, but list, not Optional, but | None
 - get_params_dependent_on_data should look minimal, but should look small and clear as we just call other functions from it
 - we do not use fill_value, but fill. Not fill_mask_value, but fill_mask
+- We do not have ANY default values in the InitSchema class

.cursor/rules/coding-guidelines.mdc

@@ -390,6 +390,44 @@ Each transform must include an `InitSchema` class that inherits from `BaseTransf
           self.brightness_coefficient = brightness_coefficient
   ```
 
+#### No Default Values in InitSchema
+
+**InitSchema classes must not contain default values for their fields.** This ensures that all transform parameters are explicitly provided and validated at initialization time.
+
+```python
+# Correct - no default values in InitSchema
+class MyTransform(ImageOnlyTransform):
+    class InitSchema(BaseTransformInitSchema):
+        brightness_range: tuple[float, float]
+        contrast_range: tuple[float, float]
+
+    def __init__(self, brightness_range: tuple[float, float] = (0.8, 1.2),
+                 contrast_range: tuple[float, float] = (0.8, 1.2), p: float = 0.5):
+        # Default values go in __init__, not InitSchema
+        super().__init__(p=p)
+        self.brightness_range = brightness_range
+        self.contrast_range = contrast_range
+
+# Incorrect - default values in InitSchema
+class MyTransform(ImageOnlyTransform):
+    class InitSchema(BaseTransformInitSchema):
+        brightness_range: tuple[float, float] = (0.8, 1.2)  # ❌ No defaults in InitSchema
+        contrast_range: tuple[float, float] = (0.8, 1.2)    # ❌ No defaults in InitSchema
+```
+
+##### Exception: Discriminator Fields
+
+The only exception to this rule is discriminator fields used for Pydantic discriminated unions, where the default value must match the literal type:
+
+```python
+# Correct - discriminator field with matching default
+class UniformParams(NoiseParamsBase):
+    noise_type: Literal["uniform"] = "uniform"  # ✅ Required for discriminated unions
+    ranges: list[Sequence[float]]
+```
+
+This rule is enforced by a pre-commit hook that will flag any violations during development.
+
 ### Coordinate Systems
 
 #### Image Center Calculations
@@ -468,8 +506,9 @@ Every transform class that is a descendant of `ImageOnlyTransform`, `DualTransfo
 
 4. **Target-Specific Requirements**:
    - For `ImageOnlyTransform`: Pass and demonstrate transformation of image data. Including how to get all transformed targets.
-   - For `DualTransform`: Pass and demonstrate transformation of image, mask, bboxes, keypoints, bbox_labels, class_labels (where supported). Including how to get all transformed targets
+   - For `DualTransform`: Pass and demonstrate transformation of image, mask, bboxes, keypoints, bbox_labels, class_labels (where supported). Including how to get all transformed targets including bbox_labels and keypoints_labels
    - For `Transform3D`: Pass and demonstrate transformation of volume and mask3d data. Including how to get all transformed targets.
+    Including keypoint_labels
 
 5. **For Base Classes**: Examples for base classes should show:
    - How to initialize a custom transform that inherits from the base class

.pre-commit-config.yaml

@@ -55,6 +55,13 @@ repos:
       files: ^albumentations/
       pass_filenames: true
       additional_dependencies: ["google-docstring-parser>=0.0.7"]
+    - id: check-no-defaults-in-schemas
+      name: Check no defaults in BaseModel schemas
+      entry: python tools/check_no_defaults_in_schemas.py
+      language: python
+      types: [python]
+      files: ^albumentations/
+      pass_filenames: true
   - repo: local
     hooks:
       - id: check-albucore-version

albumentations/augmentations/crops/transforms.py

@@ -1498,6 +1498,12 @@ class _BaseRandomSizedCrop(DualTransform):
             for image resizing. Default: cv2.INTER_LINEAR.
         mask_interpolation (OpenCV flag): Flag that is used to specify the interpolation
             algorithm for mask resizing. Default: cv2.INTER_NEAREST.
+        area_for_downscale (Literal[None, "image", "image_mask"]): Controls automatic use of INTER_AREA interpolation
+            for downscaling. Options:
+            - None: No automatic interpolation selection, always use the specified interpolation method
+            - "image": Use INTER_AREA when downscaling images, retain specified interpolation for upscaling and masks
+            - "image_mask": Use INTER_AREA when downscaling both images and masks
+            Default: None.
         p (float): Probability of applying the transform. Default: 1.0.
 
     Targets:
@@ -1510,6 +1516,8 @@ class _BaseRandomSizedCrop(DualTransform):
         This class is not meant to be used directly. Instead, use derived transforms
         like RandomSizedCrop or RandomResizedCrop that implement specific crop selection
         strategies.
+        When area_for_downscale is set, INTER_AREA interpolation will be used automatically for
+        downscaling (when the crop is larger than the target size), which provides better quality for size reduction.
 
     Examples:
         >>> import numpy as np
@@ -1524,12 +1532,14 @@ class _BaseRandomSizedCrop(DualTransform):
         ...         custom_parameter=0.5,
         ...         interpolation=cv2.INTER_LINEAR,
         ...         mask_interpolation=cv2.INTER_NEAREST,
+        ...         area_for_downscale="image",
         ...         p=1.0
         ...     ):
         ...         super().__init__(
         ...             size=size,
         ...             interpolation=interpolation,
         ...             mask_interpolation=mask_interpolation,
+        ...             area_for_downscale=area_for_downscale,
         ...             p=p,
         ...         )
         ...         self.custom_parameter = custom_parameter
@@ -1560,7 +1570,7 @@ class _BaseRandomSizedCrop(DualTransform):
         >>>
         >>> # Create a pipeline with our custom transform
         >>> transform = A.Compose(
-        ...     [CustomRandomCrop(size=(64, 64), custom_parameter=0.6)],
+        ...     [CustomRandomCrop(size=(64, 64), custom_parameter=0.6, area_for_downscale="image")],
         ...     bbox_params=A.BboxParams(format='pascal_voc', label_fields=['bbox_labels']),
         ...     keypoint_params=A.KeypointParams(format='xy', label_fields=['keypoint_labels'])
         ... )
@@ -1604,6 +1614,7 @@ class InitSchema(BaseRandomSizedCropInitSchema):
             cv2.INTER_LANCZOS4,
             cv2.INTER_LINEAR_EXACT,
         ]
+        area_for_downscale: Literal[None, "image", "image_mask"]
 
     def __init__(
         self,
@@ -1626,12 +1637,39 @@ def __init__(
             cv2.INTER_LANCZOS4,
             cv2.INTER_LINEAR_EXACT,
         ] = cv2.INTER_NEAREST,
+        area_for_downscale: Literal[None, "image", "image_mask"] = None,
         p: float = 1.0,
     ):
         super().__init__(p=p)
         self.size = size
         self.interpolation = interpolation
         self.mask_interpolation = mask_interpolation
+        self.area_for_downscale = area_for_downscale
+
+    def _get_interpolation_for_resize(self, crop_shape: tuple[int, int], target_type: str) -> int:
+        """Get the appropriate interpolation method for resizing.
+
+        Args:
+            crop_shape: Shape of the crop (height, width)
+            target_type: Either "image" or "mask" to determine base interpolation
+
+        Returns:
+            OpenCV interpolation flag
+
+        """
+        crop_height, crop_width = crop_shape
+        target_height, target_width = self.size
+
+        # Determine if this is downscaling
+        is_downscale = (crop_height > target_height) or (crop_width > target_width)
+
+        # Use INTER_AREA for downscaling if configured
+        if (is_downscale and (target_type == "image" and self.area_for_downscale in ["image", "image_mask"])) or (
+            target_type == "mask" and self.area_for_downscale == "image_mask"
+        ):
+            return cv2.INTER_AREA
+        # Get base interpolation
+        return self.interpolation if target_type == "image" else self.mask_interpolation
 
     def apply(
         self,
@@ -1648,7 +1686,8 @@ def apply(
 
         """
         crop = fcrops.crop(img, *crop_coords)
-        return fgeometric.resize(crop, self.size, self.interpolation)
+        interpolation = self._get_interpolation_for_resize(crop.shape[:2], "image")
+        return fgeometric.resize(crop, self.size, interpolation)
 
     def apply_to_mask(
         self,
@@ -1665,7 +1704,8 @@ def apply_to_mask(
 
         """
         crop = fcrops.crop(mask, *crop_coords)
-        return fgeometric.resize(crop, self.size, self.mask_interpolation)
+        interpolation = self._get_interpolation_for_resize(crop.shape[:2], "mask")
+        return fgeometric.resize(crop, self.size, interpolation)
 
     def apply_to_bboxes(
         self,
@@ -1731,8 +1771,11 @@ def apply_to_images(
         # First crop the volume using volume_crop_yx (reduces data size)
         crop = fcrops.volume_crop_yx(images, *crop_coords)
 
-        # Then resize the smaller cropped volume using decorated helper method
-        return np.stack([fgeometric.resize(crop[i], self.size, self.interpolation) for i in range(images.shape[0])])
+        # Get interpolation method based on crop dimensions
+        interpolation = self._get_interpolation_for_resize(crop.shape[1:3], "image")
+
+        # Then resize the smaller cropped volume using the selected interpolation
+        return np.stack([fgeometric.resize(crop[i], self.size, interpolation) for i in range(images.shape[0])])
 
     def apply_to_volume(
         self,
@@ -1783,6 +1826,12 @@ class RandomSizedCrop(_BaseRandomSizedCrop):
         mask_interpolation (OpenCV flag): 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.
+        area_for_downscale (Literal[None, "image", "image_mask"]): Controls automatic use of INTER_AREA interpolation
+            for downscaling. Options:
+            - None: No automatic interpolation selection, always use the specified interpolation method
+            - "image": Use INTER_AREA when downscaling images, retain specified interpolation for upscaling and masks
+            - "image_mask": Use INTER_AREA when downscaling both images and masks
+            Default: None.
         p (float): Probability of applying the transform. Default: 1.0
 
     Targets:
@@ -1799,6 +1848,8 @@ class RandomSizedCrop(_BaseRandomSizedCrop):
         - 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.
+        - When area_for_downscale is set, INTER_AREA interpolation will be used automatically for
+          downscaling (when the crop is larger than the target size), which provides better quality for size reduction.
 
     Mathematical Details:
         1. A random crop height h is sampled from the range [min_max_height[0], min_max_height[1]].
@@ -1828,6 +1879,7 @@ class RandomSizedCrop(_BaseRandomSizedCrop):
         ...         w2h_ratio=1.0,
         ...         interpolation=cv2.INTER_LINEAR,
         ...         mask_interpolation=cv2.INTER_NEAREST,
+        ...         area_for_downscale="image",  # Use INTER_AREA for image downscaling
         ...         p=1.0
         ...     ),
         ... ], bbox_params=A.BboxParams(format='pascal_voc', label_fields=['bbox_labels']),
@@ -1877,6 +1929,7 @@ class InitSchema(BaseTransformInitSchema):
         min_max_height: OnePlusIntRangeType
         w2h_ratio: Annotated[float, Field(gt=0)]
         size: Annotated[tuple[int, int], AfterValidator(check_range_bounds(1, None))]
+        area_for_downscale: Literal[None, "image", "image_mask"]
 
     def __init__(
         self,
@@ -1901,12 +1954,14 @@ def __init__(
             cv2.INTER_LANCZOS4,
             cv2.INTER_LINEAR_EXACT,
         ] = cv2.INTER_NEAREST,
+        area_for_downscale: Literal[None, "image", "image_mask"] = None,
         p: float = 1.0,
     ):
         super().__init__(
             size=size,
             interpolation=interpolation,
             mask_interpolation=mask_interpolation,
+            area_for_downscale=area_for_downscale,
             p=p,
         )
         self.min_max_height = min_max_height
@@ -1960,6 +2015,12 @@ class RandomResizedCrop(_BaseRandomSizedCrop):
         mask_interpolation (OpenCV flag): 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
+        area_for_downscale (Literal[None, "image", "image_mask"]): Controls automatic use of INTER_AREA interpolation
+            for downscaling. Options:
+            - None: No automatic interpolation selection, always use the specified interpolation method
+            - "image": Use INTER_AREA when downscaling images, retain specified interpolation for upscaling and masks
+            - "image_mask": Use INTER_AREA when downscaling both images and masks
+            Default: None.
         p (float): Probability of applying the transform. Default: 1.0
 
     Targets:
@@ -1976,6 +2037,8 @@ class RandomResizedCrop(_BaseRandomSizedCrop):
         - 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.
+        - When area_for_downscale is set, INTER_AREA interpolation will be used automatically for
+          downscaling (when the crop is larger than the target size), which provides better quality for size reduction.
 
     Mathematical Details:
         1. A target area A is sampled from the range [scale[0] * input_area, scale[1] * input_area].
@@ -2009,6 +2072,7 @@ class RandomResizedCrop(_BaseRandomSizedCrop):
         ...         ratio=(0.75, 1.33),  # Aspect ratio will vary from 3:4 to 4:3
         ...         interpolation=cv2.INTER_LINEAR,
         ...         mask_interpolation=cv2.INTER_NEAREST,
+        ...         area_for_downscale="image",  # Use INTER_AREA for image downscaling
         ...         p=1.0
         ...     ),
         ... ], bbox_params=A.BboxParams(format='pascal_voc', label_fields=['bbox_labels']),
@@ -2062,6 +2126,7 @@ class InitSchema(BaseTransformInitSchema):
             cv2.INTER_LANCZOS4,
             cv2.INTER_LINEAR_EXACT,
         ]
+        area_for_downscale: Literal[None, "image", "image_mask"]
 
     def __init__(
         self,
@@ -2086,12 +2151,14 @@ def __init__(
             cv2.INTER_LANCZOS4,
             cv2.INTER_LINEAR_EXACT,
         ] = cv2.INTER_NEAREST,
+        area_for_downscale: Literal[None, "image", "image_mask"] = None,
         p: float = 1.0,
     ):
         super().__init__(
             size=size,
             interpolation=interpolation,
             mask_interpolation=mask_interpolation,
+            area_for_downscale=area_for_downscale,
             p=p,
         )
         self.scale = scale

albumentations/augmentations/geometric/resize.py

@@ -375,7 +375,7 @@ class MaxSizeTransform(DualTransform):
     class InitSchema(BaseTransformInitSchema):
         max_size: int | list[int] | None
         max_size_hw: tuple[int | None, int | None] | None
-        area_for_downscale: Literal[None, "image", "image_mask"] = None
+        area_for_downscale: Literal[None, "image", "image_mask"]
         interpolation: Literal[
             cv2.INTER_NEAREST,
             cv2.INTER_NEAREST_EXACT,
@@ -833,7 +833,7 @@ class Resize(DualTransform):
     class InitSchema(BaseTransformInitSchema):
         height: int = Field(ge=1)
         width: int = Field(ge=1)
-        area_for_downscale: Literal[None, "image", "image_mask"] = None
+        area_for_downscale: Literal[None, "image", "image_mask"]
         interpolation: Literal[
             cv2.INTER_NEAREST,
             cv2.INTER_NEAREST_EXACT,

albumentations/augmentations/geometric/transforms.py

@@ -1184,8 +1184,8 @@ class InitSchema(BaseTransformInitSchema):
             cv2.BORDER_REFLECT_101,
         ]
 
-        fill: tuple[float, ...] | float = 0
-        fill_mask: tuple[float, ...] | float = 0
+        fill: tuple[float, ...] | float
+        fill_mask: tuple[float, ...] | float
 
         shift_limit_x: tuple[float, float] | float | None
         shift_limit_y: tuple[float, float] | float | None

albumentations/augmentations/mixing/domain_adaptation.py

@@ -37,8 +37,8 @@
 
 # Base class for Domain Adaptation Init Schema
 class BaseDomainAdaptationInitSchema(BaseTransformInitSchema):
-    reference_images: Sequence[Any] | None = None
-    read_fn: Callable[[Any], np.ndarray] | None = None
+    reference_images: Sequence[Any] | None
+    read_fn: Callable[[Any], np.ndarray] | None
     metadata_key: str
 
     @model_validator(mode="after")