albumentations.augmentations.transforms

Apply random noise to image channels using various noise distributions. This transform generates noise using different probability distributions and applies it to image channels. The noise can be generated in three spatial modes and supports multiple noise distributions, each with configurable parameters.

Parameters

Automatically adjust image contrast by stretching the intensity range. This transform provides two methods for contrast enhancement: 1. CDF method (default): Uses cumulative distribution function for more gradual adjustment 2. PIL method: Uses linear scaling like PIL.ImageOps.autocontrast The transform can optionally exclude extreme values from both ends of the intensity range and preserve specific intensity values (e.g., alpha channel).

Parameters

Notes

- The transform processes each color channel independently - For grayscale images, only one channel is processed - The output maintains the same dtype as input - Empty or single-color channels remain unchanged

Parameters

Apply Contrast Limited Adaptive Histogram Equalization (CLAHE) to the input image. CLAHE is an advanced method of improving the contrast in an image. Unlike regular histogram equalization, which operates on the entire image, CLAHE operates on small regions (tiles) in the image. This results in a more balanced equalization, preventing over-amplification of contrast in areas with initially low contrast.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.CLAHE(clip_limit=(1, 4), tile_grid_size=(8, 8), p=1.0)
>>> result = transform(image=image)
>>> clahe_image = result["image"]

Notes

- Supports only RGB or grayscale images. - For color images, CLAHE is applied to the L channel in the LAB color space. - The clip limit determines the maximum slope of the cumulative histogram. A lower clip limit will result in more contrast limiting. - Tile grid size affects the adaptiveness of the method. More tiles increase local adaptiveness but can lead to an unnatural look if set too high.

References

• Tutorial: https://docs.opencv.org/master/d5/daf/tutorial_py_histogram_equalization.html
• "Contrast Limited Adaptive Histogram Equalization.": https://ieeexplore.ieee.org/document/109340

Randomly rearrange channels of the image.

Parameters

Add lateral chromatic aberration by distorting the red and blue channels of the input image. Chromatic aberration is an optical effect that occurs when a lens fails to focus all colors to the same point. This transform simulates this effect by applying different radial distortions to the red and blue channels of the image, while leaving the green channel unchanged.

Parameters

Example

>>> import albumentations as A
>>> import cv2
>>> transform = A.ChromaticAberration(
...     primary_distortion_limit=0.05,
...     secondary_distortion_limit=0.1,
...     mode='green_purple',
...     interpolation=cv2.INTER_LINEAR,
...     p=1.0
... )
>>> transformed = transform(image=image)
>>> aberrated_image = transformed['image']

Notes

- This transform only affects RGB images. Grayscale images will raise an error. - The strength of the effect depends on both primary and secondary distortion limits. - Higher absolute values for distortion limits will result in more pronounced chromatic aberration. - The 'green_purple' mode tends to produce more noticeable effects than 'red_blue'.

References

• Chromatic Aberration: https://en.wikipedia.org/wiki/Chromatic_aberration

Randomly changes the brightness, contrast, saturation, and hue of an image. This transform is similar to torchvision's ColorJitter but with some differences due to the use of OpenCV instead of Pillow. The main differences are: 1. OpenCV and Pillow use different formulas to convert images to HSV format. 2. This implementation uses value saturation instead of uint8 overflow as in Pillow. These differences may result in slightly different output compared to torchvision's ColorJitter.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.ColorJitter(brightness=0.2, contrast=0.2, saturation=0.2, hue=0.1, p=1.0)
>>> result = transform(image=image)
>>> jittered_image = result['image']

Notes

- The order of application for these color transformations is random for each image. - The ranges for brightness, contrast, and saturation are applied as multiplicative factors. - The range for hue is applied as an additive factor.

References

• ColorJitter: https://pytorch.org/vision/stable/generated/torchvision.transforms.ColorJitter.html
• Color Conversions: https://docs.opencv.org/3.4/de/d25/imgproc_color_conversions.html

Decrease image quality by downscaling and upscaling back. This transform simulates the effect of a low-resolution image by first downscaling the image to a lower resolution and then upscaling it back to its original size. This process introduces loss of detail and can be used to simulate low-quality images or to test the robustness of models to different image resolutions.

Parameters

Example

>>> import albumentations as A
>>> import cv2
>>> transform = A.Downscale(
...     scale_range=(0.5, 0.75),
...     interpolation_pair={'downscale': cv2.INTER_NEAREST, 'upscale': cv2.INTER_LINEAR},
...     p=0.5
... )
>>> transformed = transform(image=image)
>>> downscaled_image = transformed['image']

Notes

- The actual downscaling factor is randomly chosen for each image from the range specified in scale_range. - Using different interpolation methods for downscaling and upscaling can produce various effects. For example, using INTER_NEAREST for both can create a pixelated look, while using INTER_LINEAR or INTER_CUBIC can produce smoother results. - This transform can be useful for data augmentation, especially when training models that need to be robust to variations in image quality or resolution.

