albumentations.augmentations.pixel.color_lighting

Plasma fractal (Diamond-Square) pattern varies brightness and contrast spatially. brightness_range, contrast_range. Organic, non-uniform look. Uses Diamond-Square algorithm to generate organic-looking fractal patterns that create spatially-varying brightness and contrast adjustments. Args: brightness_range ((float, float)): Range for brightness adjustment strength. Values between -1 and 1: - Positive values increase brightness - Negative values decrease brightness - 0 means no brightness change Default: (-0.3, 0.3) contrast_range ((float, float)): Range for contrast adjustment strength. Values between -1 and 1: - Positive values increase contrast - Negative values decrease contrast - 0 means no contrast change Default: (-0.3, 0.3) plasma_size (int): Size of the initial plasma pattern grid. Larger values create more detailed patterns but are slower to compute. The pattern will be resized to match the input image dimensions. Default: 256 roughness (float): Controls how quickly the noise amplitude increases at each iteration. Must be greater than 0: - Low values (< 1.0): Smoother, more gradual pattern - Medium values (~2.0): Natural-looking pattern - High values (> 3.0): Very rough, noisy pattern Default: 3.0 p (float): Probability of applying the transform. Default: 0.5. Targets: image, volume Image types: uint8, float32 Note: - Works with any number of channels (grayscale, RGB, multispectral) - The same plasma pattern is applied to all channels - Operations are performed in float32 precision - Final values are clipped to valid range [0, max_value] Mathematical Formulation: 1. Plasma Pattern Generation (Diamond-Square Algorithm): Starting with a 3x3 grid of random values in [-1, 1], iteratively: a) Diamond Step: For each 2x2 cell, compute center using diamond kernel: [[0.25, 0.0, 0.25], [0.0, 0.0, 0.0 ], [0.25, 0.0, 0.25]] b) Square Step: Fill remaining points using square kernel: [[0.0, 0.25, 0.0 ], [0.25, 0.0, 0.25], [0.0, 0.25, 0.0 ]] c) Add random noise scaled by roughness^iteration d) Normalize final pattern P to [0,1] range using min-max normalization 2. Brightness Adjustment: For each pixel (x,y): O(x,y) = I(x,y) + b·P(x,y) where: - I is the input image - b is the brightness factor - P is the normalized plasma pattern 3. Contrast Adjustment: For each pixel (x,y): O(x,y) = I(x,y)·(1 + c·P(x,y)) + μ·(1 - (1 + c·P(x,y))) where: - I is the input image - c is the contrast factor - P is the normalized plasma pattern - μ is the mean pixel value Examples: >>> import albumentations as A >>> import numpy as np # Default parameters >>> transform = A.PlasmaBrightnessContrast(p=1.0) # Custom adjustments >>> transform = A.PlasmaBrightnessContrast( ... brightness_range=(-0.5, 0.5), ... contrast_range=(-0.3, 0.3), ... plasma_size=512, # More detailed pattern ... roughness=0.7, # Smoother transitions ... p=1.0 ... ) References: - Fournier, Fussell, and Carpenter, "Computer rendering of stochastic models,": Communications of the ACM, 1982. Paper introducing the Diamond-Square algorithm. - Diamond-Square algorithm: https://en.wikipedia.org/wiki/Diamond-square_algorithm See Also: - RandomBrightnessContrast: For uniform brightness/contrast adjustments - CLAHE: For contrast limited adaptive histogram equalization - FancyPCA: For color-based contrast enhancement - HistogramMatching: For reference-based contrast adjustment

Parameters

