analysis.ghost#

Ghost Analysis

This module enumerates the two-bounce ghost paths of a refractive optical system and ranks them by how bright they are at the image surface.

A two-bounce ghost is light that reflects off surface j, travels back toward the object, reflects again off an earlier surface i < j, and then continues forward to the image. Each path is traced with real rays as a SequencedOptic, so the base optic is never modified.

Kramer Harrison, 2026

Classes

GhostAnalysis(optic[, field, wavelength, ...])

Two-bounce ghost analysis: ghost focus, spot size and irradiance.

class GhostAnalysis(optic: Optic, field: tuple[float, float] = (0.0, 0.0), wavelength: str | float = 'primary', num_rings: int = 8, reflectance: float | dict[int, float] | None = None)[source]#

Two-bounce ghost analysis: ghost focus, spot size and irradiance.

Every pair of reflecting surfaces (i, j) with 0 < i < j gives one ghost path: forward to j, reflect, back to i, reflect, forward to the image. For each path, a hexapolar ray bundle at one field point is traced, and the following are computed at the image surface:

  • reflectance: R_i * R_j, the product of the two surface reflectances.

  • transmitted_fraction: the fraction of launched rays that reach the image surface along the ghost path (the rest are clipped by apertures or fail to intersect a surface).

  • energy_fraction: reflectance * transmitted_fraction, the share of the pupil flux carried by the ghost.

  • rms_radius: the RMS radius of the ghost spot about its centroid on the image surface, in lens units.

  • focus_shift: the axial distance from the image surface to the plane where the ghost spot is smallest, along the global z axis. Positive means past the image surface. It is the least-squares focus of the straight-line extension of the ghost rays, so it is valid on either side of the image surface.

  • irradiance: energy_fraction / (pi * r**2), the mean ghost irradiance on the image surface per unit pupil flux, in inverse lens units squared. r is rms_radius, floored at the Airy radius 1.22 * wavelength * FNO so that a ghost focused on the image does not give an infinite value. Use it to rank ghosts against each other.

Ghosts are sorted by irradiance, brightest first. A ghost with fewer than two rays at the image surface has NaN rms_radius and focus_shift, and zero irradiance.

By default, each surface’s reflectance is the uncoated Fresnel reflectance at normal incidence, ((n1 - n2) / (n1 + n2)) ** 2, from the refractive indices on either side of it. Coatings on the surfaces are not read. Pass reflectance to set the values yourself, for example to model anti-reflection coatings or a reflective sensor.

Parameters:
  • optic (Optic) – The optic to analyze. It must not contain reflective surfaces (mirrors).

  • field (tuple[float, float], optional) – The normalized field coordinates (Hx, Hy). Defaults to (0.0, 0.0).

  • wavelength (str or float, optional) – The wavelength in µm, or "primary". Defaults to "primary".

  • num_rings (int, optional) – The number of rings of the hexapolar ray bundle traced for each ghost. Defaults to 8.

  • reflectance (float or dict[int, float], optional) – The reflectance of the surfaces. A float applies to every surface between the object and the image surfaces. A dict maps surface indices to their reflectance, and only those surfaces are considered; it may include the image surface, to model light reflected by a sensor. If None, the uncoated Fresnel reflectance is used. Defaults to None.

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

  • field (tuple[float, float]) – The normalized field coordinates.

  • num_rings (int) – The number of rings of the ray bundle.

  • data (dict) – The ghost data. "surfaces" is a list of (i, j) tuples. The other keys are "reflectance", "transmitted_fraction", "energy_fraction", "rms_radius", "focus_shift" and "irradiance", each a 1D array with one entry per ghost, in the order of "surfaces".

Raises:

ValueError – If the optic contains a reflective surface, if a reflectance is outside [0, 1], or if a surface index in reflectance is out of range.

sequence(i: int, j: int) → SequencedOptic[source]#

Builds the ghost path that reflects off surface j, then i.

The returned sequence can be passed to other analyses, for example SpotDiagram, to inspect one ghost in detail. It is not registered on the optic.

Parameters:
  • i (int) – The index of the second reflecting surface.

  • j (int) – The index of the first reflecting surface, j > i.

Returns:

The ghost path.

Return type:

SequencedOptic

Raises:

ValueError – If the indices do not satisfy 0 < i < j < num_surfaces.

view(fig_to_plot_on: Figure | None = None, figsize: tuple[float, float] = (10, 4.5), *, max_ghosts: int = 20, show: bool = True) → tuple[Figure, np.ndarray][source]#

Displays the brightest ghosts: irradiance and focus shift.

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 (10, 4.5).

  • max_ghosts (int, optional) – The maximum number of ghosts shown, brightest first. Defaults to 20.

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

Returns:

The current figure and an array of its two axes.

Return type:

tuple