Apply embossing effect to the input image. This transform creates an emboss effect by highlighting edges and creating a 3D-like texture in the image. It works by applying a specific convolution kernel to the image that emphasizes differences in adjacent pixel values.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.Emboss(alpha=(0.2, 0.5), strength=(0.2, 0.7), p=0.5)
>>> result = transform(image=image)
>>> embossed_image = result['image']

Notes

- The emboss effect is created using a 3x3 convolution kernel. - The 'alpha' parameter controls the blend between the original image and the embossed version. A higher alpha value will result in a more pronounced emboss effect. - The 'strength' parameter affects the intensity of the embossing. Higher strength values will create more contrast in the embossed areas, resulting in a stronger 3D-like effect. - This transform can be useful for creating artistic effects or for data augmentation in tasks where edge information is important.

References

• Image Embossing: https://en.wikipedia.org/wiki/Image_embossing
• Application of Emboss Filtering in Image Processing: https://www.researchgate.net/publication/303412455_Application_of_Emboss_Filtering_in_Image_Processing

Equalize the image histogram. This transform applies histogram equalization to the input image. Histogram equalization is a method in image processing of contrast adjustment using the image's histogram.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>>
>>> # Using a static mask
>>> mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8)
>>> transform = A.Equalize(mask=mask, p=1.0)
>>> result = transform(image=image)
>>>
>>> # Using a dynamic mask function
>>> def mask_func(image, bboxes):
...     mask = np.ones_like(image[:, :, 0], dtype=np.uint8)
...     for bbox in bboxes:
...         x1, y1, x2, y2 = map(int, bbox)
...         mask[y1:y2, x1:x2] = 0  # Exclude areas inside bounding boxes
...     return mask
>>>
>>> transform = A.Equalize(mask=mask_func, mask_params=['bboxes'], p=1.0)
>>> bboxes = [(10, 10, 50, 50), (60, 60, 90, 90)]  # Example bounding boxes
>>> result = transform(image=image, bboxes=bboxes)

Notes

- When mode='cv', OpenCV's equalizeHist() function is used. - When mode='pil', Pillow's equalize() function is used. - The 'by_channels' parameter determines whether equalization is applied to each color channel independently (True) or to the luminance channel only (False). - If a mask is provided as a numpy array, it should have the same height and width as the input image. - If a mask is provided as a function, it allows for dynamic mask generation based on the input image and additional parameters. This is useful for scenarios where the mask depends on the image content or external data (e.g., bounding boxes, segmentation masks).

References

• OpenCV equalizeHist: https://docs.opencv.org/3.4/d6/dc7/group__imgproc__hist.html#ga7e54091f0c937d49bf84152a16f76d6e
• Pillow ImageOps.equalize: https://pillow.readthedocs.io/en/stable/reference/ImageOps.html#PIL.ImageOps.equalize
• Histogram Equalization: https://en.wikipedia.org/wiki/Histogram_equalization

Apply Fancy PCA augmentation to the input image. This augmentation technique applies PCA (Principal Component Analysis) to the image's color channels, then adds multiples of the principal components to the image, with magnitudes proportional to the corresponding eigenvalues times a random variable drawn from a Gaussian with mean 0 and standard deviation 'alpha'.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.FancyPCA(alpha=0.1, p=1.0)
>>> result = transform(image=image)
>>> augmented_image = result["image"]

Notes

- This augmentation is particularly effective for RGB images but can work with any number of channels. - For grayscale images, it applies a simplified version of the augmentation. - The transform preserves the mean of the image while adjusting the color/intensity variation. - This implementation is based on the paper by Krizhevsky et al. and is similar to the one used in the original AlexNet paper.

References

• ImageNet Classification with Deep Convolutional Neural Networks: In Advances in Neural Information

Convert an image from floating point representation to the specified data type. This transform is designed to convert images from a normalized floating-point representation (typically with values in the range [0, 1]) to other data types, scaling the values appropriately.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> transform = A.FromFloat(dtype='uint8', max_value=None, p=1.0)
>>> image = np.random.rand(100, 100, 3).astype(np.float32)  # Float image in [0, 1] range
>>> result = transform(image=image)
>>> uint8_image = result['image']
>>> assert uint8_image.dtype == np.uint8
>>> assert uint8_image.min() >= 0 and uint8_image.max() <= 255

Notes

- This is the inverse transform for ToFloat. - Input images are expected to be in floating point format with values in the range [0, 1]. - For integer output types (uint8, uint16, uint32), the function will scale the values to the appropriate range (e.g., 0-255 for uint8). - For float output types (float32, float64), the values will remain in the [0, 1] range. - The transform uses the `from_float` function internally, which ensures output values are within the valid range for the specified dtype.

Apply Gaussian noise to the input image.

Parameters

Notes

- The noise parameters (std_range and mean_range) are normalized to [0, 1] range: * For uint8 images, they are multiplied by 255 * For float32 images, they are used directly - Setting per_channel=False is faster but applies the same noise to all channels - The noise_scale_factor parameter allows for a trade-off between transform speed and noise granularity

Parameters