Plasma fractal (Diamond-Square) shadow: organic darkening. shadow_intensity_range, roughness. Good for natural shading and lighting variation. Creates organic-looking shadows using plasma fractal noise pattern. The shadow intensity varies smoothly across the image, creating natural-looking darkening effects that can simulate shadows, shading, or lighting variations. Args: shadow_intensity_range (tuple[float, float]): Range for shadow intensity. Values between 0 and 1: - 0 means no shadow (original image) - 1 means maximum darkening (black) - Values between create partial shadows Default: (0.3, 0.7) roughness (float): Controls how quickly the noise amplitude increases at each iteration. Must be greater than 0: - Low values (< 1.0): Smoother, more gradual shadows - Medium values (~2.0): Natural-looking shadows - High values (> 3.0): Very rough, noisy shadows Default: 3.0 p (float): Probability of applying the transform. Default: 0.5. Targets: image, volume Image types: uint8, float32 Note: - The transform darkens the image using a plasma pattern - Works with any number of channels (grayscale, RGB, multispectral) - Shadow pattern is generated using Diamond-Square algorithm with specific kernels - The same shadow pattern is applied to all channels - Final values are clipped to valid range [0, max_value] Mathematical Formulation: 1. Plasma Pattern Generation (Diamond-Square Algorithm): Starting with a 3x3 grid of random values in [-1, 1], iteratively: a) Diamond Step: For each 2x2 cell, compute center using diamond kernel: [[0.25, 0.0, 0.25], [0.0, 0.0, 0.0 ], [0.25, 0.0, 0.25]] b) Square Step: Fill remaining points using square kernel: [[0.0, 0.25, 0.0 ], [0.25, 0.0, 0.25], [0.0, 0.25, 0.0 ]] c) Add random noise scaled by roughness^iteration d) Normalize final pattern P to [0,1] range using min-max normalization 2. Shadow Application: For each pixel (x,y): O(x,y) = I(x,y) * (1 - i*P(x,y)) where: - I is the input image - P is the normalized plasma pattern - i is the sampled shadow intensity - O is the output image Examples: >>> import albumentations as A >>> import numpy as np # Default parameters for natural shadows >>> transform = A.PlasmaShadow(p=1.0) # Subtle, smooth shadows >>> transform = A.PlasmaShadow( ... shadow_intensity_range=(0.1, 0.3), ... roughness=0.7, ... p=1.0 ... ) # Dramatic, detailed shadows >>> transform = A.PlasmaShadow( ... shadow_intensity_range=(0.5, 0.9), ... roughness=0.3, ... p=1.0 ... ) References: - Fournier, Fussell, and Carpenter, "Computer rendering of stochastic models,": Communications of the ACM, 1982. Paper introducing the Diamond-Square algorithm. - Diamond-Square algorithm: https://en.wikipedia.org/wiki/Diamond-square_algorithm See Also: - PlasmaBrightnessContrast: For brightness/contrast adjustments using plasma patterns - RandomShadow: For geometric shadow effects - RandomToneCurve: For global lighting adjustments - PlasmaBrightnessContrast: For brightness/contrast adjustments using plasma patterns

Parameters

