albumentations.augmentations.pixel.functional

Shift the hue, saturation, and value of an image. Args: img (np.ndarray): The image to shift. hue_shift (float): The amount to shift the hue. sat_shift (float): The amount to shift the saturation. val_shift (float): The amount to shift the value. Returns: np.ndarray: The shifted image.

Parameters

Apply HSV shift to a batch of images (N, H, W, C) or (N, H, W). Uses a pre-allocated output array with per-frame shift_hsv calls. This is faster than the base-class np.stack loop because it avoids N intermediate allocations and the final stack copy. A reshape-to-tall-image approach (N,H,W,3) -> (N*H,W,3) was benchmarked but was slower for images >= 512x512 due to cv2.cvtColor and cv2.LUT cache thrashing on the large intermediate arrays.

Parameters

Invert all pixel values above a threshold. Args: img (np.ndarray): The image to solarize. Can be uint8 or float32. threshold (float): Normalized threshold value in range [0, 1]. For uint8 images: pixels above threshold * 255 are inverted For float32 images: pixels above threshold are inverted Returns: np.ndarray: Solarized image. Note: The threshold is normalized to [0, 1] range for both uint8 and float32 images. For uint8 images, the threshold is internally scaled by 255.

Parameters

Reduce the number of bits for each color channel by keeping only the highest N bits. Args: img (np.ndarray): Input image. Can be single or multi-channel. bits (Literal[1, 2, 3, 4, 5, 6, 7] | list[Literal[1, 2, 3, 4, 5, 6, 7]]): Number of high bits to keep.. Can be either: - A single value to apply the same bit reduction to all channels - A list of values to apply different bit reduction per channel. Length of list must match number of channels in image. Returns: np.ndarray: Image with reduced bit depth. Has same shape and dtype as input. Note: - The transform keeps the N highest bits and sets all other bits to 0 - For example, if bits=3: - Original value: 11010110 (214) - Keep 3 bits: 11000000 (192) - The number of unique colors per channel will be 2^bits - Higher bits values = more colors = more subtle effect - Lower bits values = fewer colors = more dramatic posterization Examples: >>> import numpy as np >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> # Same posterization for all channels >>> result = posterize(image, bits=3) >>> # Different posterization per channel >>> result = posterize(image, bits=[3, 4, 5]) # RGB channels

Parameters

Apply histogram equalization to the input image. This function enhances the contrast of the input image by equalizing its histogram. It supports both grayscale and color images, and can operate on individual channels or on the luminance channel of the image. Args: img (np.ndarray): Input image. Can be grayscale (2D array) or RGB (3D array). mask (np.ndarray | None): Optional mask to apply the equalization selectively. If provided, must have the same shape as the input image. Default: None. mode (ImageMode): The backend to use for equalization. Can be either "cv" for OpenCV or "pil" for Pillow-style equalization. Default: "cv". by_channels (bool): If True, applies equalization to each channel independently. If False, converts the image to YCrCb color space and equalizes only the luminance channel. Only applicable to color images. Default: True. Returns: np.ndarray: Equalized image. The output has the same dtype as the input. Raises: ValueError: If the input image or mask have invalid shapes or types. Note: - If the input image is not uint8, it will be temporarily converted to uint8 for processing and then converted back to its original dtype. - For color images, when by_channels=False, the image is converted to YCrCb color space, equalized on the Y channel, and then converted back to RGB. - The function preserves the original number of channels in the image. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> equalized = A.equalize(image, mode="cv", by_channels=True) >>> assert equalized.shape == image.shape >>> assert equalized.dtype == image.dtype

Parameters

Evaluate the Bezier curve at the given t values. Args: t (np.ndarray): The t values to evaluate the Bezier curve at. low_y (float | np.ndarray): The low y values to evaluate the Bezier curve at. high_y (float | np.ndarray): The high y values to evaluate the Bezier curve at. Returns: np.ndarray: The Bezier curve values.

Parameters

Rescales the relationship between bright and dark areas of the image by manipulating its tone curve. Args: img (np.ndarray): Any number of channels low_y (float | np.ndarray): per-channel or single y-position of a Bezier control point used to adjust the tone curve, must be in range [0, 1] high_y (float | np.ndarray): per-channel or single y-position of a Bezier control point used to adjust image tone curve, must be in range [0, 1] num_channels (int): The number of channels in the input image. Returns: np.ndarray: Image with adjusted tone curve

Parameters

Apply a linear transformation to the RGB channels of an image or batch of images. This function applies a 3x3 linear transformation matrix (or batch of matrices) to the RGB channels of either a single image or a batch of images. Args: img (np.ndarray): A single RGB image of shape (H, W, 3), or a batch of images (B, H, W, 3), or a batch of volumes (B, D, H, W, 3). transformation_matrix (np.ndarray): A 3x3 matrix Returns: np.ndarray: Transformed image or batch of images, matching the input shape and dtype. Raises: ValueError: If input shapes do not conform to the supported configurations.

Parameters

Apply Contrast Limited Adaptive Histogram Equalization (CLAHE) to the input image. This function enhances the contrast of the input image using CLAHE. For color images, it converts the image to the LAB color space, applies CLAHE to the L channel, and then converts the image back to RGB. Args: img (np.ndarray): Input image. Can be grayscale (2D array) or RGB (3D array). clip_limit (float): Threshold for contrast limiting. Higher values give more contrast. tile_grid_size (tuple[int, int]): Size of grid for histogram equalization. Width and height of the grid. Returns: np.ndarray: Image with CLAHE applied. The output has the same dtype as the input. Note: - If the input image is float32, it's temporarily converted to uint8 for processing and then converted back to float32. - For color images, CLAHE is applied only to the luminance channel in the LAB color space. Raises: ValueError: If the input image is not 2D or 3D. Examples: >>> import numpy as np >>> img = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> result = clahe(img, clip_limit=2.0, tile_grid_size=(8, 8)) >>> assert result.shape == img.shape >>> assert result.dtype == img.dtype

Parameters

Compress the image using JPEG or WebP compression. Args: img (np.ndarray): Input image quality (int): Quality of compression in range [1, 100] image_type (Literal[".jpg", ".webp"]): Type of compression to use Returns: np.ndarray: Compressed image