Applies H&E (Hematoxylin and Eosin) stain augmentation to histopathology images. This transform simulates different H&E staining conditions using either: 1. Predefined stain matrices (8 standard references) 2. Vahadane method for stain extraction 3. Macenko method for stain extraction 4. Custom stain matrices

Parameters

References

• A. C. Ruifrok and D. A. Johnston, "Quantification of histochemical": Analytical and quantitative cytology and histology, 2001.
• M. Macenko et al., "A method for normalizing histology slides for: 2009 IEEE International Symposium on quantitative analysis," 2009 IEEE International Symposium on Biomedical Imaging, 2009.

Randomly change hue, saturation and value of the input image. This transform adjusts the HSV (Hue, Saturation, Value) channels of an input RGB image. It allows for independent control over each channel, providing a wide range of color and brightness modifications.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.HueSaturationValue(
...     hue_shift_limit=20,
...     sat_shift_limit=30,
...     val_shift_limit=20,
...     p=0.7
... )
>>> result = transform(image=image)
>>> augmented_image = result["image"]

Notes

- The transform first converts the input RGB image to the HSV color space. - Each channel (Hue, Saturation, Value) is adjusted independently. - Hue is circular, so it wraps around at 180 degrees. - For float32 images, the shift values are applied as percentages of the full range. - This transform is particularly useful for color augmentation and simulating different lighting conditions.

References

• HSV color space: https://en.wikipedia.org/wiki/HSL_and_HSV

Applies camera sensor noise to the input image, simulating high ISO settings. This transform adds random noise to an image, mimicking the effect of using high ISO settings in digital photography. It simulates two main components of ISO noise: 1. Color noise: random shifts in color hue 2. Luminance noise: random variations in pixel intensity

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.ISONoise(color_shift=(0.01, 0.05), intensity=(0.1, 0.5), p=0.5)
>>> result = transform(image=image)
>>> noisy_image = result["image"]

Notes

- This transform only works with RGB images. It will raise a TypeError if applied to non-RGB images. - The color shift is applied in the HSV color space, affecting the hue channel. - Luminance noise is added to all channels independently. - This transform can be useful for data augmentation in low-light scenarios or when training models to be robust against noisy inputs.

References

• ISO noise in digital photography: https://en.wikipedia.org/wiki/Image_noise#In_digital_cameras

Apply various illumination effects to the image. This transform simulates different lighting conditions by applying controlled illumination patterns. It can create effects like: - Directional lighting (linear mode) - Corner shadows/highlights (corner mode) - Spotlights or local lighting (gaussian mode) These effects can be used to: - Simulate natural lighting variations - Add dramatic lighting effects - Create synthetic shadows or highlights - Augment training data with different lighting conditions

Parameters

Notes

- The transform preserves image range and dtype - Effects are applied multiplicatively to preserve texture - Can be combined with other transforms for complex lighting scenarios - Useful for training models to be robust to lighting variations

References

• Lighting in Computer Vision: https://en.wikipedia.org/wiki/Lighting_in_computer_vision
• Image-based lighting: https://en.wikipedia.org/wiki/Image-based_lighting
• Similar implementation in Kornia: https://kornia.readthedocs.io/en/latest/augmentation.html#randomlinearillumination
• Research on lighting augmentation: "Learning Deep Representations of Fine-grained Visual Descriptions" https://arxiv.org/abs/1605.05395
• Photography lighting patterns: https://en.wikipedia.org/wiki/Lighting_pattern

Decrease image quality by applying JPEG or WebP compression. This transform simulates the effect of saving an image with lower quality settings, which can introduce compression artifacts. It's useful for data augmentation and for testing model robustness against varying image qualities.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.ImageCompression(quality_range=(50, 90), compression_type=0, p=1.0)
>>> result = transform(image=image)
>>> compressed_image = result["image"]

Notes

- This transform expects images with 1, 3, or 4 channels. - For JPEG compression, alpha channels (4th channel) will be ignored. - WebP compression supports transparency (4 channels). - The actual file is not saved to disk; the compression is simulated in memory. - Lower quality values result in smaller file sizes but may introduce visible artifacts. - This transform can be useful for: * Data augmentation to improve model robustness * Testing how models perform on images of varying quality * Simulating images transmitted over low-bandwidth connections

References

• JPEG compression: https://en.wikipedia.org/wiki/JPEG
• WebP compression: https://developers.google.com/speed/webp

Parameters

Invert the input image by subtracting pixel values from max values of the image types, i.e., 255 for uint8 and 1.0 for float32.

Parameters

A flexible transformation class for using user-defined transformation functions per targets. Function signature must include **kwargs to accept optional arguments like interpolation method, image size, etc:

Parameters

Parameters

Apply a morphological operation (dilation or erosion) to an image, with particular value for enhancing document scans. Morphological operations modify the structure of the image. Dilation expands the white (foreground) regions in a binary or grayscale image, while erosion shrinks them. These operations are beneficial in document processing, for example: - Dilation helps in closing up gaps within text or making thin lines thicker, enhancing legibility for OCR (Optical Character Recognition). - Erosion can remove small white noise and detach connected objects, making the structure of larger objects more pronounced.

