albumentations.augmentations.pixel.color_advanced


Advanced color jitter, channel shift, aberration, and photometric transforms.

PlanckianJitterConstclass

PlanckianJitterConst()

ColorJitterclass

ColorJitter(
    brightness_range: tuple[float, float] = (0.8, 1.2),
    contrast_range: tuple[float, float] = (0.8, 1.2),
    saturation_range: tuple[float, float] = (0.8, 1.2),
    hue_range: tuple[float, float] = (-0.5, 0.5),
    p: float = 0.5
)

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, images, volume, volumes Image types: uint8, float16, 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

NameTypeDefaultDescription
brightness_rangetuple[float, float](0.8, 1.2)-
contrast_rangetuple[float, float](0.8, 1.2)-
saturation_rangetuple[float, float](0.8, 1.2)-
hue_rangetuple[float, float](-0.5, 0.5)-
pfloat0.5-

ChromaticAberrationclass

ChromaticAberration(
    primary_distortion_range: tuple[float, float] = (-0.02, 0.02),
    secondary_distortion_range: tuple[float, float] = (-0.05, 0.05),
    mode: Literal['green_purple', 'red_blue', 'random'] = green_purple,
    interpolation: FullInterpolationType = CV2_INTER_LINEAR,
    p: float = 0.5
)

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, images, volume, volumes Image types: uint8, float16, 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

NameTypeDefaultDescription
primary_distortion_rangetuple[float, float](-0.02, 0.02)-
secondary_distortion_rangetuple[float, float](-0.05, 0.05)-
mode
One of:
  • 'green_purple'
  • 'red_blue'
  • 'random'
green_purple-
interpolationFullInterpolationTypeCV2_INTER_LINEAR-
pfloat0.5-

PlanckianJitterclass

PlanckianJitter(
    mode: Literal['blackbody', 'cied'] = blackbody,
    temperature_range: tuple[int, int] | None,
    sampling_method: Literal['uniform', 'gaussian'] = uniform,
    p: float = 0.5
)

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, images, volume, volumes Image types: uint8, float16, 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

NameTypeDefaultDescription
mode
One of:
  • 'blackbody'
  • 'cied'
blackbody-
temperature_range
One of:
  • tuple[int, int]
  • None
--
sampling_method
One of:
  • 'uniform'
  • 'gaussian'
uniform-
pfloat0.5-

RGBShiftclass

RGBShift(
    r_shift_range: tuple[float, float] = (-20, 20),
    g_shift_range: tuple[float, float] = (-20, 20),
    b_shift_range: tuple[float, float] = (-20, 20),
    p: float = 0.5
)

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, images, volume, volumes Image types: uint8, float16, 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

NameTypeDefaultDescription
r_shift_rangetuple[float, float](-20, 20)-
g_shift_rangetuple[float, float](-20, 20)-
b_shift_rangetuple[float, float](-20, 20)-
pfloat0.5-

PhotoMetricDistortclass

PhotoMetricDistort(
    brightness_range: tuple[float, float] = (0.875, 1.125),
    contrast_range: tuple[float, float] = (0.5, 1.5),
    saturation_range: tuple[float, float] = (0.5, 1.5),
    hue_range: tuple[float, float] = (-0.05, 0.05),
    distort_p: float = 0.5,
    p: float = 0.5
)

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, images, volume, volumes Image types: uint8, float16, 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

NameTypeDefaultDescription
brightness_rangetuple[float, float](0.875, 1.125)-
contrast_rangetuple[float, float](0.5, 1.5)-
saturation_rangetuple[float, float](0.5, 1.5)-
hue_rangetuple[float, float](-0.05, 0.05)-
distort_pfloat0.5-
pfloat0.5-