Parameters

Adds a simple snow effect to the image by bleaching out pixels. This function simulates a basic snow effect by increasing the brightness of pixels that are above a certain threshold (snow_point). It operates in the HLS color space to modify the lightness channel. Args: img (np.ndarray): Input image. Can be either RGB uint8 or float32. snow_point (float): A float in the range [0, 1], scaled and adjusted to determine the threshold for pixel modification. Higher values result in less snow effect. brightness_coeff (float): Coefficient applied to increase the brightness of pixels below the snow_point threshold. Larger values lead to more pronounced snow effects. Should be greater than 1.0 for a visible effect. Returns: np.ndarray: Image with simulated snow effect. The output has the same dtype as the input. Note: - This function converts the image to the HLS color space to modify the lightness channel. - The snow effect is created by selectively increasing the brightness of pixels. - This method tends to create a 'bleached' look, which may not be as realistic as more advanced snow simulation techniques. - The function automatically handles both uint8 and float32 input images. The snow effect is created through the following steps: 1. Convert the image from RGB to HLS color space. 2. Adjust the snow_point threshold. 3. Increase the lightness of pixels below the threshold. 4. Convert the image back to RGB. Mathematical Formulation: Let L be the lightness channel in HLS space. For each pixel (i, j): If L[i, j] < snow_point: L[i, j] = L[i, j] * brightness_coeff Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) >>> snowy_image = A.functional.add_snow_v1(image, snow_point=0.5, brightness_coeff=1.5) References: - HLS Color Space: https://en.wikipedia.org/wiki/HSL_and_HSV - Original implementation: https://github.com/UjjwalSaxena/Automold--Road-Augmentation-Library

Parameters

Generate snow texture and sparkle mask. Args: img_shape (tuple[int, int]): Image shape. random_generator (np.random.Generator): Random generator to use. Returns: tuple[np.ndarray, np.ndarray]: Tuple of (snow_texture, sparkle_mask) arrays.

Parameters

Add a realistic snow effect to the input image. This function simulates snowfall by applying multiple visual effects to the image, including brightness adjustment, snow texture overlay, depth simulation, and color tinting. The result is a more natural-looking snow effect compared to simple pixel bleaching methods. Args: img (np.ndarray): Input image in RGB format. snow_point (float): Coefficient that controls the amount and intensity of snow. Should be in the range [0, 1], where 0 means no snow and 1 means maximum snow effect. brightness_coeff (float): Coefficient for brightness adjustment to simulate the reflective nature of snow. Should be in the range [0, 1], where higher values result in a brighter image. snow_texture (np.ndarray): Snow texture. sparkle_mask (np.ndarray): Sparkle mask. Returns: np.ndarray: Image with added snow effect. The output has the same dtype as the input. Note: - The function first converts the image to HSV color space for better control over brightness and color adjustments. - A snow texture is generated using Gaussian noise and then filtered for a more natural appearance. - A depth effect is simulated, with more snow at the top of the image and less at the bottom. - A slight blue tint is added to simulate the cool color of snow. - Random sparkle effects are added to simulate light reflecting off snow crystals. The snow effect is created through the following steps: 1. Brightness adjustment in HSV space 2. Generation of a snow texture using Gaussian noise 3. Application of a depth effect to the snow texture 4. Blending of the snow texture with the original image 5. Addition of a cool blue tint 6. Addition of sparkle effects Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) >>> snowy_image = A.functional.add_snow_v2(image, snow_coeff=0.5, brightness_coeff=0.2) Note: This function works with both uint8 and float32 image types, automatically handling the conversion between them. References: - Perlin Noise: https://en.wikipedia.org/wiki/Perlin_noise - HSV Color Space: https://en.wikipedia.org/wiki/HSL_and_HSV

Parameters

Add rain to an image. This function adds rain to an image by drawing rain drops on the image. The rain drops are drawn using the OpenCV function cv2.polylines. Args: img (np.ndarray): The image to add rain to. slant (float): The slant of the rain drops. drop_length (int): The length of the rain drops. drop_width (int): The width of the rain drops. drop_color (tuple[int, int, int]): The color of the rain drops. blur_value (int): The blur value of the rain drops. brightness_coefficient (float): The brightness coefficient of the rain drops. rain_drops (np.ndarray): The rain drops to draw on the image. Returns: np.ndarray: The image with rain added.

Parameters

Generate radiuses for fog particles. Args: img_shape (tuple[int, int]): Image shape. num_particles (int): Number of fog particles. fog_intensity (float): Intensity of the fog effect, between 0 and 1. random_generator (np.random.Generator): Random generator to use. Returns: list[int]: List of radiuses for each fog particle.

Parameters

Add fog to an image. This function adds fog to an image by drawing fog particles on the image. The fog particles are drawn using the OpenCV function cv2.circle. Args: img (np.ndarray): The image to add fog to. fog_intensity (float): The intensity of the fog effect, between 0 and 1. alpha_coef (float): The coefficient for the alpha blending. fog_particle_positions (list[tuple[int, int]]): The positions of the fog particles. fog_particle_radiuses (list[int]): The radiuses of the fog particles. Returns: np.ndarray: The image with fog added.

Parameters