Simulate directional, corner, or local Gaussian lighting patterns to make training images more robust to varied illumination conditions. This transform simulates different lighting conditions by applying controlled illumination patterns. It can create effects like: - Directional lighting (linear mode) - Corner shadows/highlights (corner mode) - Spotlights or local lighting (gaussian mode) These effects can be used to: - Simulate natural lighting variations - Add dramatic lighting effects - Create synthetic shadows or highlights - Augment training data with different lighting conditions Args: mode (Literal['linear', 'corner', 'gaussian']): Type of illumination pattern: - 'linear': Creates a smooth gradient across the image, simulating directional lighting like sunlight through a window - 'corner': Applies gradient from any corner, simulating light source from a corner - 'gaussian': Creates a circular spotlight effect, simulating local light sources Default: 'linear' intensity_range (tuple[float, float]): Range for effect strength. Values between 0.01 and 0.2: - 0.01-0.05: Subtle lighting changes - 0.05-0.1: Moderate lighting effects - 0.1-0.2: Strong lighting effects Default: (0.01, 0.2) effect_type (str): Type of lighting change: - 'brighten': Only adds light (like a spotlight) - 'darken': Only removes light (like a shadow) - 'both': Randomly chooses between brightening and darkening Default: 'both' angle_range (tuple[float, float]): Range for gradient angle in degrees. Controls direction of linear gradient: - 0°: Left to right - 90°: Top to bottom - 180°: Right to left - 270°: Bottom to top Only used for 'linear' mode. Default: (0, 360) center_range (tuple[float, float]): Range for spotlight position. Values between 0 and 1 representing relative position: - (0, 0): Top-left corner - (1, 1): Bottom-right corner - (0.5, 0.5): Center of image Only used for 'gaussian' mode. Default: (0.1, 0.9) sigma_range (tuple[float, float]): Range for spotlight size. Values between 0.2 and 1.0: - 0.2: Small, focused spotlight - 0.5: Medium-sized light area - 1.0: Broad, soft lighting Only used for 'gaussian' mode. Default: (0.2, 1.0) num_spots_range (tuple[int, int]): Inclusive range for the number of independently sampled Gaussian spots. Each spot has its own center, sigma, intensity, and effect sign. Overlapping spot fields are multiplied, so several spots can produce a stronger combined effect. Only used for 'gaussian' mode. Default: (1, 1) gaussian_spots (tuple[tuple[float, float, float, float], ...] | None): Optional fixed Gaussian spots. Each spot is represented as `(center_x, center_y, sigma, signed_intensity)`. Providing this value bypasses random spot sampling, and `num_spots_range` must equal the exact number of spots. Default: None p (float): Probability of applying the transform. Default: 0.5 Targets: image, volume Image types: uint8, float32 Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.full((100, 100, 3), 128, dtype=np.uint8) >>> # Simulate sunlight through window >>> transform = A.Illumination( ... mode='linear', ... intensity_range=(0.05, 0.1), ... effect_type='brighten', ... angle_range=(30, 60) ... ) >>> transformed_image = transform(image=image)["image"] >>> >>> # Create dramatic corner shadow >>> transform = A.Illumination( ... mode='corner', ... intensity_range=(0.1, 0.2), ... effect_type='darken' ... ) >>> transformed_image = transform(image=image)["image"] >>> >>> # Add a random number of independently sampled bright and dark spots >>> transform = A.Illumination( ... mode='gaussian', ... num_spots_range=(2, 4), ... intensity_range=(0.05, 0.15), ... effect_type='both', ... center_range=(0.1, 0.9), ... sigma_range=(0.2, 0.5), ... p=1.0, ... ) >>> transformed_image = transform(image=image)["image"] References: - Lighting in Computer Vision: https://en.wikipedia.org/wiki/Lighting_in_computer_vision - Image-based lighting: https://en.wikipedia.org/wiki/Image-based_lighting - Similar implementation in Kornia: https://kornia.readthedocs.io/en/latest/augmentation.html#randomlinearillumination - Research on lighting augmentation: "Learning Deep Representations of Fine-grained Visual Descriptions" https://arxiv.org/abs/1605.05395 - Photography lighting patterns: https://en.wikipedia.org/wiki/Lighting_pattern Note: - The transform preserves image range and dtype - Linear mode adds a signed gradient, matching Kornia's RandomLinearIllumination behavior - Corner and gaussian modes apply multiplicative masks to preserve texture - Can be combined with other transforms for complex lighting scenarios - Useful for training models to be robust to lighting variations

Parameters

Darken corners with a radial (elliptical) gradient. Simulates lens vignetting or natural light falloff. Use for lens realism or stylistic darkening. Center of the image stays bright; corners and edges are darkened. Center position can be jittered for variety. Args: intensity_range (tuple[float, float]): Darkening at corners: 0 = no effect, 1 = black. Default: (0.2, 0.5). center_range (tuple[float, float]): Range for vignette center as fraction of width/height. (0.5, 0.5) = image center. Default: (0.3, 0.7). p (float): Probability of applying the transform. Default: 0.5. Targets: image, volume Image types: uint8, float32 Number of channels: Any Note: - Elliptical gradient centered at a random point (within center_range). - Quadratic falloff from center to edges. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> >>> transform = A.Vignetting(intensity_range=(0.2, 0.5), p=1.0) >>> result = transform(image=image)["image"] See Also: - Halftone: Dot pattern (printing-style) for vintage or print aesthetic. - FilmGrain: Luminance-dependent film grain for vintage texture.

Parameters