analysis.relative_illumination#

Relative Illumination Analysis

This module provides a relative illumination analysis for optical systems, based on M. Rimmer, “Relative illumination calculations”, Proc. SPIE 655, 99 (1986).

Kramer Harrison, 2026

Classes

RelativeIllumination(optic[, wavelengths, ...])

Relative illumination: image irradiance versus field, normalized.

class RelativeIllumination(optic: Optic, wavelengths: str | list = 'primary', num_fields: int = 32, num_pupil: int = 64)[source]#

Relative illumination: image irradiance versus field, normalized.

For a uniform, planar, Lambertian object, radiance is conserved through the system apart from transmission losses. The irradiance at an image point is then proportional to the projected solid angle of the exit pupil seen from that point, weighted by transmission. In image space, this projected solid angle is the area that the rays cover in direction-cosine space (L, M), measured in the image surface’s local frame (Rimmer, 1986). Vignetting, pupil aberrations, telecentricity and changes of F-number across the field all change that area, so no separate cos⁴ term is applied.

For each field point Hy in linspace(0, 1, num_fields) (Hx = 0), rays are traced on a polar grid of normalized pupil coordinates that covers the unit disk. Each grid cell maps to a quadrilateral in (L, M). Its signed area (shoelace formula) is weighted by the mean intensity of its four corner rays, with vignetted rays counted as zero intensity. This captures coatings, apodization and absorption, and gives a cell that is partially vignetted a proportional share of its area. The sum over cells is the unnormalized irradiance. Each wavelength’s curve is normalized by its maximum over the field.

The grid is polar, not a square grid masked to the unit disk, because the area of a masked square grid has a staircase boundary whose error falls only as 1 / num_pupil. The polar grid follows the pupil circle, and the remaining chord error is divided out, so its error falls as 1 / num_pupil**2. The integrated area does not depend on how the pupil disk is parameterized, so both grids converge to the same value.

If the signed cell areas of one field change sign, rays from different pupil regions share an image-space direction (a caustic in direction space), and the area no longer measures the irradiance. A RuntimeWarning names those fields, and data["reliable"] marks them False.

The pupil grid follows the optic’s ray aiming. With paraxial aiming, the off-axis beams fill the paraxial entrance pupil, which can under- or overfill the real stop when pupil aberrations are large. Iterative or robust aiming (optic.ray_tracer.set_aiming) fills the real stop and can change the result by several percent or more for such lenses.

The method assumes that the image surface is a good conjugate of the object: rays from one field point should land close together on it. Strong defocus, field curvature or astigmatism at the image surface make the result differ from the true irradiance, because the cone of rays from one field point is then not the cone of rays arriving at one image point.

Only planar image surfaces are supported. A tilted planar image surface is handled through its local frame.

Parameters:
  • optic (Optic) – The optic object to analyze.

  • wavelengths (str | list, optional) – The wavelengths to analyze. Defaults to ‘primary’.

  • num_fields (int, optional) – The number of field points from the axis to the full field. Defaults to 32.

  • num_pupil (int, optional) – The pupil sampling, the number of rays across the pupil diameter. As for a square grid masked to the unit disk, about num_pupil**2 * pi / 4 rays are traced per field point. Defaults to 64. Must be at least 5.

Variables:
  • optic (Optic) – The optic object being analyzed.

  • wavelengths (list) – The wavelengths being analyzed.

  • num_fields (int) – The number of field points.

  • num_pupil (int) – The pupil sampling.

  • data (dict) – "Hy", the normalized field coordinates; "relative_illumination", one array per wavelength (same order as wavelengths) with values in [0, 1]; "irradiance", the unnormalized values (projected solid angle in sr, weighted by transmission); and "reliable", one boolean array per wavelength, False where a caustic was detected.

Raises:
view(fig_to_plot_on: Figure | None = None, figsize: tuple[float, float] = (8, 5.5), *, show: bool = True) → tuple[Figure, Axes][source]#

Displays a plot of the relative illumination versus field.

Fields flagged as unreliable (caustic detected) are marked with an x.

Parameters:
  • fig_to_plot_on (plt.Figure, optional) – The figure to plot on. If None, a new figure will be created. Defaults to None.

  • figsize (tuple[float, float], optional) – The size of the figure. Defaults to (8, 5.5).

  • show (bool) – If True (default), calls plt.show(). Set False for headless use.

Returns:

The current figure and its axes.

Return type:

tuple