Add a sun flare effect to an image using a simple overlay technique. This function creates a basic sun flare effect by overlaying multiple semi-transparent circles of varying sizes and intensities on the input image. The effect simulates a simple lens flare caused by bright light sources. Args: img (np.ndarray): The input image. flare_center (tuple[float, float]): (x, y) coordinates of the flare center in pixel coordinates. src_radius (int): The radius of the main sun circle in pixels. src_color (tuple[int, ...]): The color of the sun, represented as a tuple of RGB values. circles (list[Any]): A list of tuples, each representing a circle that contributes to the flare effect. Each tuple contains: - alpha (float): The transparency of the circle (0.0 to 1.0). - center (tuple[int, int]): (x, y) coordinates of the circle center. - radius (int): The radius of the circle. - color (tuple[int, int, int]): RGB color of the circle. Returns: np.ndarray: The output image with the sun flare effect added. Note: - This function uses a simple alpha blending technique to overlay flare elements. - The main sun is created as a gradient circle, fading from the center outwards. - Additional flare circles are added along an imaginary line from the sun's position. - This method is computationally efficient but may produce less realistic results compared to more advanced techniques. The flare effect is created through the following steps: 1. Create an overlay image and output image as copies of the input. 2. Add smaller flare circles to the overlay. 3. Blend the overlay with the output image using alpha compositing. 4. Add the main sun circle with a radial gradient. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) >>> flare_center = (50, 50) >>> src_radius = 20 >>> src_color = (255, 255, 200) >>> circles = [ ... (0.1, (60, 60), 5, (255, 200, 200)), ... (0.2, (70, 70), 3, (200, 255, 200)) ... ] >>> flared_image = A.functional.add_sun_flare_overlay( ... image, flare_center, src_radius, src_color, circles ... ) References: - Alpha compositing: https://en.wikipedia.org/wiki/Alpha_compositing - Lens flare: https://en.wikipedia.org/wiki/Lens_flare

Parameters

Add a more realistic sun flare effect to the image. This function creates a complex sun flare effect by simulating various optical phenomena that occur in real camera lenses when capturing bright light sources. The result is a more realistic and physically plausible lens flare effect. Args: img (np.ndarray): Input image. flare_center (tuple[int, int]): (x, y) coordinates of the sun's center in pixels. src_radius (int): Radius of the main sun circle in pixels. src_color (tuple[int, int, int]): Color of the sun in RGB format. circles (list[Any]): List of tuples, each representing a flare circle with parameters: (alpha, center, size, color) - alpha (float): Transparency of the circle (0.0 to 1.0). - center (tuple[int, int]): (x, y) coordinates of the circle center. - size (float): Size factor for the circle radius. - color (tuple[int, int, int]): RGB color of the circle. Returns: np.ndarray: Image with added sun flare effect. Note: This function implements several techniques to create a more realistic flare: 1. Separate flare layer: Allows for complex manipulations of the flare effect. 2. Lens diffraction spikes: Simulates light diffraction in camera aperture. 3. Radial gradient mask: Creates natural fading of the flare from the center. 4. Gaussian blur: Softens the flare for a more natural glow effect. 5. Chromatic aberration: Simulates color fringing often seen in real lens flares. 6. Screen blending: Provides a more realistic blending of the flare with the image. The flare effect is created through the following steps: 1. Create a separate flare layer. 2. Add the main sun circle and diffraction spikes to the flare layer. 3. Add additional flare circles based on the input parameters. 4. Apply Gaussian blur to soften the flare. 5. Create and apply a radial gradient mask for natural fading. 6. Simulate chromatic aberration by applying different blurs to color channels. 7. Blend the flare with the original image using screen blending mode. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [1000, 1000, 3], dtype=np.uint8) >>> flare_center = (500, 500) >>> src_radius = 50 >>> src_color = (255, 255, 200) >>> circles = [ ... (0.1, (550, 550), 10, (255, 200, 200)), ... (0.2, (600, 600), 5, (200, 255, 200)) ... ] >>> flared_image = A.functional.add_sun_flare_physics_based( ... image, flare_center, src_radius, src_color, circles ... ) References: - Lens flare: https://en.wikipedia.org/wiki/Lens_flare - 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

Parameters

Add shadows to the image by reducing the intensity of the pixel values in specified regions. Args: img (np.ndarray): Input image. Multichannel images are supported. vertices_list (list[np.ndarray]): List of vertices for shadow polygons. intensities (np.ndarray): Array of shadow intensities. Range is [0, 1]. Returns: np.ndarray: Image with shadows added. References: Automold--Road-Augmentation-Library: https://github.com/UjjwalSaxena/Automold--Road-Augmentation-Library

Parameters

Add gravel to an image. This function adds gravel to an image by drawing gravel particles on the image. The gravel particles are drawn using the OpenCV function cv2.circle. Args: img (np.ndarray): The image to add gravel to. gravels (list[Any]): The gravel particles to draw on the image. Returns: np.ndarray: The image with gravel added.

Parameters

Invert the colors of an image. This function inverts the colors of an image by subtracting each pixel value from the maximum possible value. The result is a negative of the original image. Args: img (np.ndarray): The image to invert. Returns: np.ndarray: The inverted image.

Parameters

Shuffle the channels of an image. This function shuffles the channels of an image by using the cv2.mixChannels function. The channels are shuffled according to the channels_shuffled array. Args: img (np.ndarray): The image to shuffle. channels_shuffled (np.ndarray): The array of channels to shuffle. Returns: np.ndarray: The shuffled image.

Parameters

Shuffle channels of a single volume (D, H, W, C) or (D, H, W). Args: volume (np.ndarray): Input volume. channels_shuffled (Sequence[int]): New channel order. Returns: np.ndarray: Volume with channels shuffled.

Parameters

Shuffle channels of a batch of volumes (B, D, H, W, C) or (B, D, H, W). Args: volumes (np.ndarray): Input batch of volumes. channels_shuffled (Sequence[int]): New channel order. Returns: np.ndarray: Batch of volumes with channels shuffled.

Parameters

Apply gamma transformation to an image. This function applies gamma transformation to an image by raising each pixel value to the power of gamma. The result is a non-linear transformation that can enhance or reduce the contrast of the image. Args: img (np.ndarray): The image to apply gamma transformation to. gamma (float): The gamma value to apply. Returns: np.ndarray: The gamma transformed image.

Parameters

Apply poisson noise to an image to simulate camera sensor noise. Args: image (np.ndarray): Input image. Currently, only RGB images are supported. color_shift (float): The amount of color shift to apply. intensity (float): Multiplication factor for noise values. Values of ~0.5 produce a noticeable, yet acceptable level of noise. random_generator (np.random.Generator): If specified, this will be random generator used for noise generation. Returns: np.ndarray: The noised image. Image types: uint8, float32 Number of channels: 3

Parameters

