albumentations.augmentations.pixel.transforms

Random noise to channels: uniform, gaussian, laplace, or beta. spatial_mode: constant, per_pixel, or shared. Params depend on noise_type. 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

Examples

>>> # Constant RGB shift with different ranges per channel:
>>> transform = AdditiveNoise(
...     noise_type="uniform",
...     spatial_mode="constant",
...     noise_params={"ranges": [(-0.2, 0.2), (-0.1, 0.1), (-0.1, 0.1)]}
... )

Add depth-dependent fog via the atmospheric scattering equation and a synthetic depth map. Use for outdoor and driving robustness to haze. Unlike RandomFog (which overlays circular fog patches), this transform uses a physically-based scattering model: farther pixels (by synthetic depth) get more fog, producing realistic distance-dependent haze. Depth is derived from image position (linear, diagonal, or radial), not from a real depth map. Formula: `result = image * exp(-density * depth) + fog_color * (1 - exp(-density * depth))`

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.AtmosphericFog(density_range=(1.0, 2.5), depth_mode="linear", p=1.0)
>>> result = transform(image=image)["image"]
>>> # Radial fog (center clear, edges foggy)
>>> transform_radial = A.AtmosphericFog(density_range=(1.5, 3.0), depth_mode="radial", p=1.0)
>>> result_radial = transform_radial(image=image)["image"]

Notes

- Depth is synthetic (from pixel position), not from scene geometry. - For typical outdoor frames, "linear" matches sky far / ground near.

Stretch intensity to full range (autocontrast). method: CDF or PIL-style. cutoff, ignore trim extremes. Use for normalizing brightness/contrast across images. 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

Examples

>>> import albumentations as A
>>> # Basic usage
>>> transform = A.AutoContrast(p=1.0)
>>>
>>> # Exclude extreme values
>>> transform = A.AutoContrast(cutoff=20, p=1.0)
>>>
>>> # Preserve alpha channel
>>> transform = A.AutoContrast(ignore=255, p=1.0)
>>>
>>> # Use PIL-like contrast enhancement
>>> transform = A.AutoContrast(method="pil", p=1.0)

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

Contrast Limited Adaptive Histogram Equalization: local contrast with clip_limit and tile_grid_size. Good for non-uniform lighting; preserves detail. 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

Examples

>>> 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

• [{'description': 'Tutorial', 'source': 'https://docs.opencv.org/master/d5/daf/tutorial_py_histogram_equalization.html'}, {'description': '"Contrast Limited Adaptive Histogram Equalization."', 'source': 'https://ieeexplore.ieee.org/document/109340'}]

Randomly permute channel order (e.g. RGB→BGR) each call. Makes model invariant to channel order; useful for multi-channel or color-agnostic training. Unlike ChannelSwap, the permutation is random every time (uniform over all orders). All pixel data is preserved; only channel indices change.

Parameters

Examples

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

Notes

- Permutation is chosen uniformly over all channel orderings. - Same image can get different orderings on different calls.

Fixed channel reordering (e.g. RGB→BGR). Deterministic permutation; unlike ChannelShuffle. Use for color-space conversion or fixed channel layouts. Applies a user-specified channel order every time (no randomness). Useful for BGR↔RGB conversion or training models invariant to a specific channel ordering.

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>>
>>> # Swap R and B (RGB → BGR)
>>> transform = A.ChannelSwap(channel_order=(2, 1, 0), p=1.0)
>>> result = transform(image=image)["image"]
>>> np.testing.assert_array_equal(result[:, :, 0], image[:, :, 2])

Notes

- channel_order must be a permutation of 0..C-1 for C channels. - (2, 1, 0) gives RGB→BGR; (0, 2, 1) swaps G and B.

Add lateral chromatic aberration: shift red and blue relative to green. distortion_limit and shift_limit control strength. Simulates lens color fringing. 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

Examples

>>> 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