Parameters

Example

>>> import albumentations as A
>>> transform = A.Compose([
>>>     A.Morphological(scale=(2, 3), operation='dilation', p=0.5)
>>> ])
>>> image = transform(image=image)["image"]

References

• Nougat: https://github.com/facebookresearch/nougat

Apply multiplicative noise to the input image. This transform multiplies each pixel in the image by a random value or array of values, effectively creating a noise pattern that scales with the image intensity.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.MultiplicativeNoise(multiplier=(0.9, 1.1), per_channel=True, p=1.0)
>>> result = transform(image=image)
>>> noisy_image = result["image"]

Notes

- When elementwise=False and per_channel=False, a single multiplier is applied to the entire image. - When elementwise=False and per_channel=True, each channel gets a different multiplier. - When elementwise=True and per_channel=False, each pixel gets the same multiplier across all channels. - When elementwise=True and per_channel=True, each pixel in each channel gets a unique multiplier. - Setting per_channel=False is slightly faster, especially for larger images. - This transform can be used to simulate various lighting conditions or to create noise that scales with image intensity.

References

• Multiplicative noise: https://en.wikipedia.org/wiki/Multiplicative_noise

Base class for all noise parameter models.

Parameters

Applies various normalization techniques to an image. The specific normalization technique can be selected with the `normalization` parameter. Standard normalization is applied using the formula: `img = (img - mean * max_pixel_value) / (std * max_pixel_value)`. Other normalization techniques adjust the image based on global or per-channel statistics, or scale pixel values to a specified range.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> # Standard ImageNet normalization
>>> transform = A.Normalize(
...     mean=(0.485, 0.456, 0.406),
...     std=(0.229, 0.224, 0.225),
...     max_pixel_value=255.0,
...     p=1.0
... )
>>> normalized_image = transform(image=image)["image"]
>>>
>>> # Min-max normalization
>>> transform_minmax = A.Normalize(normalization="min_max", p=1.0)
>>> normalized_image_minmax = transform_minmax(image=image)["image"]

Notes

- For "standard" normalization, `mean`, `std`, and `max_pixel_value` must be provided. - For other normalization types, these parameters are ignored. - For inception normalization, use mean values of (0.5, 0.5, 0.5). - For YOLO normalization, use mean values of (0, 0, 0) and std values of (1, 1, 1). - This transform is often used as a final step in image preprocessing pipelines to prepare images for neural network input.

References

• ImageNet mean and std: https://pytorch.org/vision/stable/models.html
• Inception preprocessing: https://keras.io/api/applications/inceptionv3/

Applies Planckian Jitter to the input image, simulating color temperature variations in illumination. This transform adjusts the color of an image to mimic the effect of different color temperatures of light sources, based on Planck's law of black body radiation. It can simulate the appearance of an image under various lighting conditions, from warm (reddish) to cool (bluish) color casts. PlanckianJitter vs. ColorJitter: PlanckianJitter is fundamentally different from ColorJitter in its approach and use cases: 1. Physics-based: PlanckianJitter is grounded in the physics of light, simulating real-world color temperature changes. ColorJitter applies arbitrary color adjustments. 2. Natural effects: This transform produces color shifts that correspond to natural lighting variations, making it ideal for outdoor scene simulation or color constancy problems. 3. Single parameter: Color changes are controlled by a single, physically meaningful parameter (color temperature), unlike ColorJitter's multiple abstract parameters. 4. Correlated changes: Color shifts are correlated across channels in a way that mimics natural light, whereas ColorJitter can make independent channel adjustments. When to use PlanckianJitter: - Simulating different times of day or lighting conditions in outdoor scenes - Augmenting data for computer vision tasks that need to be robust to natural lighting changes - Preparing synthetic data to better match real-world lighting variations - Color constancy research or applications - When you need physically plausible color variations rather than arbitrary color changes The logic behind PlanckianJitter: As the color temperature increases: 1. Lower temperatures (around 3000K) produce warm, reddish tones, simulating sunset or incandescent lighting. 2. Mid-range temperatures (around 5500K) correspond to daylight. 3. Higher temperatures (above 7000K) result in cool, bluish tones, similar to overcast sky or shade. This progression mimics the natural variation of sunlight throughout the day and in different weather conditions.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8)
>>> transform = A.PlanckianJitter(mode="blackbody",
...                               temperature_range=(3000, 9000),
...                               sampling_method="uniform",
...                               p=1.0)
>>> result = transform(image=image)
>>> jittered_image = result["image"]

Notes

- The transform preserves the overall brightness of the image while shifting its color. - The "blackbody" mode provides a wider range of color shifts, especially in the lower (warmer) temperatures. - The "cied" mode is based on standard illuminants and may provide more realistic daylight variations. - The Gaussian sampling method tends to produce more subtle variations, as it's centered around daylight. - Unlike ColorJitter, this transform ensures that color changes are physically plausible and correlated across channels, maintaining the natural appearance of the scene under different lighting conditions.

References