Convert RGB image(s) to grayscale using the weighted average method. This function uses OpenCV's cvtColor function with COLOR_RGB2GRAY conversion, which applies the following formula: Y = 0.299*R + 0.587*G + 0.114*B The function efficiently handles batches and volumes by reshaping them into a tall 2D image for processing, then restoring the original shape structure. Args: img (np.ndarray): Input RGB image(s) as a numpy array. Supported shapes: - Single image: (H, W, 3) - Batch of images: (N, H, W, 3) - Volume: (D, H, W, 3) - Batch of volumes: (N, D, H, W, 3) Returns: np.ndarray: Grayscale image as a 2D numpy array. Image types: uint8, float32 Number of channels: 3

Parameters

Convert an RGB image or batch of images to grayscale using LAB color space. This function converts RGB images to grayscale by first converting to LAB color space and then extracting the L (lightness) channel. It uses albucore's reshape utilities to efficiently handle batches/volumes by processing them as a single tall image. Implementation Details: The function uses albucore's reshape_for_channel and restore_from_channel functions: - reshape_for_channel: Flattens batches/volumes to 2D format for OpenCV processing - restore_from_channel: Restores the original shape after processing This enables processing all images in a single OpenCV call Args: img: Input RGB image(s) as a numpy array. Must have 3 channels in the last dimension. Supported shapes: - Single image: (H, W, 3) - Batch of images: (N, H, W, 3) - Volume: (D, H, W, 3) - Batch of volumes: (N, D, H, W, 3) Supported dtypes: - np.uint8: Values in range [0, 255] - np.float32: Values in range [0, 1] Returns: Grayscale image(s) with the same spatial dimensions as input but without channel dimension: - Single image: (H, W) - Batch of images: (N, H, W) - Volume: (D, H, W) - Batch of volumes: (N, D, H, W) The output dtype matches the input dtype. For float inputs, the L channel is normalized to [0, 1] by dividing by 100. Raises: ValueError: If the last dimension is not 3 (RGB channels) Examples: >>> # Single image >>> img = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> gray = to_gray_from_lab(img) >>> assert gray.shape == (100, 100) >>> # Batch of images - efficiently processed without loops >>> batch = np.random.randint(0, 256, (10, 100, 100, 3), dtype=np.uint8) >>> gray_batch = to_gray_from_lab(batch) >>> assert gray_batch.shape == (10, 100, 100) >>> # Volume (e.g., video frames or 3D medical data) >>> volume = np.random.randint(0, 256, (16, 100, 100, 3), dtype=np.uint8) >>> gray_volume = to_gray_from_lab(volume) >>> assert gray_volume.shape == (16, 100, 100) >>> # Float32 input >>> img_float = img.astype(np.float32) / 255.0 >>> gray_float = to_gray_from_lab(img_float) >>> assert 0 <= gray_float.min() <= gray_float.max() <= 1.0 Note: The LAB color space provides perceptually uniform grayscale conversion, where the L (lightness) channel represents human perception of brightness better than simple RGB averaging or other methods.

Parameters

Convert an image to grayscale using the desaturation method. Args: img (np.ndarray): Input image as a numpy array. Returns: np.ndarray: Grayscale image as a 2D numpy array. Image types: uint8, float32 Number of channels: any

Parameters

Convert an image to grayscale using the average method. This function computes the arithmetic mean across all channels for each pixel, resulting in a grayscale representation of the image. Key aspects of this method: 1. It treats all channels equally, regardless of their perceptual importance. 2. Works with any number of channels, making it versatile for various image types. 3. Simple and fast to compute, but may not accurately represent perceived brightness. 4. For RGB images, the formula is: Gray = (R + G + B) / 3 Note: This method may produce different results compared to weighted methods (like RGB weighted average) which account for human perception of color brightness. It may also produce unexpected results for images with alpha channels or non-color data in additional channels. Args: img (np.ndarray): Input image as a numpy array. Can be any number of channels. Returns: np.ndarray: Grayscale image as a 2D numpy array. The output data type matches the input data type. Image types: uint8, float32 Number of channels: any

Parameters

Convert an image to grayscale using the maximum channel value method. This function takes the maximum value across all channels for each pixel, resulting in a grayscale image that preserves the brightest parts of the original image. Key aspects of this method: 1. Works with any number of channels, making it versatile for various image types. 2. For 3-channel (e.g., RGB) images, this method is equivalent to extracting the V (Value) channel from the HSV color space. 3. Preserves the brightest parts of the image but may lose some color contrast information. 4. Simple and fast to compute. Note: - This method tends to produce brighter grayscale images compared to other conversion methods, as it always selects the highest intensity value from the channels. - For RGB images, it may not accurately represent perceived brightness as it doesn't account for human color perception. Args: img (np.ndarray): Input image as a numpy array. Can be any number of channels. Returns: np.ndarray: Grayscale image as a 2D numpy array. The output data type matches the input data type. Image types: uint8, float32 Number of channels: any

Parameters

Convert an image to grayscale using Principal Component Analysis (PCA). This function applies PCA to reduce a multi-channel image to a single channel, effectively creating a grayscale representation that captures the maximum variance in the color data. Args: img (np.ndarray): Input image as a numpy array. Can be: - Single multi-channel image: (H, W, C) - Batch of multi-channel images: (N, H, W, C) - Single multi-channel volume: (D, H, W, C) - Batch of multi-channel volumes: (N, D, H, W, C) Returns: np.ndarray: Grayscale image with the same spatial dimensions as input. If input is uint8, output is uint8 in range [0, 255]. If input is float32, output is float32 in range [0, 1]. Note: This method can potentially preserve more information from the original image compared to standard weighted average methods, as it accounts for the correlations between color channels. Image types: uint8, float32 Number of channels: any

Parameters

Convert an image to grayscale using a specified method. This function converts an image to grayscale using a specified method. The method can be one of the following: - "weighted_average": Use the weighted average method. - "from_lab": Use the L channel from the LAB color space. - "desaturation": Use the desaturation method. - "average": Use the average method. - "max": Use the maximum channel value method. - "pca": Use the Principal Component Analysis method. Args: img (np.ndarray): Input image as a numpy array. num_output_channels (int): The number of channels in the output image. method (Literal["weighted_average", "from_lab", "desaturation", "average", "max", "pca"]): The method to use for grayscale conversion. Returns: np.ndarray: Grayscale image as a 2D numpy array.