• [{'description': 'Chromatic Aberration', 'source': 'https://en.wikipedia.org/wiki/Chromatic_aberration'}]

Randomly apply brightness, contrast, saturation, hue in random order. Separate ranges per effect. Strong color augmentation for classification and detection. 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

Examples

>>> 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

• [{'description': 'ColorJitter', 'source': 'https://pytorch.org/vision/stable/generated/torchvision.transforms.ColorJitter.html'}, {'description': 'Color Conversions', 'source': 'https://docs.opencv.org/3.4/de/d25/imgproc_color_conversions.html'}]

Reduce colors via dithering: ordered Bayer, error diffusion, or random. num_levels, method. Good for retro look or limited-color output. Dithering is like creating a newspaper photo - it uses patterns of dots to create the illusion of more colors than are actually present. When you have a limited color palette (like only black and white), dithering arranges these limited colors in patterns that trick your eye into seeing intermediate shades. Think of it like pointillist paintings - up close you see individual dots, but from a distance they blend together to create smooth gradients and subtle color variations. This transform works with ANY number of channels - it processes each channel independently, whether you have a standard RGB image (3 channels), RGBA with transparency (4 channels), multispectral satellite imagery (dozens of channels), or even single-channel grayscale images.

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>> # Prepare sample data
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>>
>>> # Black and white dithering with Floyd-Steinberg
>>> transform = A.Compose([
...     A.Dithering(
...         method="error_diffusion",
...         n_colors=2,
...         error_diffusion_algorithm="floyd_steinberg",
...         color_mode="grayscale",
...         p=1.0
...     )
... ])
>>> transformed = transform(image=image)
>>> dithered_image = transformed['image']  # Black and white dithered image
>>>
>>> # Ordered dithering with 16 colors per channel
>>> transform = A.Compose([
...     A.Dithering(
...         method="ordered",
...         n_colors=16,
...         bayer_matrix_size=8,
...         color_mode="per_channel",
...         p=1.0
...     )
... ])
>>> transformed = transform(image=image)
>>> dithered_image = transformed['image']  # Reduced color depth with Bayer pattern
>>>
>>> # Random dithering
>>> transform = A.Compose([
...     A.Dithering(
...         method="random",
...         n_colors=4,
...         noise_range=(-0.3, 0.3),
...         p=1.0
...     )
... ])
>>> transformed = transform(image=image)
>>> dithered_image = transformed['image']  # Noisy dithered appearance

References

• [{'description': 'Wikipedia', 'source': 'https://en.wikipedia.org/wiki/Dither'}, {'description': 'Floyd-Steinberg dithering', 'source': 'https://en.wikipedia.org/wiki/Floyd%E2%80%93Steinberg_dithering'}, {'description': 'Ordered dithering', 'source': 'https://en.wikipedia.org/wiki/Ordered_dithering'}, {'description': 'Error diffusion dithering', 'source': 'https://en.wikipedia.org/wiki/Error_diffusion'}]

Reduce quality by downscale then upscale. scale_min and scale_max control factor. Simulates resolution or compression loss. 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

Examples

>>> 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 emboss effect (directional highlight and shadow). strength_range controls intensity. Pseudo-3D look; for texture or style augmentation. 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

Examples

>>> 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

• [{'description': 'Image Embossing', 'source': 'https://en.wikipedia.org/wiki/Image_embossing'}, {'description': 'Application of Emboss Filtering in Image Processing', 'source': 'https://www.researchgate.net/publication/303412455_Application_of_Emboss_Filtering_in_Image_Processing'}]

Equalize histogram to spread intensities. mode: global or adaptive; mask optional. Improves contrast normalization across datasets. 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

Examples

>>> 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

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

Add color variation via PCA on RGB: perturb components by alpha_std. Simulates natural lighting variation (ImageNet-style). Good for object recognition. 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

Examples

>>> 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

• [{'description': 'ImageNet Classification with Deep Convolutional Neural Networks', 'source': 'In Advances in Neural Information'}]