• Planck's law: https://en.wikipedia.org/wiki/Planck%27s_law
• CIE Standard Illuminants: https://en.wikipedia.org/wiki/Standard_illuminant
• Color temperature: https://en.wikipedia.org/wiki/Color_temperature
• Implementation inspired by: https://github.com/TheZino/PlanckianJitter

Apply plasma fractal pattern to modify image brightness and contrast. Uses Diamond-Square algorithm to generate organic-looking fractal patterns that create spatially-varying brightness and contrast adjustments.

Parameters

Notes

- Works with any number of channels (grayscale, RGB, multispectral) - The same plasma pattern is applied to all channels - Operations are performed in float32 precision - Final values are clipped to valid range [0, max_value]

References

• Fournier, Fussell, and Carpenter, "Computer rendering of stochastic models,": Communications of the ACM, 1982. Paper introducing the Diamond-Square algorithm.
• Diamond-Square algorithm: https://en.wikipedia.org/wiki/Diamond-square_algorithm

Apply plasma-based shadow effect to the image using Diamond-Square algorithm. Creates organic-looking shadows using plasma fractal noise pattern. The shadow intensity varies smoothly across the image, creating natural-looking darkening effects that can simulate shadows, shading, or lighting variations.

Parameters

Notes

- The transform darkens the image using a plasma pattern - Works with any number of channels (grayscale, RGB, multispectral) - Shadow pattern is generated using Diamond-Square algorithm with specific kernels - The same shadow pattern is applied to all channels - Final values are clipped to valid range [0, max_value]

References

• Fournier, Fussell, and Carpenter, "Computer rendering of stochastic models,": Communications of the ACM, 1982. Paper introducing the Diamond-Square algorithm.
• Diamond-Square algorithm: https://en.wikipedia.org/wiki/Diamond-square_algorithm

Reduces the number of bits for each color channel in the image. This transform applies color posterization, a technique that reduces the number of distinct colors used in an image. It works by lowering the number of bits used to represent each color channel, effectively creating a "poster-like" effect with fewer color gradations.

Parameters

Notes

- The effect becomes more pronounced as the number of bits is reduced. - This transform can create interesting artistic effects or be used for image compression simulation. - Posterization is particularly useful for: * Creating stylized or retro-looking images * Reducing the color palette for specific artistic effects * Simulating the look of older or lower-quality digital images * Data augmentation in scenarios where color depth might vary

References

• Color Quantization: https://en.wikipedia.org/wiki/Color_quantization
• Posterization: https://en.wikipedia.org/wiki/Posterization

Randomly shift values for each channel of the input RGB image. A specialized version of AdditiveNoise that applies constant uniform shifts to RGB channels. Each channel (R,G,B) can have its own shift range specified.

Parameters

Notes

- Values are shifted independently for each channel - For uint8 images: * Input ranges like (-20, 20) represent pixel value shifts * A shift of 20 means adding 20 to that channel * Final values are clipped to [0, 255] - For float32 images: * Input ranges like (-0.1, 0.1) represent relative shifts * A shift of 0.1 means adding 0.1 to that channel * Final values are clipped to [0, 1]

Randomly changes the brightness and contrast of the input image. This transform adjusts the brightness and contrast of an image simultaneously, allowing for a wide range of lighting and contrast variations. It's particularly useful for data augmentation in computer vision tasks, helping models become more robust to different lighting conditions.

Parameters

Notes

- The order of operation is: contrast adjustment, then brightness adjustment. - For uint8 images, the output is clipped to [0, 255] range. - For float32 images, the output is clipped to [0, 1] range. - The `brightness_by_max` parameter affects how brightness is adjusted: * If True, brightness adjustment is more pronounced and can lead to more saturated results. * If False, brightness adjustment is more subtle and preserves the overall lighting better. - This transform is useful for: * Simulating different lighting conditions * Enhancing low-light or overexposed images * Data augmentation to improve model robustness

References

• Brightness: https://en.wikipedia.org/wiki/Brightness
• Contrast: https://en.wikipedia.org/wiki/Contrast_(vision)

Simulates fog for the image by adding random fog-like artifacts. This transform creates a fog effect by generating semi-transparent overlays that mimic the visual characteristics of fog. The fog intensity and distribution can be controlled to create various fog-like conditions.

Parameters

Notes

- The fog effect is created by overlaying semi-transparent circles on the image. - Higher fog coefficient values result in denser fog effects. - The fog is typically denser in the center of the image and gradually decreases towards the edges. - This transform is useful for: * Simulating various weather conditions in outdoor scenes * Data augmentation for improving model robustness to foggy conditions * Creating atmospheric effects in image editing

References

• Fog: https://en.wikipedia.org/wiki/Fog
• Atmospheric perspective: https://en.wikipedia.org/wiki/Aerial_perspective

Applies random gamma correction to the input image. Gamma correction, or simply gamma, is a nonlinear operation used to encode and decode luminance or tristimulus values in imaging systems. This transform can adjust the brightness of an image while preserving the relative differences between darker and lighter areas, making it useful for simulating different lighting conditions or correcting for display characteristics.

Parameters

