albumentations.augmentations.pixel.color_advanced

Randomly jitter brightness/contrast/saturation/hue in random order. Separate _range 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. Args: brightness_range (tuple[float, float]): Range for the brightness factor, sampled per image. Both ends should be non-negative. Default: (0.8, 1.2) contrast_range (tuple[float, float]): Range for the contrast factor, sampled per image. Both ends should be non-negative. Default: (0.8, 1.2) saturation_range (tuple[float, float]): Range for the saturation factor, sampled per image. Both ends should be non-negative. Default: (0.8, 1.2) hue_range (tuple[float, float]): Range for the hue factor, sampled per image. Values should be in [-0.5, 0.5]. Default: (-0.5, 0.5) p (float): Probability of applying the transform. Should be in the range [0, 1]. Default: 0.5 Targets: image, volume Image types: uint8, float32 Number of channels: 1, 3 Note: - The order of application for these color transformations is random for each image. - The ranges for brightness_range, contrast_range, and saturation_range are applied as multiplicative factors. - The range for hue_range is applied as an additive factor. 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_range=(0.8, 1.2), ... contrast_range=(0.8, 1.2), ... saturation_range=(0.8, 1.2), ... hue_range=(-0.1, 0.1), ... p=1.0, ... ) >>> result = transform(image=image) >>> jittered_image = result['image'] References: - ColorJitter: https://pytorch.org/vision/stable/generated/torchvision.transforms.ColorJitter.html - Color Conversions: https://docs.opencv.org/3.4/de/d25/imgproc_color_conversions.html

Parameters

Add lateral chromatic aberration: shift red/blue channels relative to green. Simulates lens color fringing via primary/secondary distortion ranges. 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. Args: primary_distortion_range (tuple[float, float]): Range of the primary radial distortion coefficient, sampled per image. Controls distortion in the center of the image: - Positive values result in pincushion distortion (edges bend inward) - Negative values result in barrel distortion (edges bend outward) Default: (-0.02, 0.02). secondary_distortion_range (tuple[float, float]): Range of the secondary radial distortion coefficient, sampled per image. Controls distortion in the corners: - Positive values enhance pincushion distortion - Negative values enhance barrel distortion Default: (-0.05, 0.05). mode (Literal['green_purple', 'red_blue', 'random']): Type of color fringing to apply. Options are: - 'green_purple': Distorts red and blue channels in opposite directions, creating green-purple fringing. - 'red_blue': Distorts red and blue channels in the same direction, creating red-blue fringing. - 'random': Randomly chooses between 'green_purple' and 'red_blue' modes for each application. Default: 'green_purple'. interpolation (InterpolationType): Flag specifying the interpolation algorithm. Should be one of: cv2.INTER_NEAREST, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4. Default: cv2.INTER_LINEAR. p (float): Probability of applying the transform. Should be in the range [0, 1]. Default: 0.5. Targets: image, volume Image types: uint8, float32 Number of channels: 3 Note: - 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'. Examples: >>> import albumentations as A >>> import cv2 >>> transform = A.ChromaticAberration( ... primary_distortion_range=(-0.05, 0.05), ... secondary_distortion_range=(-0.1, 0.1), ... mode='green_purple', ... interpolation=cv2.INTER_LINEAR, ... p=1.0, ... ) >>> transformed = transform(image=image) >>> aberrated_image = transformed['image'] References: Chromatic Aberration: https://en.wikipedia.org/wiki/Chromatic_aberration

Parameters

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. Args: mode (Literal['blackbody', 'cied']): The mode of the transformation. - "blackbody": Simulates blackbody radiation color changes. - "cied": Uses the CIE D illuminant series for color temperature simulation. Default: "blackbody" temperature_range (tuple[int, int] | None): The range of color temperatures (in Kelvin) to sample from. - For "blackbody" mode: Should be within [3000K, 15000K]. Default: (3000, 15000) - For "cied" mode: Should be within [4000K, 15000K]. Default: (4000, 15000) If None, the default ranges will be used based on the selected mode. Higher temperatures produce cooler (bluish) images, lower temperatures produce warmer (reddish) images. sampling_method (Literal['uniform', 'gaussian']): Method to sample the temperature. - "uniform": Samples uniformly across the specified range. - "gaussian": Samples from a Gaussian distribution centered at 6500K (approximate daylight). Default: "uniform" p (float): Probability of applying the transform. Default: 0.5 Targets: image, volume Image types: uint8, float32 Number of channels: 3 Note: - 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. 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"] References: - Planck's law: https://en.wikipedia.org/wiki/Planck%27s_law - CIE Standard Illuminants: https://en.wikipedia.org/wiki/Standard_illuminant - Color temperature: https://en.wikipedia.org/wiki/Color_temperature - Implementation inspired by: https://github.com/TheZino/PlanckianJitter

