...

Illumination

Targets:
image
volume
Image Types:uint8, float32

Apply various illumination effects to the image.

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)
p
float
0.5

Probability of applying the transform. Default: 0.5

Examples
>>> import albumentations as A
>>> # Simulate sunlight through window
>>> transform = A.Illumination(
...     mode='linear',
...     intensity_range=(0.05, 0.1),
...     effect_type='brighten',
...     angle_range=(30, 60)
... )
>>>
>>> # Create dramatic corner shadow
>>> transform = A.Illumination(
...     mode='corner',
...     intensity_range=(0.1, 0.2),
...     effect_type='darken'
... )
>>>
>>> # Add multiple spotlights
>>> transform1 = A.Illumination(
...     mode='gaussian',
...     intensity_range=(0.05, 0.15),
...     effect_type='brighten',
...     center_range=(0.2, 0.4),
...     sigma_range=(0.2, 0.3)
... )
>>> transform2 = A.Illumination(
...     mode='gaussian',
...     intensity_range=(0.05, 0.15),
...     effect_type='darken',
...     center_range=(0.6, 0.8),
...     sigma_range=(0.3, 0.5)
... )
>>> transforms = A.Compose([transform1, transform2])
Notes
  • The transform preserves image range and dtype
  • Effects are applied multiplicatively to preserve texture
  • Can be combined with other transforms for complex lighting scenarios
  • Useful for training models to be robust to lighting variations
References