albumentations.augmentations.pixel.transforms

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'}]

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'}]

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

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.

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/'}]

Create ringing or overshoot artifacts via 2D sinc convolution. blur_limit and cutoff control strength. Simulates sharpening or compression artifacts. 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

Examples

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

# Apply ringing effect with default parameters
>>> transform = A.RingingOvershoot(p=1.0)
>>> ringing_image = transform(image=image)['image']

# Apply ringing effect with custom parameters
>>> transform = A.RingingOvershoot(
...     blur_limit=(9, 17),
...     cutoff=(np.pi/6, np.pi/3),
...     p=1.0
... )
>>> ringing_image = transform(image=image)['image']

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

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

Sharpen the image via kernel or Gaussian unsharp method. alpha and lightness control strength. Enhances edges; useful for document or detail-sensitive tasks. 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

Examples

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

# Traditional kernel sharpening
>>> transform = A.Sharpen(
...     alpha=(0.2, 0.5),
...     lightness=(0.5, 1.0),
...     method='kernel',
...     p=1.0
... )

# Gaussian interpolation sharpening
>>> transform = A.Sharpen(
...     alpha=(0.5, 1.0),
...     method='gaussian',
...     kernel_size=5,
...     sigma=1.0,
...     p=1.0
... )

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

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

Replace image with superpixel segmentation (SLIC). p_replace, n_segments, max_size control fraction and segment count. Reduces fine texture.

Parameters

Examples

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

# Apply superpixels with default parameters
>>> transform = A.Superpixels(p=1.0)
>>> augmented_image = transform(image=image)['image']

# Apply superpixels with custom parameters
>>> transform = A.Superpixels(
...     p_replace=(0.5, 0.7),
...     n_segments=(50, 100),
...     max_size=None,
...     interpolation=cv2.INTER_NEAREST,
...     p=1.0
... )
>>> augmented_image = transform(image=image)['image']

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

Sharpen via unsharp masking: blur, subtract, add back. blur_limit, sigma_limit, alpha control strength. Luminance unchanged; edges enhanced. 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

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>>
# Apply UnsharpMask with default parameters
>>> transform = A.UnsharpMask(p=1.0)
>>> sharpened_image = transform(image=image)['image']
>>>
# Apply UnsharpMask with custom parameters
>>> transform = A.UnsharpMask(
...     blur_limit=(3, 7),
...     sigma_limit=(0.1, 0.5),
...     alpha=(0.2, 0.7),
...     threshold=15,
...     p=1.0
... )
>>> sharpened_image = transform(image=image)['image']

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

• [{'description': 'Unsharp Masking', 'source': 'https://en.wikipedia.org/wiki/Unsharp_masking'}]