Parameters

Shift R, G, B with separate ranges. Specialized AdditiveNoise with constant uniform shifts. Params: r_shift_range, g_shift_range, b_shift_range. 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. Args: r_shift_range (tuple[int, int]): Range (min, max) for shifting the red channel, sampled per image. For uint8 images values are absolute shifts in [0, 255]; for float images they are relative shifts in [0, 1]. Default: (-20, 20) g_shift_range (tuple[int, int]): Range (min, max) for shifting the green channel, sampled per image. Same units as r_shift_range. Default: (-20, 20) b_shift_range (tuple[int, int]): Range (min, max) for shifting the blue channel, sampled per image. Same units as r_shift_range. Default: (-20, 20) p (float): Probability of applying the transform. Default: 0.5. Targets: image, volume Image types: uint8, float32 Note: - 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] Examples: >>> import numpy as np >>> import albumentations as A # Shift RGB channels of uint8 image >>> transform = A.RGBShift( ... r_shift_range=(-30, 30), # Will sample red shift from [-30, 30] ... g_shift_range=(-20, 20), # Will sample green shift from [-20, 20] ... b_shift_range=(-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 ... ) See Also: - AdditiveNoise: More general noise transform with various options: * Different noise distributions (uniform, gaussian, laplace, beta) * Spatial modes (constant, per-pixel, shared) - RandomToneCurve: For non-linear color transformations - RandomBrightnessContrast: For combined brightness and contrast adjustments - PlankianJitter: For color temperature adjustments - HueSaturationValue: For HSV color space adjustments - ColorJitter: For combined brightness, contrast, saturation adjustments

Parameters