Parameters

Convert a grayscale image to a multi-channel image. This function takes a 2D grayscale image or a 3D image with a single channel and converts it to a multi-channel image by repeating the grayscale data across the specified number of channels. Args: grayscale_image (np.ndarray): Input grayscale image. Can be 2D (height, width) or 3D (height, width, 1). num_output_channels (int, optional): Number of channels in the output image. Defaults to 3. Returns: np.ndarray: Multi-channel image with shape (height, width, num_channels)

Parameters

Downscale and upscale an image. This function downscales and upscales an image using the specified interpolation methods. The downscaling and upscaling are performed using albucore.resize. Args: img (np.ndarray): Input image as a numpy array. scale (float): The scale factor for the downscaling and upscaling. down_interpolation (int): The interpolation method for the downscaling. up_interpolation (int): The interpolation method for the upscaling. Returns: np.ndarray: The downscaled and upscaled image.

Parameters

No-op function. This function is a no-op and returns the input object unchanged. It is used to satisfy the type checker requirements for the `noop` function. Args: input_obj (Any): The input object to return unchanged. **params (Any): Additional keyword arguments. Returns: Any: The input object unchanged.

Parameters

Perform 'Fancy PCA' augmentation on an image with any number of channels. Args: img (np.ndarray): Input image alpha_vector (np.ndarray): Vector of scale factors for each principal component. Should have the same length as the number of channels in the image. Returns: np.ndarray: Augmented image of the same shape, type, and range as the input. Image types: uint8, float32 Number of channels: Any Note: - This function generalizes the Fancy PCA augmentation to work with any number of channels. - It preserves the original range of the image ([0, 255] for uint8, [0, 1] for float32). - For single-channel images, the augmentation is applied as a simple scaling of pixel intensity variation. - For multi-channel images, PCA is performed on the entire image, treating each pixel as a point in N-dimensional space (where N is the number of channels). - The augmentation preserves the correlation between channels while adding controlled noise. - Computation time may increase significantly for images with a large number of channels. References: ImageNet classification with deep convolutional neural networks: Krizhevsky, A., Sutskever, I., & Hinton, G. E. (2012): In Advances in neural information processing systems (pp. 1097-1105).

Parameters

Adjust the brightness of an image. This function adjusts the brightness of an image by multiplying each pixel value by a factor. The brightness is adjusted by multiplying the image by the factor. Args: img (np.ndarray): Input image as a numpy array. factor (np.ndarray): The factor to adjust the brightness by. Returns: np.ndarray: The adjusted image.

Parameters

Adjust the contrast of an image. This function adjusts the contrast of an image by multiplying each pixel value by a factor. The contrast is adjusted by multiplying the image by the factor. Args: img (np.ndarray): Input image as a numpy array. factor (float): The factor to adjust the contrast by. Returns: np.ndarray: The adjusted image.

Parameters

Adjust the saturation of an image by blending with grayscale. Uses to_gray for conversion: weighted_average for RGB (matches OpenCV), average for arbitrary channels. Works on batches (4D) and volumes (5D). Args: img (np.ndarray): Input image as a numpy array. factor (float): The factor to adjust the saturation by. gamma (float): Unused, kept for API compatibility. Returns: np.ndarray: The adjusted image.

Parameters

Adjust the hue of an image. This function adjusts the hue of an image by adding a factor to the hue value. Args: img (np.ndarray): Input image. factor (float): The factor to adjust the hue by. Returns: np.ndarray: The adjusted image.

Parameters

Apply brightness and contrast adjustments fused into a single LUT (uint8) or two passes (float32). Both operations are `clip(a*x + b)`. The image grayscale mean is computed once and propagated analytically through the pipeline: if brightness comes first, `mean_at_contrast = mean * brightness_factor` (clipped to valid range). This avoids re-reading the image after brightness is applied. For uint8 images the composition is pre-computed over all 256 input values into a single 256-entry LUT applied in one `cv2.LUT` call. For float32, two sequential clipped passes are used. Args: img: Input image (uint8 or float32). brightness_factor: Brightness multiplicative factor. contrast_factor: Contrast multiplicative factor. brightness_first: Whether brightness is applied before contrast. Returns: ImageType: Adjusted image with the same dtype as input.

Parameters

Apply superpixels to an image. This function applies superpixels to an image using the SLIC algorithm. The superpixels are applied by replacing the pixels in the image with the mean intensity of the superpixel. Args: image (np.ndarray): Input image as a numpy array. n_segments (int): The number of segments to use for the superpixels. replace_samples (Sequence[bool]): The samples to replace. max_size (int | None): The maximum size of the superpixels. interpolation (int): The interpolation method to use. Returns: np.ndarray: The superpixels applied to the image.

Parameters

Apply unsharp mask to a batch of images. Processes a batch of images (N, H, W, C) by applying the unsharp mask to each image and writing directly into a pre-allocated output array. Args: images: Batch of images with shape (N, H, W, C) or (N, H, W). ksize: The kernel size for Gaussian blur. sigma: The sigma value for Gaussian blur. alpha: The alpha value for the unsharp mask. threshold: The threshold value for the unsharp mask. Returns: Batch of unsharp masked images with same shape and dtype as input. Note: we intentionally avoid @float32_io/@clipped decorators here. Those decorators convert the entire batch at once, which is ~2x slower for uint8 than per-image conversion due to poor cache locality on large 4D arrays.

Parameters

Apply unsharp mask to a single image. Backward-compatible wrapper around unsharp_mask_images for a single image. Args: image: Single image, shape (H, W, C) or (H, W). ksize: The kernel size for Gaussian blur. sigma: The sigma value for Gaussian blur. alpha: The alpha value for the unsharp mask. threshold: The threshold value for the unsharp mask. Returns: Unsharp masked image with same shape and dtype as input.

Parameters

Apply pixel dropout to the image. Args: image (np.ndarray): Input image drop_mask (np.ndarray): Boolean mask indicating which pixels to drop drop_values (np.ndarray): Values to replace dropped pixels with Returns: np.ndarray: Image with dropped pixels