Analog film grain: luminance-dependent, spatially correlated noise. Distinct from i.i.d. GaussNoise or ShotNoise. Use for vintage or film-like augmentation. Unlike GaussNoise or ShotNoise, film grain is: - Luminance-dependent: darker areas show more visible grain - Spatially correlated: grain is clumped, not i.i.d. per-pixel - Optionally chromatic: separate grain patterns per channel

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>>
>>> transform = A.FilmGrain(intensity_range=(0.1, 0.3), grain_size_range=(1, 3), p=1.0)
>>> result = transform(image=image)["image"]

Notes

- Grain is generated at lower resolution and upscaled → spatial correlation (clumping) like real film. - Visibility modulated by inverse luminance; darker regions show more grain (silver halide-like behavior).

Add Gaussian (normal) noise to the image. i.i.d. per pixel (or per block if scaled). Use for robustness to sensor or transmission noise. Noise standard deviation and mean are sampled from configurable ranges and scaled to image dtype (255 for uint8, 1.0 for float32). Optional per-channel sampling and lower-resolution noise for speed.

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>>
>>> transform = A.GaussNoise(std_range=(0.1, 0.2), p=1.0)
>>> noisy_image = transform(image=image)["image"]

Notes

- std_range and mean_range are in [0, 1] / [-1, 1]; scaled by 255 (uint8) or used directly (float32). - per_channel=False: faster, same noise on all channels (grayscale-like on RGB). - per_channel=True: different noise per channel (colored noise). - noise_scale_factor < 1 trades speed for noise granularity.

H&E stain augmentation for histopathology. method: preset, random_preset, vahadane, macenko. Simulates staining variation for robust pathology models. 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

Examples

>>> import numpy as np
>>> import albumentations as A
>>> import cv2
>>>
>>> # Create a sample H&E stained histopathology image
>>> # For real use cases, load an actual H&E stained image
>>> image = np.zeros((300, 300, 3), dtype=np.uint8)
>>> # Simulate tissue regions with different staining patterns
>>> image[50:150, 50:150] = np.array([120, 140, 180], dtype=np.uint8)  # Hematoxylin-rich region
>>> image[150:250, 150:250] = np.array([140, 160, 120], dtype=np.uint8)  # Eosin-rich region
>>>
>>> # Example 1: Using a specific preset stain matrix
>>> transform = A.HEStain(
...     method="preset",
...     preset="standard",
...     intensity_scale_range=(0.8, 1.2),
...     intensity_shift_range=(-0.1, 0.1),
...     augment_background=False,
...     p=1.0
... )
>>> result = transform(image=image)
>>> transformed_image = result['image']
>>>
>>> # Example 2: Using random preset selection
>>> transform = A.HEStain(
...     method="random_preset",
...     intensity_scale_range=(0.7, 1.3),
...     intensity_shift_range=(-0.15, 0.15),
...     p=1.0
... )
>>> result = transform(image=image)
>>> transformed_image = result['image']
>>>
>>> # Example 3: Using Vahadane method (requires H&E stained input)
>>> transform = A.HEStain(
...     method="vahadane",
...     intensity_scale_range=(0.7, 1.3),
...     p=1.0
... )
>>> result = transform(image=image)
>>> transformed_image = result['image']
>>>
>>> # Example 4: Using Macenko method (requires H&E stained input)
>>> transform = A.HEStain(
...     method="macenko",
...     intensity_scale_range=(0.7, 1.3),
...     intensity_shift_range=(-0.2, 0.2),
...     p=1.0
... )
>>> result = transform(image=image)
>>> transformed_image = result['image']
>>>
>>> # Example 5: Combining with other transforms in a pipeline
>>> transform = A.Compose([
...     A.HEStain(method="preset", preset="high_contrast", p=1.0),
...     A.RandomBrightnessContrast(p=0.5),
... ])
>>> result = transform(image=image)
>>> transformed_image = result['image']

References

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