Perturb hematoxylin and eosin concentrations in H&E histology images to simulate stain variation across laboratories, scanners, and protocols. Use this transform to train pathology models against expected staining variation. It converts RGB values to optical density, separates hematoxylin and eosin with the selected stain basis, perturbs both concentrations, and reconstructs the RGB image. Args: method (Literal["preset", "random_preset", "vahadane", "macenko", "custom"]): Selects the stain basis: - "preset": Use the matrix named by `preset`. - "random_preset": Select one of the eight preset matrices for each call. - "vahadane": Extract the matrix from the input with the Vahadane method. - "macenko": Extract the matrix from the input with the Macenko method. - "custom": Use the fixed matrix supplied through `stain_matrix`. Default: "random_preset". preset (str | None): Preset stain matrix used when `method="preset"`: - "ruifrok": Standard reference from Ruifrok and Johnston. - "macenko": Reference from the Macenko method. - "standard": Typical bright-field microscopy. - "high_contrast": Enhanced contrast. - "h_heavy": Hematoxylin-dominant staining. - "e_heavy": Eosin-dominant staining. - "dark": Darker staining. - "light": Lighter staining. When None with `method="preset"`, "standard" is used. Default: None. intensity_scale_range (tuple[float, float]): Non-negative range for the multiplicative concentration factor sampled independently for hematoxylin and eosin. For example, `(0.7, 1.3)` varies each concentration from 70% to 130%. Default: (0.7, 1.3). intensity_shift_range (tuple[float, float]): Range within `[-1.0, 1.0]` for the additive concentration shift sampled independently for hematoxylin and eosin. Default: (-0.2, 0.2). augment_background (bool): Whether to perturb background pixels along with tissue pixels. Default: False. residual_mode (Literal["project", "preserve", "augment"]): Controls the optical-density component orthogonal to the H&E plane: - `"project"`: Reconstruct from H&E only, retaining the two-stain model from earlier releases. - `"preserve"`: Derive the residual basis vector and keep its concentration unchanged. - `"augment"`: Independently perturb the derived residual along with H&E. Default: `"project"`. p (float): Probability of applying the transform. Default: 0.5. stain_matrix (np.ndarray | None): Fixed H&E stain basis used when `method="custom"`. The matrix must have shape `(2, 3)`: row 0 is the hematoxylin RGB optical-density vector and row 1 is the eosin vector. Both rows must contain finite values, be non-zero, and be linearly independent. The transform copies the matrix as `float32` and uses its values without row normalization. Default: None. Targets: image, volume Number of channels: 3 Image types: uint8, float32 Note: - Let `M` be the `(2, 3)` H&E matrix and `C` the per-pixel concentrations. `"project"` solves `OD ~= C @ M`, perturbs H&E, and reconstructs `RGB = exp(-(C * scale + shift) @ M)`. - `"preserve"` and `"augment"` derive `R = normalize(cross(H, E))`, solve the full H&E+R basis, and either retain or perturb the residual concentration. - A custom matrix is fixed for the lifetime of the transform. Per-image callable extraction is not supported. References: - A. C. Ruifrok and D. A. Johnston, "Quantification of histochemical": Analytical and quantitative cytology and histology, 2001. - M. Macenko et al., "A method for normalizing histology slides for: 2009 IEEE International Symposium on quantitative analysis," 2009 IEEE International Symposium on Biomedical Imaging, 2009. - D. Tellez et al., "H&E stain augmentation improves generalization of convolutional networks for histopathological mitosis detection": Medical Imaging, 2018. Examples: >>> import numpy as np >>> import albumentations as A >>> >>> # 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 custom stain matrix calibrated for an acquisition pipeline >>> stain_matrix = np.array( ... [ ... [0.71, 0.65, 0.27], # Hematoxylin ... [0.18, 0.91, 0.37], # Eosin ... ], ... dtype=np.float32, ... ) >>> transform = A.HEStain( ... method="custom", ... stain_matrix=stain_matrix, ... residual_mode="augment", ... intensity_scale_range=(0.8, 1.2), ... intensity_shift_range=(-0.1, 0.1), ... p=1.0, ... ) >>> transformed_image = transform(image=image)["image"] >>> >>> # Example 2: 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, ... ) >>> transformed_image = transform(image=image)["image"] >>> >>> # Example 3: 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, ... ) >>> transformed_image = transform(image=image)["image"] >>> >>> # Example 4: Using Vahadane extraction (requires an H&E stained input) >>> transform = A.HEStain( ... method="vahadane", ... intensity_scale_range=(0.7, 1.3), ... p=1.0, ... ) >>> transformed_image = transform(image=image)["image"] >>> >>> # Example 5: Using Macenko extraction (requires an 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, ... ) >>> transformed_image = transform(image=image)["image"] >>> >>> # Example 6: Combining stain and brightness variation in one pipeline >>> transform = A.Compose([ ... A.HEStain(method="preset", preset="high_contrast", p=1.0), ... A.RandomBrightnessContrast(p=0.5), ... ]) >>> transformed_image = transform(image=image)["image"]

Parameters

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. Args: brightness_range (tuple[float, float]): Multiplicative factor range for brightness. Factor is drawn uniformly from this range. Must be non-negative. Default: `(0.875, 1.125)`. contrast_range (tuple[float, float]): Multiplicative factor range for contrast. Factor is drawn uniformly from this range. Must be non-negative. Default: `(0.5, 1.5)`. saturation_range (tuple[float, float]): Multiplicative factor range for saturation. Factor is drawn uniformly from this range. Must be non-negative. Default: `(0.5, 1.5)`. hue_range (tuple[float, float]): Additive factor range for hue. Factor is drawn uniformly from this range. Must be in `[-0.5, 0.5]`. Default: `(-0.05, 0.05)`. distort_p (float): Probability of applying each individual distortion (brightness, contrast, saturation, hue, channel permutation). Default: `0.5`. p (float): Probability of applying the overall transform. Default: `0.5`. Targets: image, volume Image types: uint8, float32 Number of channels: 1, 3 Note: - 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. 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'] References: - SSD: https://arxiv.org/abs/1512.02325 - torchvision RandomPhotometricDistort: https://pytorch.org/vision/stable/generated/torchvision.transforms.v2.RandomPhotometricDistort.html

Parameters