Illumination

Targets:

image

volume

Image Types:uint8, float32

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

Arguments

mode

linear | corner | gaussian

linear

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]

[0.01, 0.2]

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

brighten | darken | both

both

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]

[0, 360]

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]

[0.1, 0.9]

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]

[0.2, 1]

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]

[1, 1]

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

0.5

Probability of applying the transform. Default: 0.5

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"]

Notes

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

References

[{'description': 'Lighting in Computer Vision', 'source': 'https://en.wikipedia.org/wiki/Lighting_in_computer_vision'}, {'description': 'Image-based lighting', 'source': 'https://en.wikipedia.org/wiki/Image-based_lighting'}, {'description': 'Similar implementation in Kornia', 'source': 'https://kornia.readthedocs.io/en/latest/augmentation.html#randomlinearillumination'}, {'description': 'Research on lighting augmentation', 'source': '"Learning Deep Representations of Fine-grained Visual Descriptions" https://arxiv.org/abs/1605.05395'}, {'description': 'Photography lighting patterns', 'source': 'https://en.wikipedia.org/wiki/Lighting_pattern'}]