Parameters

Apply spatter rain to an image. This function applies spatter rain to an image by adding the rain to the image. Args: img (np.ndarray): Input image as a numpy array. rain (np.ndarray): Rain image as a numpy array. Returns: np.ndarray: The spatter rain applied to the image.

Parameters

Apply spatter mud to an image. This function applies spatter mud to an image by adding the mud to the image. Args: img (np.ndarray): Input image as a numpy array. non_mud (np.ndarray): Non-mud image as a numpy array. mud (np.ndarray): Mud image as a numpy array. Returns: np.ndarray: The spatter mud applied to the image.

Parameters

Apply chromatic aberration to an image. This function applies chromatic aberration to an image by distorting the red and blue channels. Args: img (np.ndarray): Input image as a numpy array. primary_distortion_red (float): The primary distortion of the red channel. secondary_distortion_red (float): The secondary distortion of the red channel. primary_distortion_blue (float): The primary distortion of the blue channel. secondary_distortion_blue (float): The secondary distortion of the blue channel. interpolation (int): The interpolation method to use. Returns: np.ndarray: The chromatic aberration applied to the image.

Parameters

Apply Planckian jitter to an image. This function applies Planckian jitter to an image by linearly interpolating between the two closest temperatures in the PLANCKIAN_COEFFS dictionary. Args: img (np.ndarray): Input image as a numpy array. temperature (int): The temperature to apply. mode (Literal["blackbody", "cied"]): The mode to use. Returns: np.ndarray: The Planckian jitter applied to the image.

Parameters

Add noise to an image. This function adds noise to an image by adding the noise to the image. Args: img (np.ndarray): Input image as a numpy array. noise (np.ndarray): Noise as a numpy array. Returns: np.ndarray: The noise added to the image.

Parameters

Simple Linear Iterative Clustering (SLIC) superpixel segmentation using OpenCV and NumPy. Args: image (np.ndarray): Input image (3D numpy array with shape (H, W, C)). n_segments (int): Approximate number of superpixels to generate. compactness (float): Balance between color proximity and space proximity. max_iterations (int): Maximum number of iterations for k-means. Returns: np.ndarray: Segmentation mask where each superpixel has a unique label.

Parameters

Apply shot noise to the image. Args: img (np.ndarray): Input image scale (float): Scale factor for the noise random_generator (np.random.Generator): Random number generator Returns: np.ndarray: Image with shot noise

Parameters

Get safe brightness and contrast parameters. Args: alpha (float): Contrast factor beta (float): Brightness factor max_value (float): Maximum pixel value Returns: tuple[float, float]: Safe alpha and beta values

Parameters

Generate constant noise using Python's random generator (faster for small arrays). This function generates constant noise using Python's random generator, which is more efficient for generating a small number of values (one per channel). Args: noise_type (Literal["uniform", "gaussian", "laplace", "beta"]): The type of noise to generate. shape (tuple[int, ...]): The shape of the noise to generate. params (dict[str, Any] | None): The parameters of the noise to generate. max_value (float): The maximum value of the noise to generate. py_random (random.Random): Python's random generator to use. Returns: np.ndarray: The noise generated.

Parameters

Generate spatial noise (per_pixel or shared) with optional approximation for speed. This function generates spatial noise with optional approximation for speed. Args: noise_type (Literal["uniform", "gaussian", "laplace", "beta"]): The type of noise to generate. spatial_mode (Literal["per_pixel", "shared"]): The spatial mode to use. shape (tuple[int, ...]): The shape of the noise to generate. params (dict[str, Any] | None): The parameters of the noise to generate. max_value (float): The maximum value of the noise to generate. approximation (float): The approximation to use for the noise to generate. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The noise generated.

Parameters

Generate per-pixel noise. This function generates per-pixel noise by sampling from the noise distribution. Args: noise_type (Literal["uniform", "gaussian", "laplace", "beta"]): The type of noise to generate. shape (tuple[int, ...]): The shape of the noise to generate. params (dict[str, Any]): The parameters of the noise to generate. max_value (float): The maximum value of the noise to generate. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The per-pixel noise generated.

Parameters

Sample from specific noise distribution. This function samples from a specific noise distribution. Args: noise_type (Literal["uniform", "gaussian", "laplace", "beta"]): The type of noise to generate. size (tuple[int, ...]): The size of the noise to generate. params (dict[str, Any]): The parameters of the noise to generate. max_value (float): The maximum value of the noise to generate. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The noise sampled.

Parameters

Sample from uniform distribution for spatial noise. Args: size (tuple[int, ...]): Size of the output array params (dict[str, Any]): Distribution parameters random_generator (np.random.Generator): Random number generator Returns: np.ndarray: Sampled values

Parameters

Sample from Gaussian distribution. This function samples from a Gaussian distribution. Args: size (tuple[int, ...]): The size of the noise to generate. params (dict[str, Any]): The parameters of the noise to generate. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The Gaussian noise sampled.

Parameters

Sample from Laplace distribution. This function samples from a Laplace distribution. Args: size (tuple[int, ...]): The size of the noise to generate. params (dict[str, Any]): The parameters of the noise to generate. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The Laplace noise sampled.

Parameters

Sample from Beta distribution. This function samples from a Beta distribution. Args: size (tuple[int, ...]): The size of the noise to generate. params (dict[str, Any]): The parameters of the noise to generate. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The Beta noise sampled.

Parameters

Generate shared noise. Args: noise_type (Literal["uniform", "gaussian", "laplace", "beta"]): Type of noise to generate shape (tuple[int, ...]): Shape of the output array params (dict[str, Any]): Distribution parameters max_value (float): Maximum value for the noise random_generator (np.random.Generator): Random number generator Returns: np.ndarray: Generated noise

Parameters

Sharpen image using Gaussian blur. This function sharpens an image using a Gaussian blur. Args: img (np.ndarray): The image to sharpen. alpha (float): The alpha value to use for the sharpening. kernel_size (int): The kernel size to use for the Gaussian blur. sigma (float): The sigma value to use for the Gaussian blur. Returns: np.ndarray: The sharpened image.