Halftone dot pattern (printing-style). Continuous tones become dots of varying size. Use for vintage or print-aesthetic augmentation. Simulates halftone printing: a grid of cells, each drawn as a filled circle whose size is proportional to mean luminance in that cell. Larger dots = brighter, smaller = darker. Optional blend with the original image controls strength.

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>>
>>> transform = A.Halftone(dot_size_range=(4, 8), blend_range=(0.0, 0.3), p=1.0)
>>> result = transform(image=image)["image"]

Notes

- Mean luminance per grid cell drives dot radius; cell color from original image. - Dot size is proportional to luminance (bright → large dot, dark → small dot).

Randomly shift hue, saturation, and value (HSV). Separate ranges per channel. Common for color augmentation in classification. 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

Examples

>>> 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

• [{'description': 'HSV color space', 'source': 'https://en.wikipedia.org/wiki/HSL_and_HSV'}]

Add camera-sensor-like noise scaling with intensity (high ISO). color_shift and intensity range control strength. Good for low-light or camera noise simulation. 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

Examples

>>> 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

• [{'description': 'ISO noise in digital photography', 'source': 'https://en.wikipedia.org/wiki/Image_noise#In_digital_cameras'}]

Illumination patterns: directional (linear), corner shadows/highlights, or gaussian. mode and params control shape and strength. Simulates lighting variation. 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

Examples

>>> import albumentations as A
>>> # Simulate sunlight through window
>>> transform = A.Illumination(
...     mode='linear',
...     intensity_range=(0.05, 0.1),
...     effect_type='brighten',
...     angle_range=(30, 60)
... )
>>>
>>> # Create dramatic corner shadow
>>> transform = A.Illumination(
...     mode='corner',
...     intensity_range=(0.1, 0.2),
...     effect_type='darken'
... )
>>>
>>> # Add multiple spotlights
>>> transform1 = A.Illumination(
...     mode='gaussian',
...     intensity_range=(0.05, 0.15),
...     effect_type='brighten',
...     center_range=(0.2, 0.4),
...     sigma_range=(0.2, 0.3)
... )
>>> transform2 = A.Illumination(
...     mode='gaussian',
...     intensity_range=(0.05, 0.15),
...     effect_type='darken',
...     center_range=(0.6, 0.8),
...     sigma_range=(0.3, 0.5)
... )
>>> transforms = A.Compose([transform1, transform2])

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

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

Reduce image quality via JPEG or WebP compression. quality_range and compression_type control strength and format. Simulates real-world compression artifacts. 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

Examples

>>> 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

• [{'description': 'JPEG compression', 'source': 'https://en.wikipedia.org/wiki/JPEG'}, {'description': 'WebP compression', 'source': 'https://developers.google.com/speed/webp'}]

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

Examples

>>> import numpy as np
>>> import albumentations as A
>>> import cv2
>>>
>>> # Create a sample image with different elements
>>> image = np.zeros((100, 100, 3), dtype=np.uint8)
>>> cv2.circle(image, (30, 30), 20, (255, 255, 255), -1)  # White circle
>>> cv2.rectangle(image, (60, 60), (90, 90), (128, 128, 128), -1)  # Gray rectangle
>>>
>>> # Apply InvertImg transform
>>> transform = A.InvertImg(p=1.0)
>>> result = transform(image=image)
>>> inverted_image = result['image']
>>>
>>> # Result:
>>> # - Black background becomes white (0 → 255)
>>> # - White circle becomes black (255 → 0)
>>> # - Gray rectangle is inverted (128 → 127)
>>> # The same approach works for float32 images (0-1 range) and grayscale images

Add lens flare: starburst rays and ghost reflections from a bright source. Use for outdoor or backlit robustness and optical-artifact simulation. A flare center is chosen in a configurable region; starburst rays and mirrored ghost circles are drawn toward the image center. Strength and blur are configurable.

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.LensFlare(intensity_range=(0.3, 0.6), p=1.0)
>>> result = transform(image=image)["image"]