Notes

- The gamma correction is applied using the formula: output = input^gamma - Gamma values > 1 will make the image darker, while values < 1 will make it brighter - This transform is particularly useful for: * Simulating different lighting conditions * Correcting for non-linear display characteristics * Enhancing contrast in certain regions of the image * Data augmentation in computer vision tasks

References

• Gamma correction: https://en.wikipedia.org/wiki/Gamma_correction
• Power law (Gamma) encoding: https://www.cambridgeincolour.com/tutorials/gamma-correction.htm

Adds gravel-like artifacts to the input image. This transform simulates the appearance of gravel or small stones scattered across specific regions of an image. It's particularly useful for augmenting datasets of road or terrain images, adding realistic texture variations.

Parameters

Notes

- The gravel effect is created by modifying the saturation channel in the HLS color space. - Gravel particles are distributed within randomly generated patches inside the specified ROI. - This transform is particularly useful for: * Augmenting datasets for road condition analysis * Simulating variations in terrain for computer vision tasks * Adding realistic texture to synthetic images of outdoor scenes

References

• Road surface textures: https://en.wikipedia.org/wiki/Road_surface
• HLS color space: https://en.wikipedia.org/wiki/HSL_and_HSV

Adds rain effects to an image. This transform simulates rainfall by overlaying semi-transparent streaks onto the image, creating a realistic rain effect. It can be used to augment datasets for computer vision tasks that need to perform well in rainy conditions.

Parameters

Notes

- The rain effect is created by drawing semi-transparent lines on the image. - The slant of the rain can be controlled to simulate wind effects. - Different rain types (drizzle, heavy, torrential) adjust the density and appearance of the rain. - The transform also adjusts image brightness and applies a blur to simulate the visual effects of rain. - This transform is particularly useful for: * Augmenting datasets for autonomous driving in rainy conditions * Testing the robustness of computer vision models to weather effects * Creating realistic rainy scenes for image editing or film production

References

• Rain visualization techniques: https://developer.nvidia.com/gpugems/gpugems3/part-iv-image-effects/chapter-27-real-time-rain-rendering
• Weather effects in computer vision: https://www.sciencedirect.com/science/article/pii/S1077314220300692

Simulates shadows for the image by reducing the brightness of the image in shadow regions. This transform adds realistic shadow effects to images, which can be useful for augmenting datasets for outdoor scene analysis, autonomous driving, or any computer vision task where shadows may be present.

Parameters

Notes

- Shadows are created by generating random polygons within the specified ROI and reducing the brightness of the image in these areas. - The number of shadows, their shapes, and intensities can be randomized for variety. - This transform is particularly useful for: * Augmenting datasets for outdoor scene understanding * Improving robustness of object detection models to shadowed conditions * Simulating different lighting conditions in synthetic datasets

References

• Shadow detection and removal: https://www.sciencedirect.com/science/article/pii/S1047320315002035
• Shadows in computer vision: https://en.wikipedia.org/wiki/Shadow_detection

Applies a random snow effect to the input image. This transform simulates snowfall by either bleaching out some pixel values or adding a snow texture to the image, depending on the chosen method.

Parameters

Notes

- The "bleach" method increases the brightness of pixels above a certain threshold, creating a simple snow effect. This method is faster but may look less realistic. - The "texture" method creates a more realistic snow effect through the following steps: 1. Converts the image to HSV color space for better control over brightness. 2. Increases overall image brightness to simulate the reflective nature of snow. 3. Generates a snow texture using Gaussian noise, which is then smoothed with a Gaussian filter. 4. Applies a depth effect to the snow texture, making it more prominent at the top of the image. 5. Blends the snow texture with the original image using alpha compositing. 6. Adds a slight blue tint to simulate the cool color of snow. 7. Adds random sparkle effects to simulate light reflecting off snow crystals. This method produces a more realistic result but is computationally more expensive.

References

• Bleach method: https://github.com/UjjwalSaxena/Automold--Road-Augmentation-Library
• Texture method: Inspired by computer graphics techniques for snow rendering and atmospheric scattering simulations.

Simulates a sun flare effect on the image by adding circles of light. This transform creates a sun flare effect by overlaying multiple semi-transparent circles of varying sizes and intensities along a line originating from a "sun" point. It offers two methods: a simple overlay technique and a more complex physics-based approach.

Parameters

References

• Lens flare: https://en.wikipedia.org/wiki/Lens_flare
• Alpha compositing: https://en.wikipedia.org/wiki/Alpha_compositing
• Diffraction: https://en.wikipedia.org/wiki/Diffraction
• Chromatic aberration: https://en.wikipedia.org/wiki/Chromatic_aberration
• Screen blending: https://en.wikipedia.org/wiki/Blend_modes#Screen

Randomly change the relationship between bright and dark areas of the image by manipulating its tone curve. This transform applies a random S-curve to the image's tone curve, adjusting the brightness and contrast in a non-linear manner. It can be applied to the entire image or to each channel separately.

Parameters

Notes

