analysis.footprint#

Footprint Diagram Analysis

This module provides a footprint diagram analysis: where real rays land on any surface of an optical system, in that surface’s local coordinates.

Cr, 2026

Classes

FootprintData(x, y, reached, clipped)

Ray intersections with the analyzed surface, for one field and wavelength.

FootprintDiagram(optic, surface_index[, ...])

Footprint diagram: real ray intersections with any surface.
class FootprintData(x: BEArray, y: BEArray, reached: BEArray, clipped: BEArray)[source]#

Ray intersections with the analyzed surface, for one field and wavelength.

Variables:

  • x (BEArray) – Local x-coordinates of every traced ray on the surface.

  • y (BEArray) – Local y-coordinates of every traced ray on the surface.

  • reached (BEArray) – True for the rays that arrive at the surface, i.e. that have a nonzero intensity on the previous surface.

  • clipped (BEArray) – True for the rays that arrive at the surface but are blocked by it (zero intensity on the surface itself). A ray that misses the surface geometrically is also clipped, and its coordinates are NaN.

clipped: BEArray#
reached: BEArray#
x: BEArray#
y: BEArray#
class FootprintDiagram(optic: Optic, surface_index: int, fields: str | list = 'all', wavelengths: str | list = 'primary', num_rays: int = 12, distribution: DistributionType = 'hexapolar')[source]#

Footprint diagram: real ray intersections with any surface.

For each field and wavelength, rays are traced in the same way as for SpotDiagram, and their intersections with the chosen surface are converted to that surface’s local frame. The footprint shows how much of a surface each field uses, which helps to size clear apertures and to find where a beam is clipped.

Parameters:

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

  • surface_index (int) – Position of the surface in optic.surfaces. Negative values count from the end, so -1 is the image surface. The object surface (index 0) cannot be analyzed.

  • fields (str or list, optional) – The fields to trace: ‘all’ or a list of (Hx, Hy) tuples. Defaults to ‘all’.

  • wavelengths (str or list, optional) – The wavelengths to trace: ‘all’, ‘primary’, or a list of values in µm. Defaults to ‘primary’.

  • num_rays (int, optional) – The number of rays, or the number of rings for the hexapolar distribution. Defaults to 12.

  • distribution (str, optional) – The pupil distribution of the rays. Defaults to ‘hexapolar’.

Variables:

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

  • surface_index (int) – The non-negative index of the analyzed surface.

  • fields (list[FieldPoint]) – The fields being analyzed.

  • wavelengths (list[WavelengthPoint]) – The wavelengths being analyzed.

  • num_rays (int) – The number of rays or rings per trace.

  • distribution (str) – The pupil distribution of the rays.

  • data (list[list[FootprintData]]) – The footprint data, indexed by field and then by wavelength.

Raises:

ValueError – If surface_index is the object surface or is out of range.

extent() → tuple[float, float, float, float][source]#

Returns the bounding box of the rays that reach the surface.

Returns:

(xmin, xmax, ymin, ymax) in lens units, over all fields and wavelengths.

Return type:

tuple[float, float, float, float]

Raises:

ValueError – If no ray reaches the surface.

max_radius() → float[source]#

Returns the largest radial distance of the rays that reach the surface.

Returns:

The largest hypot(x, y) in lens units, over all fields and wavelengths.

Return type:

float

Raises:

ValueError – If no ray reaches the surface.

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

Displays the footprint diagram.

Rays that pass the surface are drawn in one color per field. Rays that reach the surface but are blocked by it are drawn as grey crosses. The boundary of the surface’s physical aperture is drawn when it has one, otherwise its semi-aperture circle when that is set.

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

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

Returns:

The current figure and its axes.

Return type:

tuple