Source code for 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
"""

from __future__ import annotations

import math
import warnings
from typing import TYPE_CHECKING

import numpy as np

import optiland.backend as be
from optiland.geometries import Plane

from ._plotting import finalize_figure, prepare_axes
from .base import BaseAnalysis

if TYPE_CHECKING:
    from matplotlib.axes import Axes
    from matplotlib.figure import Figure

    from optiland.optic import Optic


[docs] class RelativeIllumination(BaseAnalysis): """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. Args: 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. Attributes: 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: NotImplementedError: If the image surface is not planar. ValueError: If ``num_fields`` is less than 1 or ``num_pupil`` is less than 5. """ def __init__( self, optic: Optic, wavelengths: str | list = "primary", num_fields: int = 32, num_pupil: int = 64, ): if num_fields < 1: raise ValueError(f"num_fields must be at least 1, got {num_fields}.") if num_pupil < 5: raise ValueError(f"num_pupil must be at least 5, got {num_pupil}.") if not isinstance(optic.image_surface.geometry, Plane): raise NotImplementedError( "RelativeIllumination supports planar image surfaces only." ) self.num_fields = num_fields self.num_pupil = num_pupil super().__init__(optic, wavelengths)
[docs] def view( self, fig_to_plot_on: Figure | None = None, figsize: tuple[float, float] = (8, 5.5), *, show: bool = True, ) -> tuple[Figure, Axes]: """Displays a plot of the relative illumination versus field. Fields flagged as unreliable (caustic detected) are marked with an ``x``. Args: 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: tuple: The current figure and its axes. """ current_fig, ax, is_gui_embedding = prepare_axes(fig_to_plot_on, figsize) field_np = be.to_numpy(self.data["Hy"]) * self.optic.fields.max_field for k, wp in enumerate(self.wavelengths): ri = be.to_numpy(self.data["relative_illumination"][k]) reliable = be.to_numpy(self.data["reliable"][k]).astype(bool) ax.plot(field_np, ri, f"C{k}", zorder=10, label=f"{wp.value:.4f} µm") if not reliable.all(): ax.plot( field_np[~reliable], ri[~reliable], f"C{k}x", zorder=11, label=f"{wp.value:.4f} µm, caustic", ) ax.set_xlabel("Field") ax.set_ylabel("Relative Illumination") ax.set_xlim([0, self.optic.fields.max_field]) ax.set_ylim([0, 1.05]) ax.set_title("Relative Illumination") ax.legend(bbox_to_anchor=(1.05, 0.5), loc="center left") ax.grid(True) current_fig.tight_layout() finalize_figure(current_fig, is_gui_embedding, show) return current_fig, ax
def _generate_data(self) -> dict: """Computes the relative illumination for each wavelength. Returns: dict: ``"Hy"``, ``"relative_illumination"``, ``"irradiance"`` and ``"reliable"``, as described in the class docstring. """ Hy = be.linspace(0, 1, self.num_fields) relative, irradiance, reliable = [], [], [] for wp in self.wavelengths: e, ok = self._irradiance(Hy, wp.value) peak = be.max(e) has_light = float(be.to_numpy(peak)) > 0 relative.append(e / peak if has_light else be.zeros_like(e)) irradiance.append(e) reliable.append(ok) _warn_caustics(Hy, ok, wp.value) return { "Hy": Hy, "relative_illumination": relative, "irradiance": irradiance, "reliable": reliable, } def _irradiance(self, Hy, wavelength: float): """Weighted direction-cosine area for every field point. Args: Hy (be.ndarray): Normalized y field coordinates. wavelength (float): Wavelength in µm. Returns: tuple: ``(irradiance, reliable)``, one value per field point. """ grid = _PolarPupilGrid(self.num_pupil) num_fields = Hy.shape[0] num_rays = grid.Px.shape[0] Hy_all = be.repeat(Hy, num_rays) rays = self.optic.trace_generic( be.zeros_like(Hy_all), Hy_all, be.tile(grid.Px, num_fields), be.tile(grid.Py, num_fields), wavelength, ) # The returned rays are a fresh object, so localizing them leaves the # recorded per-surface data in the global frame. self.optic.image_surface.geometry.localize(rays) shape = (num_fields, num_rays) L = grid.cells(be.reshape(rays.L, shape)) M = grid.cells(be.reshape(rays.M, shape)) intensity = grid.cells(be.reshape(be.where(rays.i > 0, rays.i, 0.0), shape)) # Corners in order around each cell; the diagonal form of the # shoelace formula gives the signed area of the quadrilateral. L0, L1, L2, L3 = L M0, M1, M2, M3 = M area = 0.5 * ((L2 - L0) * (M3 - M1) - (L3 - L1) * (M2 - M0)) weight = 0.25 * (intensity[0] + intensity[1] + intensity[2] + intensity[3]) finite = be.isfinite(area) area = be.reshape(be.where(finite, area, 0.0), (num_fields, -1)) weight = be.reshape(be.where(finite, weight, 0.0), (num_fields, -1)) irradiance = be.abs(be.sum(area * weight, axis=1)) * grid.chord_correction return irradiance, _no_sign_change(area, weight)
class _PolarPupilGrid: """Polar grid of normalized pupil coordinates over the unit disk. The grid has ``num_rho`` radial and ``num_theta`` angular intervals. Each point is traced once: the pupil center, then ``num_theta`` points on each ring. :meth:`cells` rebuilds the closed ``(num_rho + 1) x (num_theta + 1)`` grid from per-ray values and returns the corners of every cell. Args: num_pupil (int): Rays across the pupil diameter. The grid uses ``num_pupil // 2`` rings of ``round(pi * num_pupil / 2)`` points, about ``num_pupil**2 * pi / 4`` rays in all. Attributes: Px (be.ndarray): Normalized pupil x coordinates of the traced rays. Py (be.ndarray): Normalized pupil y coordinates of the traced rays. num_rho (int): Number of radial intervals. num_theta (int): Number of angular intervals. chord_correction (float): ``d / sin(d)`` for the angular step ``d``. The outer cells replace the pupil circle by chords, which loses the factor ``sin(d) / d`` for a locally linear pupil-to-direction map. """ def __init__(self, num_pupil: int): self.num_rho = max(2, num_pupil // 2) self.num_theta = max(8, round(math.pi * num_pupil / 2)) step = 2 * math.pi / self.num_theta self.chord_correction = step / math.sin(step) rho = be.linspace(0, 1, self.num_rho + 1)[1:] theta = be.arange(self.num_theta) * step theta, rho = be.meshgrid(theta, rho) # Clip rounding overshoot so the coordinates stay within [-1, 1]. zero = be.zeros(1) self.Px = be.concatenate([zero, be.ravel(be.clip(rho * be.cos(theta), -1, 1))]) self.Py = be.concatenate([zero, be.ravel(be.clip(rho * be.sin(theta), -1, 1))]) def cells(self, values): """Corners of every grid cell, in order around the cell. Args: values (be.ndarray): Per-ray values of shape ``(fields, rays)``, in the order of ``Px`` and ``Py``. Returns: tuple: Four arrays of shape ``(fields, num_rho, num_theta)`` for the corners ``(i, j)``, ``(i + 1, j)``, ``(i + 1, j + 1)`` and ``(i, j + 1)``, with ``i`` the ring and ``j`` the angle index. """ num_fields = values.shape[0] center = values[:, :1, None] * be.ones((1, 1, self.num_theta)) rings = be.reshape(values[:, 1:], (num_fields, self.num_rho, self.num_theta)) grid = be.concatenate([center, rings], axis=1) # Repeat the first angle at the end to close each ring. grid = be.concatenate([grid, grid[:, :, :1]], axis=2) return ( grid[:, :-1, :-1], grid[:, 1:, :-1], grid[:, 1:, 1:], grid[:, :-1, 1:], ) def _no_sign_change(area, weight, rel_tol: float = 1e-6): """Whether the signed cell areas of each field share one sign. Cells that carry no light, and cells far smaller than the largest cell of their field (such as the degenerate cells at the pupil center), are ignored. Args: area (be.ndarray): Signed cell areas, shape ``(fields, cells)``. weight (be.ndarray): Cell weights, same shape. rel_tol (float, optional): Relative area below which a cell is ignored. Defaults to 1e-6. Returns: be.ndarray: One boolean per field, ``True`` without a sign change. """ lit = weight > 0 largest = be.nanmax(be.where(lit, be.abs(area), 0.0), axis=1) counted = lit & (be.abs(area) > rel_tol * largest[:, None]) positive = be.sum(be.where(counted & (area > 0), 1.0, 0.0), axis=1) negative = be.sum(be.where(counted & (area < 0), 1.0, 0.0), axis=1) return (positive == 0) | (negative == 0) def _warn_caustics(Hy, reliable, wavelength: float) -> None: """Emits a ``RuntimeWarning`` naming the fields with a caustic. Args: Hy (be.ndarray): Normalized y field coordinates. reliable (be.ndarray): One boolean per field. wavelength (float): Wavelength in µm. """ flags = be.to_numpy(reliable).astype(bool) if flags.all(): return bad = np.round(be.to_numpy(Hy)[~flags], 4).tolist() warnings.warn( f"RelativeIllumination: the direction-cosine mapping folds over " f"(caustic) at {wavelength:.4f} µm for Hy = {bad}. Relative " f"illumination is unreliable at these fields.", RuntimeWarning, stacklevel=4, )