Parameters

Apply salt and pepper noise to an image. This function applies salt and pepper noise to an image using pre-computed masks. Salt pixels are set to maximum value, pepper pixels are set to 0. Args: img (np.ndarray): Input image of any dtype and dimensions: - 2D: (H, W) - grayscale - 3D: (H, W, C) - RGB/multi-channel - 4D: (D, H, W, C) - volume with depth salt_mask (np.ndarray): Boolean mask indicating salt pixels (H, W) pepper_mask (np.ndarray): Boolean mask indicating pepper pixels (H, W) Returns: np.ndarray: The image with salt and pepper noise applied.

Parameters

Generate a plasma pattern. This function generates a plasma pattern using the diamond-square algorithm. Args: target_shape (tuple[int, int]): The shape of the plasma pattern to generate. roughness (float): The roughness of the plasma pattern. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The plasma pattern generated.

Parameters

Apply plasma-based brightness and contrast adjustments. This function applies plasma-based brightness and contrast adjustments to an image. Args: img (np.ndarray): The image to apply the brightness and contrast adjustments to. brightness_factor (float): The brightness factor to apply. contrast_factor (float): The contrast factor to apply. plasma_pattern (np.ndarray): The plasma pattern to use for the brightness and contrast adjustments. Returns: np.ndarray: The image with the brightness and contrast adjustments applied.

Parameters

Apply plasma shadow to the image. Args: img (np.ndarray): Input image intensity (float): Shadow intensity plasma_pattern (np.ndarray): Plasma pattern to use Returns: np.ndarray: Image with plasma shadow

Parameters

Create a directional gradient in [0, 1] range. This function creates a directional gradient in the [0, 1] range. Args: height (int): The height of the image. width (int): The width of the image. angle (float): The angle of the gradient. Returns: np.ndarray: The directional gradient.

Parameters

Create an illumination gradient map of shape (H, W) or (H, W, 1). Returns a float32 gradient that can be applied via multiply_by_array. The returned gradient does NOT have a channel dimension.

Parameters

Apply linear illumination to the image. Args: img (np.ndarray): Input image intensity (float): Illumination intensity angle (float): Illumination angle in radians Returns: np.ndarray: Image with linear illumination

Parameters

Apply corner illumination to the image. Args: img (np.ndarray): Input image intensity (float): Illumination intensity corner (Literal[0, 1, 2, 3]): The corner to apply the illumination to. Returns: np.ndarray: Image with corner illumination applied.

Parameters

Apply gaussian illumination to the image. Args: img (np.ndarray): Input image intensity (float): Illumination intensity center (tuple[float, float]): The center of the illumination. sigma (float): The sigma of the illumination.

Parameters

Apply automatic contrast enhancement. Args: img (np.ndarray): Input image cutoff (float): Cutoff percentage for histogram ignore (int | None): Value to ignore in histogram method (Literal["cdf", "pil"]): Method to use for contrast enhancement Returns: np.ndarray: Image with enhanced contrast

Parameters

Create lookup table for contrast adjustment. This function creates a lookup table for contrast adjustment. Args: hist (np.ndarray): Histogram of the image. min_intensity (int): Minimum intensity of the histogram. max_intensity (int): Maximum intensity of the histogram. max_value (int): Maximum value of the lookup table. method (Literal["cdf", "pil"]): Method to use for contrast enhancement. Returns: np.ndarray: Lookup table for contrast adjustment.

Parameters

Get the low and high bounds of the histogram. This function gets the low and high bounds of the histogram. Args: hist (np.ndarray): Histogram of the image. cutoff (float): Cutoff percentage for histogram. Returns: tuple[int, int]: Low and high bounds of the histogram.

Parameters

Generate dropout mask. This function generates a dropout mask. Args: shape (tuple[int, ...]): Shape of the output mask per_channel (bool): Whether to apply dropout per channel dropout_prob (float): Dropout probability random_generator (np.random.Generator): Random number generator Returns: np.ndarray: Dropout mask

Parameters

Generate random values. Args: channels (int): Number of channels dtype (np.dtype): Data type of the output array random_generator (np.random.Generator): Random number generator Returns: np.ndarray: Random values

Parameters

Prepare values to fill dropped pixels. Args: array (np.ndarray): Input array to determine shape and dtype value (float | Sequence[float] | np.ndarray | None): User-specified drop values or None for random random_generator (np.random.Generator): Random number generator Returns: np.ndarray: Array of values matching input shape

Parameters

Get mask array from input data if it exists.

Parameters

Generate parameters for rain effect. This function generates parameters for a rain effect. Args: liquid_layer (np.ndarray): Liquid layer of the image. color (np.ndarray): Color of the rain. intensity (float): Intensity of the rain. Returns: dict[str, Any]: Parameters for the rain effect.

Parameters

Generate parameters for mud effect. This function generates parameters for a mud effect. Args: liquid_layer (np.ndarray): Liquid layer of the image. color (np.ndarray): Color of the mud. cutout_threshold (float): Cutout threshold for the mud. sigma (float): Sigma for the Gaussian blur. intensity (float): Intensity of the mud. random_generator (np.random.Generator): Random number generator. Returns: dict[str, Any]: Parameters for the mud effect.

Parameters

Convert RGB image to optical density. This function converts an RGB image to optical density. Args: img (np.ndarray): Input image. eps (float): Epsilon value. Returns: np.ndarray: Optical density image.

Parameters

Normalize vectors. This function normalizes vectors. Args: vectors (np.ndarray): Vectors to normalize. Returns: np.ndarray: Normalized vectors.

Parameters

Get stain normalizer based on method. This function gets a stain normalizer based on a method. Args: method (Literal["vahadane", "macenko"]): Method to use for stain normalization. Returns: StainNormalizer: Stain normalizer.

Parameters

Base class for stain normalizers.

