albumentations.augmentations.utils
Module containing utility functions for augmentation operations. This module provides a collection of helper functions and utilities used throughout the augmentation pipeline. It includes functions for image loading, type checking, error handling, mathematical operations, and decorators that add functionality to other functions in the codebase. These utilities help ensure consistent behavior and simplify common operations across different augmentation transforms.
Members
- classPCA
- functionangle_2pi_range
- functioncheck_range
- functionhandle_empty_array
- functionnon_rgb_error
PCAclass
Principal Component Analysis (PCA) transformer. This class provides a wrapper around OpenCV's PCA implementation for dimensionality reduction. It can be used to project data onto a lower dimensional space while preserving as much variance as possible.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| n_components | One of:
| None | Number of components to keep. - If None: Keep all components (min of n_samples and n_features) - If int: Keep the specified number of components Must be greater than 0 if specified. |
Examples
>>> import numpy as np
>>> from albumentations.augmentations.utils import PCA
>>> # Create sample data
>>> data = np.random.randn(100, 10) # 100 samples, 10 features
>>> # Initialize PCA to keep 3 components
>>> pca = PCA(n_components=3)
>>> # Fit and transform the data
>>> transformed = pca.fit_transform(data)
>>> print(transformed.shape) # (100, 3)angle_2pi_rangefunction
Decorator to normalize angle values to the range [0, 2π). This decorator wraps a function that processes keypoints, ensuring that angle values (stored in the 4th column, index 3) are normalized to the range [0, 2π) after the wrapped function executes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| func | Callable[Concatenate[np.ndarray, P], np.ndarray] | - | Function that processes keypoints and returns a numpy array. The function should take a keypoints array as its first parameter. |
Returns
- Callable: Wrapped function that normalizes angles after processing keypoints.
check_rangefunction
Checks if the given value is within the specified bounds
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| value | tuple[float, float] | - | The value to check and convert. Can be a single float or a tuple of floats. |
| lower_bound | float | - | The lower bound for the range check. |
| upper_bound | float | - | The upper bound for the range check. |
| name | One of:
| - | The name of the parameter being checked. Used for error messages. |
handle_empty_arrayfunction
Decorator to handle empty array inputs gracefully. This decorator wraps a function to check if the specified array parameter is empty. If the array is empty, it returns the empty array immediately without calling the wrapped function. This prevents errors in functions that cannot handle empty arrays.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| param_name | str | - | Name of the parameter that should be checked for emptiness. This parameter should be an array-like object with a `len()` method. |
Returns
- Callable[[F], F]: A decorator function that can be applied to other functions
Examples
>>> import numpy as np
>>> from albumentations.augmentations.utils import handle_empty_array
>>>
>>> @handle_empty_array("points")
... def process_points(points):
... # This would fail on empty arrays
... return points.mean(axis=0)
>>>
>>> # Empty array is returned immediately
>>> empty = np.array([])
>>> result = process_points(empty)
>>> assert result is empty
>>>
>>> # Non-empty arrays are processed normally
>>> points = np.array([[1, 2], [3, 4]])
>>> result = process_points(points)
>>> assert np.array_equal(result, np.array([2., 3.]))Notes
- The decorator checks for the parameter as both a positional and keyword argument - An empty array is defined as one with `len(array) == 0` - If the array is empty, the original empty array is returned unmodified - This is useful for functions that perform operations on arrays which would fail or be meaningless on empty inputs
non_rgb_errorfunction
Check if the input image is RGB and raise a ValueError if it's not. This function is used to ensure that certain transformations are only applied to RGB images. It provides helpful error messages for grayscale and multi-spectral images.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| image | np.ndarray | - | The input image to check. Expected to be a numpy array representing an image. |
Examples
>>> import numpy as np
>>> rgb_image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> non_rgb_error(rgb_image) # No error raised
>>>
>>> grayscale_image = np.random.randint(0, 256, (100, 100), dtype=np.uint8)
>>> non_rgb_error(grayscale_image) # Raises ValueError with conversion instructions
>>>
>>> multispectral_image = np.random.randint(0, 256, (100, 100, 5), dtype=np.uint8)
>>> non_rgb_error(multispectral_image) # Raises ValueError stating incompatibilityNotes
- RGB images are expected to have exactly 3 channels. - Grayscale images (1 channel) will trigger an error with conversion instructions. - Multi-spectral images (more than 3 channels) will trigger an error stating incompatibility.