Notes

- Ghost reflections lie along the line from flare source to image center. - Size decreases and color shifts with distance from the source.

Multiply image by random per-pixel or per-channel factor. multiplier_range controls strength. Simulates illumination or gain variation; preserves zeros. 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

Examples

>>> 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

• [{'description': 'Multiplicative noise', 'source': 'https://en.wikipedia.org/wiki/Multiplicative_noise'}]

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

Examples

>>> 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

• [{'description': 'ImageNet mean and std', 'source': 'https://pytorch.org/vision/stable/models.html'}, {'description': 'Inception preprocessing', 'source': 'https://keras.io/api/applications/inceptionv3/'}]

SSD-style photometric distortion: brightness, contrast, saturation, hue, channel shuffle; each with probability distort_p. For detection training. Applies brightness, contrast, saturation, and hue adjustments independently with probability `distort_p` each. Contrast is applied either before or after the HSV-space adjustments (randomly chosen). Optionally permutes channels with probability `distort_p`. This mirrors the `RandomPhotometricDistort` transform from torchvision but uses our existing `adjust_*_torchvision` functional primitives.

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>> 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]], dtype=np.float32)
>>> bbox_labels = [1]
>>> keypoints = np.array([[20, 30]], dtype=np.float32)
>>> keypoint_labels = [0]
>>>
>>> transform = A.Compose([
...     A.PhotoMetricDistort(
...         brightness_range=(0.875, 1.125),
...         contrast_range=(0.5, 1.5),
...         saturation_range=(0.5, 1.5),
...         hue_range=(-0.05, 0.05),
...         distort_p=0.5,
...         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 = transform(
...     image=image,
...     mask=mask,
...     bboxes=bboxes,
...     bbox_labels=bbox_labels,
...     keypoints=keypoints,
...     keypoint_labels=keypoint_labels,
... )
>>> transformed_image = result['image']

Notes

- Each of the five distortions (brightness, contrast, saturation, hue, channel shuffle) is applied independently with probability `distort_p`. - Contrast is randomly applied either before or after saturation/hue adjustment. - For single-channel images, saturation and hue adjustments have no effect.

References

• [{'description': 'SSD', 'source': 'https://arxiv.org/abs/1512.02325'}, {'description': 'torchvision RandomPhotometricDistort', 'source': 'https://pytorch.org/vision/stable/generated/torchvision.transforms.v2.RandomPhotometricDistort.html'}]

Simulate color temperature variation via Planckian locus jitter. mode and magnitude control the shift. Good for robustness to different light sources. 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

Examples

>>> 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

• [{'description': "Planck's law", 'source': 'https://en.wikipedia.org/wiki/Planck%27s_law'}, {'description': 'CIE Standard Illuminants', 'source': 'https://en.wikipedia.org/wiki/Standard_illuminant'}, {'description': 'Color temperature', 'source': 'https://en.wikipedia.org/wiki/Color_temperature'}, {'description': 'Implementation inspired by', 'source': 'https://github.com/TheZino/PlanckianJitter'}]

Plasma fractal (Diamond-Square) pattern varies brightness and contrast spatially. brightness_range, contrast_range. Organic, non-uniform look. Uses Diamond-Square algorithm to generate organic-looking fractal patterns that create spatially-varying brightness and contrast adjustments.

Parameters

Examples

>>> import albumentations as A
>>> import numpy as np

# Default parameters
>>> transform = A.PlasmaBrightnessContrast(p=1.0)

# Custom adjustments
>>> transform = A.PlasmaBrightnessContrast(
...     brightness_range=(-0.5, 0.5),
...     contrast_range=(-0.3, 0.3),
...     plasma_size=512,    # More detailed pattern
...     roughness=0.7,      # Smoother transitions
...     p=1.0
... )

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

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

Plasma fractal (Diamond-Square) shadow: organic darkening. shadow_intensity_range, roughness. Good for natural shading and lighting variation. 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

Examples

>>> import albumentations as A
>>> import numpy as np

# Default parameters for natural shadows
>>> transform = A.PlasmaShadow(p=1.0)

# Subtle, smooth shadows
>>> transform = A.PlasmaShadow(
...     shadow_intensity_range=(0.1, 0.3),
...     roughness=0.7,
...     p=1.0
... )

# Dramatic, detailed shadows
>>> transform = A.PlasmaShadow(
...     shadow_intensity_range=(0.5, 0.9),
...     roughness=0.3,
...     p=1.0
... )

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

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

Reduce bits per color channel (e.g. 8→4). num_bits_range controls strength; lower gives stronger posterization. Simulates low-bit-depth or compression. 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

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8)

# Posterize all channels to 3 bits
>>> transform = A.Posterize(num_bits=3, p=1.0)
>>> posterized_image = transform(image=image)["image"]

# Randomly posterize between 2 and 5 bits
>>> transform = A.Posterize(num_bits=(2, 5), p=1.0)
>>> posterized_image = transform(image=image)["image"]

# Different bits for each channel
>>> transform = A.Posterize(num_bits=[3, 5, 2], p=1.0)
>>> posterized_image = transform(image=image)["image"]

# Range of bits for each channel
>>> transform = A.Posterize(num_bits=[(1, 3), (3, 5), (2, 4)], p=1.0)
>>> posterized_image = transform(image=image)["image"]

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

• [{'description': 'Color Quantization', 'source': 'https://en.wikipedia.org/wiki/Color_quantization'}, {'description': 'Posterization', 'source': 'https://en.wikipedia.org/wiki/Posterization'}]

Shift R, G, B with separate ranges. Specialized AdditiveNoise with constant uniform shifts. Params: r_shift_limit, g_shift_limit, b_shift_limit. 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

Examples

>>> import numpy as np
>>> import albumentations as A

# Shift RGB channels of uint8 image
>>> transform = A.RGBShift(
...     r_shift_limit=30,  # Will sample red shift from [-30, 30]
...     g_shift_limit=(-20, 20),  # Will sample green shift from [-20, 20]
...     b_shift_limit=(-10, 10),  # Will sample blue shift from [-10, 10]
...     p=1.0
... )
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> shifted = transform(image=image)["image"]

# Same effect using AdditiveNoise
>>> transform = A.AdditiveNoise(
...     noise_type="uniform",
...     spatial_mode="constant",  # One value per channel
...     noise_params={
...         "ranges": [(-30/255, 30/255), (-20/255, 20/255), (-10/255, 10/255)]
...     },
...     p=1.0
... )

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 adjust brightness and contrast with separate ranges. Simple and fast; good baseline color augmentation for classification and detection. 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

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8)

# Default usage
>>> transform = A.RandomBrightnessContrast(p=1.0)
>>> augmented_image = transform(image=image)["image"]

# Custom brightness and contrast limits
>>> transform = A.RandomBrightnessContrast(
...     brightness_limit=0.3,
...     contrast_limit=0.3,
...     p=1.0
... )
>>> augmented_image = transform(image=image)["image"]

# Adjust brightness based on mean value
>>> transform = A.RandomBrightnessContrast(
...     brightness_limit=0.2,
...     contrast_limit=0.2,
...     brightness_by_max=False,
...     p=1.0
... )
>>> augmented_image = transform(image=image)["image"]

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

• [{'description': 'Brightness', 'source': 'https://en.wikipedia.org/wiki/Brightness'}, {'description': 'Contrast', 'source': 'https://en.wikipedia.org/wiki/Contrast_(vision)'}]

Simulate fog by overlaying semi-transparent circles and blending with a fog color. Good for driving or outdoor robustness to weather. Fog is built from random circles with controllable intensity; an image-size-dependent Gaussian blur is applied to the result. Patch-based (no depth); for distance-dependent fog use AtmosphericFog.

Parameters