Simple Non-negative Matrix Factorization (NMF) for histology stain separation. This class implements a simplified version of the Non-negative Matrix Factorization algorithm specifically designed for separating Hematoxylin and Eosin (H&E) stains in histopathology images. It is used as part of the Vahadane stain normalization method. The algorithm decomposes optical density values of H&E stained images into stain color appearances (the stain color vectors) and stain concentrations (the density of each stain at each pixel). The implementation uses an iterative multiplicative update approach that preserves non-negativity constraints, which are physically meaningful for stain separation as concentrations and absorption coefficients cannot be negative. This implementation is optimized for stability by: 1. Initializing with standard H&E reference colors from Ruifrok 2. Using normalized projection for initial concentrations 3. Applying careful normalization to avoid numerical issues Args: n_iter (int): Number of iterations for the NMF algorithm. Default: 100 References: - Vahadane, A., et al. (2016): Structure-preserving color normalization and sparse stain separation for histological images. IEEE Transactions on Medical Imaging, 35(8), 1962-1971. - Ruifrok, A. C., & Johnston, D. A. (2001): Quantification of histochemical staining by color deconvolution. Analytical and Quantitative Cytology and Histology, 23(4), 291-299.

Parameters

Order stains using a combination of methods. This combines both angular information and spectral characteristics for more robust identification. Args: stain_colors (np.ndarray): Stain colors. Returns: tuple[int, int]: Hematoxylin and eosin indices.

Parameters

A stain normalizer implementation based on Vahadane's method for histopathology images. This class implements the "Structure-Preserving Color Normalization and Sparse Stain Separation for Histological Images" method proposed by Vahadane et al. The technique uses Non-negative Matrix Factorization (NMF) to separate Hematoxylin and Eosin (H&E) stains in histopathology images and then normalizes them to a target standard. The Vahadane method is particularly effective for histology image normalization because: 1. It maintains tissue structure during color normalization 2. It performs sparse stain separation, reducing color bleeding 3. It adaptively estimates stain vectors from each image 4. It preserves biologically relevant information This implementation uses SimpleNMF as its core matrix factorization algorithm to extract stain color vectors (appearance matrix) and concentration matrices from optical density-transformed images. It identifies the Hematoxylin and Eosin stains by their characteristic color profiles and spatial distribution. References: Vahadane, et al., 2016: Structure-preserving color normalization and sparse stain separation for histological images. IEEE transactions on medical imaging, 35(8), pp.1962-1971. Examples: >>> import numpy as np >>> import albumentations as A >>> from albumentations.augmentations.pixel import functional as F >>> import cv2 >>> >>> # Load source and target images (H&E stained histopathology) >>> source_img = cv2.imread('source_image.png') >>> source_img = cv2.cvtColor(source_img, cv2.COLOR_BGR2RGB) >>> target_img = cv2.imread('target_image.png') >>> target_img = cv2.cvtColor(target_img, cv2.COLOR_BGR2RGB) >>> >>> # Create and fit the normalizer to the target image >>> normalizer = F.VahadaneNormalizer() >>> normalizer.fit(target_img) >>> >>> # Normalize the source image to match the target's stain characteristics >>> normalized_img = normalizer.transform(source_img)

Macenko stain normalizer with optimized computations.

Parameters

Get tissue mask from image. Args: img (np.ndarray): Input image threshold (float): Threshold for tissue detection. Default: 0.85 Returns: np.ndarray: Binary mask where True indicates tissue regions

Parameters

Apply HE stain augmentation to an image. This function applies HE stain augmentation to an image. Args: img (np.ndarray): Input image. stain_matrix (np.ndarray): Stain matrix. scale_factors (np.ndarray): Scale factors. shift_values (np.ndarray): Shift values. augment_background (bool): Whether to augment the background. Returns: np.ndarray: Augmented image.

Parameters

Convolve an image with a kernel. This function convolves an image with a kernel. Args: img (np.ndarray): Input image. kernel (np.ndarray): Kernel. Returns: np.ndarray: Convolved image.

Parameters

Convolve an image with a separable kernel. This function convolves an image with a separable kernel. Args: img (np.ndarray): Input image. kernel (np.ndarray): Kernel. Returns: np.ndarray: Convolved image.

Parameters

Apply vignetting effect by darkening corners with a radial gradient. Args: img: Input image of shape (H, W) or (H, W, C). intensity: Strength of darkening at corners, in [0, 1]. center_x: Horizontal center of the vignette as fraction of width, in [0, 1]. center_y: Vertical center of the vignette as fraction of height, in [0, 1]. Returns: Image with vignetting applied.

Parameters

Apply film grain noise to an image (2D or 3D). Film grain is luminance-dependent and spatially correlated, unlike simple Gaussian noise. Args: img: Input image, shape (H, W, C) or (H, W, 1). grain: Pre-generated grain pattern, shape (H, W), float32. intensity: Grain strength multiplier. Returns: Image with film grain applied.

Parameters

Convert image to halftone dot pattern. Args: img: Input image (H, W, C), uint8 or float32. dot_size: Size of each halftone grid cell in pixels. blend: Blend factor between halftone and original. 0 = pure halftone, 1 = original. Returns: Image with halftone effect applied.

Parameters

Apply realistic lens flare with ghosts and starburst. Args: img: Input image (H, W, C), must be 3-channel. flare_center: (x, y) position of the flare source. ghosts: List of (x, y, radius, alpha) for each ghost circle. starburst_angles: Array of angles in radians for starburst rays. starburst_intensity: Brightness of starburst rays, 0-1. bloom_radius: Gaussian blur radius for bloom effect. Returns: Image with lens flare applied.

Parameters

Generate displacement maps simulating water refraction. Args: image_shape: (height, width). amplitude: Maximum displacement in pixels. wavelength: Base wavelength of waves in pixels. num_waves: Number of overlaid sine waves. random_generator: NumPy random generator. Returns: Tuple of (map_x, map_y) float32 arrays for cv2.remap.

Parameters

Apply depth-aware atmospheric fog using the standard scattering model. Formula: result = img * exp(-density * depth) + fog_color * (1 - exp(-density * depth)) Args: img: Input image (H, W, C). density: Fog density factor. fog_color: Color of the fog, values in [0, max_val]. depth_map: (H, W) float32 array with values in [0, 1], where 1 is farthest. Returns: Image with fog applied.

Parameters