- This transform modifies the image's histogram by applying a smooth, S-shaped curve to it. - The S-curve is defined by moving two control points of a quadratic Bézier curve. - When per_channel is False, the same curve is applied to all channels, maintaining color balance. - When per_channel is True, different curves are applied to each channel, which can create color shifts. - This transform can be used to adjust image contrast and brightness in a more natural way than linear transforms. - The effect can range from subtle contrast adjustments to more dramatic "vintage" or "faded" looks.

References

• "What Else Can Fool Deep Learning? Addressing Color Constancy Errors on Deep Neural Network Performance": https://arxiv.org/abs/1912.06960
• Bézier curve: https://en.wikipedia.org/wiki/B%C3%A9zier_curve#Quadratic_B%C3%A9zier_curves
• Tone mapping: https://en.wikipedia.org/wiki/Tone_mapping

Create ringing or overshoot artifacts by convolving the image with a 2D sinc filter. This transform simulates the ringing artifacts that can occur in digital image processing, particularly after sharpening or edge enhancement operations. It creates oscillations or overshoots near sharp transitions in the image.

Parameters

Notes

- Ringing artifacts are oscillations of the image intensity function in the neighborhood of sharp transitions, such as edges or object boundaries. - This transform uses a 2D sinc filter (also known as a 2D cardinal sine function) to introduce these artifacts. - The severity of the ringing effect is controlled by both the kernel size (blur_limit) and the cutoff frequency. - Larger kernel sizes and lower cutoff frequencies will generally produce more noticeable ringing effects. - This transform can be useful for: * Simulating imperfections in image processing or transmission systems * Testing the robustness of computer vision models to ringing artifacts * Creating artistic effects that emphasize edges and transitions in images

References

• Ringing artifacts: https://en.wikipedia.org/wiki/Ringing_artifacts
• Sinc filter: https://en.wikipedia.org/wiki/Sinc_filter
• Digital Image Processing: Rafael C. Gonzalez and Richard E. Woods, 4th Edition

Apply salt and pepper noise to the input image. Salt and pepper noise is a form of impulse noise that randomly sets pixels to either maximum value (salt) or minimum value (pepper). The amount and proportion of salt vs pepper noise can be controlled. The same noise mask is applied to all channels of the image to preserve color consistency.

Parameters

Notes

- Salt noise sets pixels to maximum value (255 for uint8, 1.0 for float32) - Pepper noise sets pixels to 0 - The noise mask is generated once and applied to all channels to maintain color consistency (i.e., if a pixel is set to salt, all its color channels will be set to maximum value) - The exact number of affected pixels matches the specified amount as masks are generated without overlap

References

• Digital Image Processing: Rafael C. Gonzalez and Richard E. Woods, 4th Edition, Chapter 5: Image Restoration and Reconstruction.
• Fundamentals of Digital Image Processing: A. K. Jain, Chapter 7: Image Degradation and Restoration.
• Salt and pepper noise: https://en.wikipedia.org/wiki/Salt-and-pepper_noise

Sharpen the input image using either kernel-based or Gaussian interpolation method. Implements two different approaches to image sharpening: 1. Traditional kernel-based method using Laplacian operator 2. Gaussian interpolation method (similar to Kornia's approach)

Parameters

Notes

- Kernel sizes must be odd to maintain spatial alignment - Methods produce different visual results: * Kernel method: More pronounced edges, possible artifacts * Gaussian method: More natural look, limited to original sharpness

References

• R. C. Gonzalez and R. E. Woods, "Digital Image Processing (4th Edition),": Chapter 3: Intensity Transformations and Spatial Filtering.
• J. C. Russ, "The Image Processing Handbook (7th Edition),": Chapter 4: Image Enhancement.
• T. Acharya and A. K. Ray, "Image Processing: Principles and Applications,": Chapter 5: Image Enhancement.
• Unsharp masking: https://en.wikipedia.org/wiki/Unsharp_masking
• Laplacian operator: https://en.wikipedia.org/wiki/Laplace_operator
• Gaussian blur: https://en.wikipedia.org/wiki/Gaussian_blur

Apply shot noise to the image by modeling photon counting as a Poisson process. Shot noise (also known as Poisson noise) occurs in imaging due to the quantum nature of light. When photons hit an imaging sensor, they arrive at random times following Poisson statistics. This transform simulates this physical process in linear light space by: 1. Converting to linear space (removing gamma) 2. Treating each pixel value as an expected photon count 3. Sampling actual photon counts from a Poisson distribution 4. Converting back to display space (reapplying gamma) The noise characteristics follow real camera behavior: - Noise variance equals signal mean in linear space (Poisson statistics) - Brighter regions have more absolute noise but less relative noise - Darker regions have less absolute noise but more relative noise - Noise is generated independently for each pixel and color channel

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> # Generate synthetic image
>>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8)
>>> # Apply moderate shot noise
>>> transform = A.ShotNoise(scale_range=(0.1, 1.0), p=1.0)
>>> noisy_image = transform(image=image)["image"]

Notes

- Performs calculations in linear light space (gamma = 2.2) - Preserves the image's mean intensity - Memory efficient with in-place operations - Thread-safe with independent random seeds

References

• Shot noise: https://en.wikipedia.org/wiki/Shot_noise
• Original paper: https://doi.org/10.1002/andp.19183622304 (Schottky, 1918)
• Poisson process: https://en.wikipedia.org/wiki/Poisson_point_process
• Gamma correction: https://en.wikipedia.org/wiki/Gamma_correction

Invert all pixel values above a threshold. This transform applies a solarization effect to the input image. Solarization is a phenomenon in photography in which the image recorded on a negative or on a photographic print is wholly or partially reversed in tone. Dark areas appear light or light areas appear dark. In this implementation, all pixel values above a threshold are inverted.

Parameters

Notes

- For uint8 images, pixel values above the threshold are inverted as: 255 - pixel_value - For float32 images, pixel values above the threshold are inverted as: 1.0 - pixel_value - The threshold is applied to each channel independently - The threshold is calculated in two steps: 1. Sample a value from threshold_range 2. Multiply by the image's maximum value: * For uint8: threshold = sampled_value * 255 * For float32: threshold = sampled_value * 1.0 - This transform can create interesting artistic effects or be used for data augmentation

Apply spatter transform. It simulates corruption which can occlude a lens in the form of rain or mud.

Parameters

References

• Benchmarking Neural Network Robustness to Common Corruptions and Perturbations: https://arxiv.org/abs/1903.12261

Transform images partially/completely to their superpixel representation.

Parameters

Notes

- This transform can significantly change the visual appearance of the image. - The transform makes use of a superpixel algorithm, which tends to be slow. If performance is a concern, consider using `max_size` to limit the image size. - The effect of this transform can vary greatly depending on the `p_replace` and `n_segments` parameters. - When `p_replace` is high, the image can become highly abstracted, resembling a voronoi diagram. - The transform preserves the original image type (uint8 or float32).

Convert the input image to a floating-point representation. This transform divides pixel values by `max_value` to get a float32 output array where all values lie in the range [0, 1.0]. It's useful for normalizing image data before feeding it into neural networks or other algorithms that expect float input.

Parameters

Returns

• np.ndarray: Image in floating point representation, with values in range [0, 1.0].

Notes

- If the input image is already float32 with values in [0, 1], it will be returned unchanged. - For integer types (uint8, uint16, uint32), the function will scale the values to [0, 1] range. - The output will always be float32, regardless of the input type. - This transform is often used as a preprocessing step before applying other transformations or feeding the image into a neural network.

Convert an image to grayscale and optionally replicate the grayscale channel. This transform first converts a color image to a single-channel grayscale image using various methods, then replicates the grayscale channel if num_output_channels is greater than 1.

Parameters

Returns

• np.ndarray: Grayscale image with the specified number of channels.

Notes

- The transform first converts the input image to single-channel grayscale, then replicates this channel if num_output_channels > 1. - "weighted_average" and "from_lab" are typically used in image processing and computer vision applications where accurate representation of human perception is important. - "desaturation" and "average" are often used in simple image manipulation tools or when computational speed is a priority. - "max" method can be useful in scenarios where preserving bright features is important, such as in some medical imaging applications. - "pca" might be used in advanced image analysis tasks or when dealing with hyperspectral images.

Convert an input image from grayscale to RGB format.

Parameters

Notes

- For single-channel (grayscale) images, the channel is replicated to create an RGB image. - If the input is already a 3-channel RGB image, it is returned unchanged. - This transform does not change the data type of the image (e.g., uint8 remains uint8).

Apply a sepia filter to the input image. This transform converts a color image to a sepia tone, giving it a warm, brownish tint that is reminiscent of old photographs. The sepia effect is achieved by applying a specific color transformation matrix to the RGB channels of the input image. For grayscale images, the transform is a no-op and returns the original image.

Parameters

Notes

- The sepia effect only works with RGB images (3 channels). For grayscale images, the original image is returned unchanged since the sepia transformation would have no visible effect when R=G=B. - The sepia effect is created using a fixed color transformation matrix: [[0.393, 0.769, 0.189], [0.349, 0.686, 0.168], [0.272, 0.534, 0.131]] - The output image will have the same data type as the input image. - For float32 images, ensure the input values are in the range [0, 1].

Parameters

Sharpen the input image using Unsharp Masking processing and overlays the result with the original image. Unsharp masking is a technique that enhances edge contrast in an image, creating the illusion of increased sharpness. This transform applies Gaussian blur to create a blurred version of the image, then uses this to create a mask which is combined with the original image to enhance edges and fine details.

Parameters

Notes

- The algorithm creates a mask M = (I - G) * alpha, where I is the original image and G is the Gaussian blurred version. - The final image is computed as: output = I + M if |I - G| > threshold, else I. - Higher alpha values increase the strength of the sharpening effect. - Higher threshold values limit the sharpening effect to areas with more significant edges or details. - The blur_limit and sigma_limit parameters control the Gaussian blur used to create the mask.

References

• Unsharp Masking: https://en.wikipedia.org/wiki/Unsharp_masking