Plotting Guide

Every LensBench figure is made of three separate parts:

	What it is	Where it lives
Data	Plain data computed by the evaluator (spot coordinates, ray fans, MTF curves…)	kernel/, obtained through Evaluator
View spec	Sampling and display options, written as view statements in the .lens file	model/views.py
Style	Tokens for color, line style, font and font size	style.py, shared by interactive and publication figures

So the same figure looks the same, in content and colors, whether you view it in the GUI, export it with lb plot, or review it in the gallery; and if the optical engine is replaced, the plotting layer does not need to change.

Figure kinds

Kind (kind)	Content	Zemax equivalent
layout	2D layout (YZ section); colored by field (color=wave colors by wavelength: a set of rays is traced for each wavelength, the primary wavelength is drawn on top, and colored fringes show where dispersion separates them), stop blades, a slanted hatch on the back of mirrors, a scale bar; for multi-configuration designs configs=all stacks the configurations vertically (same z scale)	2D Layout (Color Rays By Field / Wave)
spot	Spot diagram; equal-scale boxes, Airy disk circle, scale bar, with the polychromatic RMS / GEO below the box	Standard Spot Diagram
spot_density	Spot density map: pseudo-color (sequential) energy density of hundreds of thousands of ray landing points, one cell per field, the same box, with the Airy circle overlaid; rays= bins= ref= box=, scale=sqrt/linear/log, norm=field/all, airy=	Geometric Image Analysis (point source)
fan	Ray aberration fan; all subplots share the same vertical axis, labeled "max scale"	Ray Aberration
opd_fan	Wavefront aberration fan (in waves)	OPD Fan
mtf	Polychromatic FFT MTF (the complex OTFs of the wavelengths are combined by weight); tangential solid, sagittal dashed, diffraction limit dotted; spec points are colored pass / fail; max_freq= sampling=auto/integer (see "FFT sampling" below)	FFT MTF
mtf_vs_field	MTF versus field: one color per frequency, tangential solid, sagittal dashed; f1= f2= f3= (e.g. 30/mm; if none is given = 1/16, 1/8 and 1/4 of the cutoff frequency, rounded) num= sampling=auto/integer	FFT MTF vs. Field
through_focus_mtf	Through-focus MTF: MTF of each field at one frequency versus image-plane defocus (field colors, tangential solid, sagittal dashed), with a triangle at the top marking the best focus; freq= step= steps=	Through Focus MTF
fieldcurv	Field curvature (T / S) and distortion (F-tanθ)	Field Curvature and Distortion
grid_distortion	Grid distortion: ideal grid as gray dashed lines, actual grid as dark solid lines, grid points colored by distortion (diverging colors: barrel blue, pincushion red); n= wave=, exaggerate= (deviation magnification)	Grid Distortion
image_sim	Image simulation: ideal image and simulated image side by side; each wavelength is convolved with its own PSF and the results are composed in wavelength colors; mode=patch/full pattern=star/grid/bars/checker field= size= pixels= sampling= grid=, show=both/sim	Image Simulation
longitudinal	Longitudinal aberration: distance of the axial tangential ray's intersection with the optical axis from the image plane vs. pupil	Longitudinal Aberration
lateral_color	Lateral color: chief-ray image height of each wavelength relative to the primary wavelength, with ±Airy radius reference lines	Lateral Color
focal_shift	Chromatic focal shift: shift of the paraxial focus with wavelength, with the diffraction-limited depth-of-focus band 4λF#²	Chromatic Focal Shift
through_focus	Through-focus spot diagram: rows = fields, columns = defocus positions before and after the image plane	Through Focus Spot Diagram
seidel	Per-surface Seidel contribution bar chart: seven items per surface, with the sum as a separate group; unit=waves shows wavefront coefficients	Seidel Diagram
footprint	Footprint diagram: landing points of each field's beam on a surface (in the surface's local coordinates) plus the clear semi-aperture; surface= selects the surface, surface=all shows all surfaces together	Footprint Diagram
wavefront	Wavefront map: pseudo-color OPD over the pupil (diverging colors, negative blue, positive red, zero neutral gray, symmetric color bar) plus an interferogram; field= wave= remove=none/piston/tilt, show=both/map/fringes	Wavefront Map / Interferogram
psf	FFT PSF: point spread function on the image plane (sequential color, single blue hue, light to dark) plus x / y cross sections through the peak, overlaid with the diffraction-limited Airy cross section at the same working F-number; field= wave= sampling=auto/integer span=, scale=linear/log	FFT PSF / FFT PSF Cross Section
glass_map	Glass map (nd–vd): the horizontal axis is the Abbe number, reversed; catalog glasses are small dots (colored by manufacturer when there are several), the design's glasses are large dots labeled with the glass name (labels avoid each other automatically); model glasses are drawn as diamonds with a dashed line to the nearest catalog glass (circled, i.e. the one glass-substitute would swap in); catalogs=design/all, labels=on/off	Glass Map
sag	Sag table: top = sag and the best-fit sphere (through the vertex and the edge), bottom = deviation from the BFS (µm); both plots share the horizontal axis; surface= (default: the first aspheric surface) num=	Sag Table
field_map	Full-field image-quality map: polychromatic RMS spot size / wavefront over the 2D field (sequential-color heat map: light = good, dark = bad), with contour lines labeled with values, the defined fields (white dots) and the worst location; data= ref= area=circle/sensor n= rings= arms=	Full-Field Aberration / RMS Field Map
rms_field	RMS versus field: thin line per wavelength (wavelength color), thick polychromatic line, diffraction limit dotted; data=spot/wavefront ref=centroid/chief num= rings= arms=	RMS vs. Field
zernike	Zernike coefficient bar chart: one bar per term, positive and negative in different colors, terms numbered along the horizontal axis, and the largest few terms (name and value) written in the info block; field= wave= kind=fringe/standard terms= grid=	Zernike Fringe / Standard Coefficients
huygens_mtf	Huygens MTF: drawn like mtf, computed from the Huygens PSF on the image plane (differs from the FFT MTF for a tilted / curved image plane or oblique chief-ray incidence); max_freq= sampling= (pupil, default 32)	Huygens MTF
huygens_psf	Huygens PSF: drawn like psf, with pixels on the actual image plane (the stretching from a tilted / curved image plane or oblique chief-ray incidence is included); field= wave= sampling= (pupil, default 32) pixels= (image-plane grid, default 128) delta= (pixel pitch, default automatic), scale=linear/log	Huygens PSF / Huygens PSF Cross Section
encircled_energy	Encircled energy: one curve per field plus a dotted diffraction limit, 50 / 80 % reference lines, and a dot marking the 80 % energy radius; method=diffraction/geometric ref=chief/centroid wave= (0 = all, by weight) sampling= radius=, marks=	Diffraction / Geometric Encircled Energy
relative_illumination	Relative illumination: illumination / on-axis illumination versus field (solid), the fraction of the pupil transmitted (dashed, geometric vignetting), and a cos⁴θ reference (dotted); num= rays= wave=, cos4= vignetting=	Relative Illumination

Tolerance plots are not part of plot; they are produced by lb tolerance --out tol.png (sensitivity is a tornado chart, Monte Carlo is a histogram plus cumulative yield), with the same figure frame and evidence id as above.

Visual conventions: field colors run blue, green, red… (12 colors); wavelength colors are assigned by λ from short to long (F/d/C are blue/green/red, a single wavelength uses green), independent of input order; layout and footprint are colored by field, while spot / ray fan / field curvature are colored by wavelength; tangential is solid and sagittal is dashed; units are written into the labels, and values carry 4 significant digits. The seven Seidel terms use a separate fixed color sequence (style.SEIDEL_COLORS, in which adjacent terms remain distinguishable under color blindness), with gaps between bars.

Figure frame and info block

Every publication figure has a title and an info block:

• Left column: lens name, LensBench version and engine build number (such as "引擎 r7b3cab6f", i.e. "Engine r7b3cab6f"), date; the full engine identifier is recorded only in the evidence register;
• Middle column: field, wavelength, and information specific to this figure (scale bar, box size, Airy radius, max scale, spec verdict…);
• Right column: the evidence id and the model hash.

Evidence id = model hash + engine identifier + analysis kind + sampling parameters. The model hash looks at optics only: the name, comments, formatting, var / op / let / default / view / spec / pack / tol / comp do not enter it; glass is taken as its resolved refractive-index data (so switching the AGF file is detected even when the text is unchanged). Therefore:

• Renaming, adding a comment, or reformatting → the evidence does not change;
• Changing the rings of the spot diagram → only the spot diagram's evidence changes;
• Changing display options such as box size or turning on surface numbers → the evidence does not change;
• Upgrading or replacing the engine module, or revising the analysis conventions (when upgrading LensBench) → all evidence changes (numbers from old and new conventions are never attached to the same id).

Type evidence <id> in the command line at the bottom of the desktop app (or on the "终端" (Terminal) tab on the right), or have the AI call the evidence tool, to look up the command, arguments, text hash and engine of that time (the evidence register lives in the session; the system command-line lb does not have this command).

View spec: the view statement

view spot rings=8 ref=centroid box=120um
view layout numbers=on fold=on first=3 last=7
view mtf max_freq=100/mm
view through_focus step=0.02mm steps=7

• The options of each figure kind are described in the view section of .lens 语法参考; [sampling] options change the data (and the evidence), [display] options change only how it is drawn.
• Dimensioned values must carry units (120um, 0.02mm, 100/mm); omitting them raises E-UNIT-REQUIRED, and no default unit is assumed.
• Command line: lb view-set my.lens spot rings=8 box=100um (minimal edit; the same figure kind is merged into one line); GUI: "⚙ 本图选项" (⚙ Options for this figure) on the floating navigation bar at the bottom of the view.
• lb plot --view "…" can override temporarily: write only the options, not the figure kind, e.g. --view "rings=8 box=100um".

Layout specifics: fold=on compresses air gaps longer than half the total length of the rest (a break symbol is drawn, and the info block states the original length); first / last draw only a range of surfaces (Zemax's First/Last Surface); rays that are blocked or cannot be traced further are drawn up to the surface that blocks them.

Specs and acceptance: the spec statement and lb verify

spec efl target=50mm tol=1%
spec fno max=2.0
spec ttl max=40mm
spec cra max=13deg
spec mtf freq=50/mm field=0.7 dir=T min=0.3
spec spot_rms max=10um
spec distortion max=2%
spec custom expr="max(RSCE(ring=3, Hy=0:0.25:1))" max=0.01 label="Full-field RMS (mm)"

• A spec is acceptance, an op is an optimization target; the two are kept separate, and a spec stores only absolute target values.
• First-order specs (efl / fno / bfl / ttl / imh / cra) are enforced first; an MTF spec can be written per relative field (0–1 or all) and direction (T / S / both), and spot RMS per field; distortion takes the absolute value by default, write signed for the signed value. The kinds and the corresponding Zemax operands are in the reference documentation.
• custom: custom acceptance, where expr= is an expression (MATLAB-style; syntax in optimization.md, "Expressions"). It may only call operands and functions and cannot reference op lines or let (acceptance and optimization targets are kept separate and self-contained); the limits carry no units and use the operand's own units (length in mm, wavefront in λ, angle in °, distortion in %); when the result is a vector, every element must pass and the conclusion points out the worst one; label= is the display name. The sampling is simply the operand arguments written in the expression.
• lb verify independently recomputes with fixed canonical sampling (it does not read view and does not use the numbers the optimizer reports), and gives for each spec the value, limit, pass / fail and source (which analysis, what sampling, and which command can recompute it on its own; the canonical sampling always equals that command's default sampling); with --strict, any failed or undecidable spec makes it fail (usable as a CI gate). Evidence = model hash + spec hash: changing a spec only invalidates the verdict and does not trigger recomputation of analyses.
• At the end comes manufacturability: mounting violations (interpenetration, negative edge thickness) and a warning for lenses with edge thickness below 0.5 mm (manufacturing in the structured result); these are warnings only and do not count as failures. The manufacturability table of the report pack and its conclusions use the same check.
• Multi-configuration designs are verified per configuration: spec efl target=70mm tol=1% config=2 is checked only on configuration 2, spec ttl max=60mm config=all is checked on every configuration, and without config= the check is on the current configuration (as before; lb verify --config k switches the current configuration); a nonexistent configuration number raises E-SPEC-CONFIG. Each (spec, configuration) pair is judged once with that configuration's evaluator (fields / wavelengths follow the configuration), the table gains a "configuration" column, and the end lists each configuration's verdict and evidence id; there is one piece of evidence per configuration, with evidence key = hash of the specs verified on that configuration + the configuration number, so changing another configuration's spec does not make it stale; manufacturability is checked once per configuration. Sign-off records each configuration's conclusion and evidence id, the report pack's acceptance table carries configuration and evidence columns and its conclusions are written per configuration, and the report check verifies numbers against each configuration's evidence.
• When plotting, the specs relevant to a figure are drawn on it, and the color is verify's verdict: MTF triangles, spot RMS, distortion limit lines, lateral color limit lines, and the chromatic focal shift range. For multi-configuration designs, only specs verified on the currently displayed configuration are drawn (a config=k spec appears only on configuration k's figure).
• The "验收" (Acceptance) tab of the GUI right-hand panel (Ctrl+Shift+V) lists the per-spec results and manufacturability, lets you add / delete specs, and "来源" (Source) switches to the analysis page that computed the number.

Export

lb plot my.lens spot --out spot.pdf              # PDF: vector, embedded fonts (TrueType / Type 42)
lb plot my.lens layout --out layout.svg          # SVG: text converted to paths by default, identical on any machine
lb plot my.lens layout --out l.svg --svg-text text   # SVG keeps text: editable in Word (requires the font)
lb plot my.lens mtf --dpi 600 --lang en          # PNG (default 300 dpi), English figure
lb plot my.lens fan --full-table --json          # attach the full data table page / raw data

• The format is determined by the file extension; the figure language follows the interface by default, and --lang switches it independently.
• Without --out the file is written to <lens directory>/reports/<name>_<kind>.png; for multi-configuration designs add --config k to plot configuration k (the configuration number enters the evidence key).
• Every figure has a data table page (the same data as a table): the command's text output includes a summary, --full-table includes everything, and --json gives the raw arrays; what MCP returns to the AI is this data, and the PNG is returned to the AI as well.
• GUI: "⇪ 导出" (⇪ Export, Ctrl+E) on the floating navigation bar at the bottom of the view goes through the same pipeline; "⧉ 复制图" (⧉ Copy figure, Ctrl+Shift+C) puts both the bitmap and the SVG on the clipboard (Word 2016 and later can paste SVG directly); "▤ 数字页" (▤ Data table) switches to a table of the same data, and Ctrl+C copies it.

Fonts: Noto Sans SC is bundled (OFL 1.1, GB2312 + symbol subset) and missing glyphs fall back to system fonts, so the same figure comes out identically on different machines.

Gallery

lb gallery                     # 7 reference designs × 27 figure kinds (except the OPD fan) → reports/gallery/index.html
lb gallery my.lens --kinds spot,mtf --out reports/mine

Reference designs: Cooke triplet, double Gauss, Petzval, wide angle (100°), telephoto, folded mirror, parabolic mirror (all can be opened from the desktop app's home page › reference designs). The gallery lays out every figure on one page, which suits reviewing all the figures of a design in one sitting; key points for reading the figures are listed at the top of the page.

Notes on conventions

• Field curvature / distortion are computed in image-plane local coordinates: by intersecting neighboring-ray pairs (the same method as Zemax), and distortion is referenced to the scaling of the paraxial actual chief ray on the actual image plane, calibrated separately for each wavelength. When the image plane is not at the paraxial focus (for example the Cooke sample's image plane is 0.23 mm in front of the focus), you cannot compare against EFFL·tanθ. Folded systems give exactly the same results as the unfolded coaxial system (guaranteed by tests).
• Focus shift and longitudinal aberration are taken positive along the propagation direction (the sign convention for reflective image space remains to be verified against Zemax).
• Spot diagram coordinates are in image-plane local coordinates, relative to the reference point (chief ray or centroid); Airy radius = 1.22·λ·F#, where F# is the working F-number computed from the actual axial marginal ray.
• Spot density map: a spot diagram with a few thousand scattered points shows only the outline, not where the energy concentrates; the spot density map uses rays × rays stratified jittered sampling over the pupil (one random point in each square, with a fixed seed so results are reproducible bit for bit; uniform by area, without the moiré a regular grid produces at caustics), default 301 × 301 (about 71,000 rays inside the circle) × each wavelength, wavelengths combined by weight; the landing points (image-plane local coordinates, relative to the reference point) are binned onto a bins × bins grid with cloud-in-cell (bilinear) assignment, and the density unit is "fraction of this field's energy reaching the image plane / µm²". The box by default encloses 99.5 % of each field's energy (× 2.16, rounded). The default is a square-root scale (bright areas do not saturate and faint blur is still visible); scale=log shows three orders of magnitude; norm=all shares one scale across fields, to compare which field has more concentrated energy. A pure-defocus disk agrees with the analytic values (density inside the disk 1/(πR²) to within 1 %, RMS = R/√2; tested). RMS convention: the RMS of the spot density map is the converged value of an area-uniform integral over the pupil (within 0.3 % of an independent Gauss quadrature; tested); the RMS of the spot diagram is the equal-weight average over the hexagonally sampled rays (consistent with the points drawn in the spot diagram), and with few rings the two differ by several to a dozen percent (Cooke 20°: 13.04 vs 11.55 µm).
• Lateral color = chief-ray image height of each wavelength − chief-ray image height of the primary wavelength; "longest − shortest" is Zemax's LACL convention (w2 − w1, with w1 defaulting to the shortest and w2 to the longest).
• Chromatic focal shift = shift of the paraxial focus (the intersection of the axial paraxial marginal ray with the optical axis) with wavelength; C minus F equals the paraxial AXCL (same as Zemax's w2 − w1; independently verified by tests).
• Seidel coefficients are computed in-house with Welford's formulas (the same data as lb seidel); a positive lens has undercorrected spherical aberration S_I > 0; per-surface wavefront coefficients W040 = S_I/8λ, W131 = S_II/2λ, W222 = S_III/2λ, W220P = S_IV/4λ, W311 = S_V/2λ, W020 = C_I/2λ, W111 = C_II/λ. A coordinate break does not take up a group; when a decentered / tilted surface with power goes beyond the first-order model, the whole figure is unavailable (with an explanation).
• The footprint is in the surface's local coordinates (compared in the same coordinates as the surface's clear semi-aperture; the cross-section of a circular beam on a 45° fold mirror is stretched by √2), primary wavelength, hexagonal sampling. The beam outline is the true boundary rays, not a fitted circle: at each pupil azimuth, the largest pupil radius that reaches this surface is taken (if the pupil-edge ray reaches it, that is used; if it is blocked by an earlier surface, the blocked boundary is found by bisection along the radius), and vignetting factors (VDY / VCY…) are reflected in the shape as well (VCY=0.3 → the beam is about 70 % as tall; tested). Rays blocked before this surface are not drawn; rays that reach this surface but fall outside a fixed aperture (semi=) are still drawn and counted in "rays outside the aperture". Note: as in Zemax, the clear semi-aperture (semi) does not block light and is used only for comparison; the default is surface 1; coordinate breaks and an object surface at infinity have no footprint.
• Wavefront map: OPD on a 65 × 65 grid over the pupil (grid=; for odd values the center and ±1 fall exactly on grid points), in waves, relative to the chief-ray reference sphere — the same convention as the OPD fan and RWCE / RWCH, with 0 at the chief ray. remove=piston subtracts the mean, remove=tilt additionally subtracts the least-squares plane (to see the aberration shape with tilt removed); RMS is the root mean square after removing the mean (area-uniform weighting), P-V is the peak-to-valley value, both computed on the map after removal. Blocked grid points (vignetting, obscuration, rays that miss the surface) are left blank. The interferogram brightness is ½(1 + cos 2πW), and one fringe = one wavelength. A pure-defocus parabolic mirror agrees with the analytic formula point by point (difference < 5e-4 λ; tested).
• PSF: FFT PSF, normalized to the diffraction-limited peak (the peak of an unaberrated circular pupil at the same working F-number = 1), so the peak in the figure is the Strehl ratio. wave=0 (default) combines all wavelengths by weight (polychromatic, Zemax's default): the PSF of each wavelength is shifted to the primary wavelength's pixel grid by the chief-ray lateral color (cubic interpolation) and weighted by w /(λF#)² (with unit energy, the diffraction-limited peak ∝ 1/(λF#)²), the peak is the polychromatic Strehl ratio, and the diffraction-limited cross section is weighted in the same way; wave=k looks at a single wavelength. Polychromatic is centered on the primary wavelength's chief-ray image point, monochromatic on that wavelength's chief-ray image point (origin), image-plane local coordinates, µm. sampling= is the sampling (default automatic, see the next item); it fixes the pupil sampling and the FFT grid, and the info block prints the sampling actually used, the pupil sampling and the FFT grid, with pixel = λ·F# / Q (Q = FFT grid / (pupil sampling − 1)). The window is automatic by default: radius enclosing 95 % of the energy × 1.3, at least 3 Airy radii; span=20um specifies the half-width. The cross sections on the right pass through the peak (not necessarily through the origin), and the dotted line is the diffraction-limited Airy cross section [2 J1(v)/v]², v = π r /(λ F#), sampled on the same pixel grid; with scale=log, the pseudo-color shows four orders of magnitude and the cross section five (side lobes and scatter are obvious at a glance). A perfect parabolic mirror agrees with the Airy formula point by point (difference < 5e-3), the Strehl ratio of pure defocus agrees with [sin(πW₀₂₀)/(πW₀₂₀)]² (difference < 1 %), and the three-wavelength polychromatic PSF of a dispersion-free mirror agrees with the weighted Airy formula (difference < 3e-3); all tested. Note: wave=0 means "all wavelengths" for encircled energy, PSF and Huygens PSF, but "primary wavelength" for the wavefront map, Zernike, relative illumination and grid distortion (these are inherently monochromatic analyses, as in Zemax).
• Huygens PSF: from each sample point on the exit-pupil reference sphere (a uniform sampling × sampling pupil grid), a Huygens–Fresnel sum is evaluated at every pixel on the image plane: U(P) = Σ a · e^{ik(nR − W)} / R · ½(1 + cos θ), where W is that point's optical path difference relative to the reference sphere, and the obliquity factor is computed from the reference-sphere normal. The difference from the FFT PSF: the FFT PSF is computed on the plane perpendicular to the chief ray, whereas the Huygens PSF's pixels lie on the actual image plane — when the image plane is tilted or curved, or the chief ray is oblique at large fields, the PSF is elongated along the tilt direction by about 1/cos θ, and the Strehl ratio and energy distribution change accordingly; all wavelengths share the same physical grid (no interpolated shifting). Normalization: each wavelength is divided by the peak at the reference-sphere center for "the same pupil, zero aberration", and polychromatic is combined by weight after normalizing by pupil power, so the peak is the polychromatic Strehl ratio (the same convention as the FFT PSF). The grid is 129 × 129 by default, centered on the primary wavelength's chief-ray image point, with automatic pixel pitch (the window encloses the 95 % radius of the geometric blur × 1.3 plus one Airy radius, at least 3 Airy radii); delta=0.2um specifies it. Run time ∝ number of pixels × number of pupil samples. Checks: the first dark ring of an ideal lens is within 0.5 % of 1.22 λF#; with the image plane tilted 30°, the y / x dark-ring ratio is within 0.2 % of 1/cos 30° (the FFT PSF remains circular); at normal incidence the Strehl ratio is within 1.5 % of the FFT PSF; the coma direction agrees with the centroid of the geometric spot; all tested.
• Glass map: for every glass in the manufacturer catalogs, nd (d line) and Abbe number vd (F / C lines), overlaid with the glasses used by this design (taken directly from the built materials, so AGF, model glasses and built-in crystals are included). By default the manufacturers in the design's catalogs are drawn, and catalogs=all draws all of them. The display range is the 0.5 %–99.5 % quantile of the catalog points (outliers such as infrared materials do not squash the optical glasses into a clump; the count is stated in the info block), and the design's glasses are always included. To find a glass exactly by nd / vd, use lb glass.
• Sag table: for a surface, the sag z(r) from the vertex to the semi-aperture along the surface's local +y, the best-fit sphere through the vertex and the aperture edge (BFS, edge-matched: R = (r² + z²) / 2z), the deviation from the BFS (asphericity, µm) and the surface slope dz/dr (°). The numbers to give a manufacturer: maximum deviation, P-V deviation, maximum slope. By default it looks at the first aspheric / conic surface; for non-rotationally-symmetric surfaces it gives the profile along y. The sag agrees bit for bit with the closed form for even asphere, and the BFS of a sphere is itself, with deviation 0; tested.
• Full-field image-quality map: polychromatic RMS computed on a 2D field grid (sampling as for RMS vs. field); area=circle is the whole field circle and sensor is the inscribed 3:2 sensor rectangle (to see the corners). For rotationally symmetric systems (no coordinate breaks, non-rotationally-symmetric surface types, or decentered apertures) 2n + 1 points are computed along the field radius and then expanded — equivalent to point-by-point computation and much faster, and the worst location is a full circle (dashed); other systems are computed point by point (decentered / tilted asymmetry is plain to see, and the worst location is marked ×), and an extra ring outside the circle is computed only to support interpolation. The figure is rendered on a fine grid and clipped to the field circle, with no blocky steps.
• RMS versus field: along +y from the axis to the maximum field, num points, giving the RMS spot radius (µm) or RMS wavefront (λ) for each wavelength and for the polychromatic case. Gauss-quadrature pupil (rings rings × arms arms), the same approach as the merit function's RSCE / RSCH / RWCE / RWCH; ref=centroid is relative to the centroid (wavefront with tilt removed), chief is relative to the primary wavelength's chief ray (wavefront with only piston removed). The polychromatic spot is computed by combining wavelengths by weight, and the polychromatic wavefront is the square root of the weighted average of the per-wavelength RMS². arms defaults to 2 × rings (default 6 rings 12 arms, the same for spot and wavefront, with azimuths as in Zemax), bit for bit identical to RSCE / RSCH / RWCE / RWCH with Ring = rings; 12 arms differ from a 201 × 201 dense grid by only about 0.04 %. Diffraction-limit reference: for spot, the Airy radius 1.22 λF#; for wavefront, the Maréchal criterion 0.072 λ. The optical path of an ideal thin lens (type=paraxial) follows Zemax's OPD Mode (opd_mode): when the incident beam has no aberration, the wavefront is 0 at every field.
• FFT sampling (mtf, mtf_vs_field, psf; the same for lb strehl): sampling=auto (default) picks a tier automatically — from 128 / 256 / 512 / 1024, the smallest tier for which the FFT window (λ·F# × (pupil sampling − 1)) is not smaller than 4 times the geometric spot diameter. The geometric diameter is centered on that wavelength's chief ray, and blocked rays are not counted; for MTF all fields and wavelengths are considered (MTF vs. field considers its own field points), while for PSF the current field and the chosen wavelength are considered; the automatic sampling for PSF and lb strehl goes up to 512 (one polychromatic PSF at the 1024 tier takes two or three seconds), and a hint is still shown when it is not enough; you can explicitly write view psf sampling=1024. An integer such as sampling=256 is a fixed sampling (32–1024). When the spot is larger than the window, the PSF wraps around and the low-frequency OTF samples are too sparse, so the MTF error is large: on the reference designs, with a window ≥ 4 times, the whole curve is within 0.004 of sampling 2048; below 1.5 times, the difference is 0.02–0.5. The info block and the command output print the sampling actually used (marked when automatic); a hint "undersampled" appears when the window is less than 1.5 times the geometric spot diameter, or when, after tilt removal, the phase difference between adjacent pupil samples exceeds half a wavelength — when the aberration is so large that even sampling 1024 is not enough, look at the Huygens MTF / PSF instead. The MTF specs in verify also use automatic sampling, and the explanation states the sampling used.
• Zernike coefficients: the OPD over the pupil (relative to the chief-ray reference sphere, on the same samples as the wavefront map, in normalized entrance-pupil coordinates Px = ρ cos θ, Py = ρ sin θ, with θ measured counterclockwise from +x) is least-squares fitted to Zernike polynomials. kind=fringe (default; Zemax Fringe's 37-term ordering, not normalized: Z4 = 2ρ² − 1 defocus, Z5 / Z6 astigmatism, Z7 / Z8 coma, Z9 = 6ρ⁴ − 6ρ² + 1 spherical aberration…); kind=standard (Noll indexing and normalization, where the coefficient is that term's RMS, up to 66 terms). It also gives the statistics from Zemax's text page: P-V / RMS "to chief ray" (raw OPD) and "to centroid" (after removing piston and tilt), the RMS of the fit residual, and the Strehl estimate exp(−(2πσ)²) (Maréchal, σ = RMS to centroid; clearly too low when σ is above about 0.1 λ — use the PSF's Strehl ratio instead). The piston term Z1 is not drawn. Checks: for a pure-defocus parabolic mirror, Z4 and Z9 agree with the orthogonal projection of the analytic wavefront (within 0.2 % / 0.5 %), and the Standard Z4 equals the defocus RMS; for a field in the y direction, the terms odd in x (Z2, Z6, Z7, Z10…) are 0; the coefficients of a synthesized wavefront are recovered term by term; all tested.
• Huygens MTF: for each field and wavelength the Huygens PSF is computed on the image plane; summing along x gives the line spread function in y (tangential T) and summing along y gives the one in x (sagittal S), and the Fourier transform is taken directly at the requested frequencies and normalized by the zero-frequency value. The window is one period of the PSF: discrete pupil sampling makes the Huygens PSF periodic on the image plane with period λ / Δu (Δu is the direction-cosine difference between adjacent samples projected onto the image-plane axis, which naturally stretches when the image plane is tilted), so the energy inside the window is all of the energy, and the MTF is not overestimated by truncating the far wings; each period has about 2.5 (s − 1) pixels (above Nyquist). When the 95 % radius of the geometric blur exceeds 0.4 times the period, the PSF overlaps its periodic images; the info block and command output flag those fields — increase sampling. Polychromatic adds the complex OTFs by weight and then takes the modulus (relative to the primary wavelength's chief ray, including lateral color and the phase of each wavelength's OTF, i.e. the MTF of the polychromatic PSF), the same convention as the FFT MTF (and Zemax). Checks: an ideal lens differs from the diffraction limit by < 0.01; with the image plane tilted 30°, the tangential MTF(f) differs from the diffraction limit (f / cos 30°) by < 0.01; monochromatic on-axis differs from the FFT MTF by < 0.015 (at low frequency the FFT MTF is affected by pupil sampling: at 3 /mm for a 14° field, sampling 64 differs by 0.04 and 128 by 0.017, while the Huygens MTF converges to the same value as sampling increases); tested.
• Encircled energy: the fraction of energy inside a circle of radius r centered on the reference point. method=diffraction (default) integrates the FFT PSF of each wavelength: the engine's PSF is the squared modulus of a zero-padded pupil FFT, so the grid samples are exactly a band-limited periodic function (spectrum = pupil autocorrelation, with no aliasing inside the grid), and the integral inside the circle is therefore evaluated analytically frequency by frequency (∫ e^{2πi f·x} dA = r J1(2πrρ)/ρ), with no pixel steps and accurate even as r → 0; the PSF of each wavelength is centered on its own chief ray, and here they are shifted into alignment by the chief-ray lateral color and then combined by weight. method=geometric uses the landing points of rays from stratified jittered pupil sampling (4 × sampling per side, about 50,000 rays per wavelength), with no diffraction. For the center, ref=chief is the primary wavelength's chief-ray image point and centroid is the polychromatic energy centroid; wave=0 combines all wavelengths by weight (unlike the PSF and wavefront map, where wave=0 = primary wavelength: encircled energy defaults to polychromatic, as in Zemax). Diffraction limit = per-wavelength 1 − J0² − J1² combined by weight. A perfect parabolic mirror agrees with the Rayleigh formula point by point (< 2e-3), and the geometric encircled energy of pure defocus = (r/R)² (r50 and r80 within 0.5 %); tested. The radius range by default extends to the worst field's 90 % energy radius × 1.5 (at least 3 Airy radii).
• Relative illumination: the ratio of the illumination at a point on the image plane to the on-axis value = the ratio of the projected solid angles of the exit pupil as seen from the image point (uniform Lambertian object, radiance conserved; Zemax's definition: "the effective area of the exit pupil as seen from the image point", integrated in direction-cosine space). (L, M) are the direction cosines from the chief-ray image point to the intersection of each ray with the exit-pupil plane (through the exit-pupil point, perpendicular to the image-space optical axis) — not the direction of the ray itself: with aberrations the ray does not pass through the image point, and the two differ by a few thousandths. The pupil is sampled with stratified jitter (default 101 × 101); each ray is traced with a small offset on both sides, ∂(L, M)/∂(Px, Py) is obtained by finite differences, and then integrated; vignetting, obscuration, pupil aberration and the variation of the image-space F-number with field are all included, while distortion is not (as in Zemax). The three lines are all ratios between 0 and 1 on the same vertical axis, with no dual axes; the effective F-number = 1 /(2·√(A/π)) is in the info block and the data table page. An ideal thin lens agrees with the independent integral ∫∫ f²/ρ⁴ dA to < 2e-4, and with a surface aperture blocking light, both the transmitted fraction and the illumination agree with the analytic intersection area of two circles (< 3e-3); tested. The retrofocus wide-angle (examples/wide_angle) reaches 1.0085 at the maximum field — the entrance pupil grows with field, canceling the cos⁴, and an energy-conservation cross-check (object-space beam cross-section × sinθ ÷ image-plane area element) gives 1.008.
• Through-focus MTF: the same convention as lb mtf (FFT, polychromatic combined by complex OTF). The image plane moves along its own normal, positive along the propagation direction (correct for folded systems too), on a copy of the optical system, so the design itself is unchanged. Best focus = where (T + S)/2 is maximal (parabolic interpolation around the discrete maximum); when the maximum falls at a scan endpoint, a hollow triangle is drawn and labeled "outside the scan range"; increase step or steps and look again. The defaults are 21 positions, a step of λF#² rounded, and a frequency of 1/8 of the cutoff frequency rounded. For a parabolic mirror with the image plane 0.05 mm behind the focus, the best focus comes out as −0.05 mm (difference < 1e-4 mm), and at the image plane it agrees with the MTF analysis; tested.
• Grid distortion: chief-ray image points of a square object-space grid (half-width = maximum field) versus the ideal (paraxial) grid. For angular fields the grid points are taken equally spaced in tan, so the ideal image is a square grid (straight lines imaged as straight lines means no distortion); ideal image point = paraxial magnification × (tanθx, tanθy or object height), with the magnification for x and y each calibrated by extrapolating small-field chief rays (as for field curvature / distortion). Distortion at each point is 100·(|r| − |r₀|)/|r₀|; TV distortion follows SMIA: 100·(A − B)/B, where B = height of the center column and A = the average height of the left and right edge columns (barrel is negative). When grid corners lie beyond the maximum field (the wide-angle diagonal is about 59°) and the engine cannot trace them, those points are left blank, the ideal grid is still complete, and TV distortion is recorded as "—". exaggerate=10 magnifies the deviation tenfold to show its shape (display only, noted in the info block). An ideal thin lens gives 0 everywhere, and the edge midpoints agree bit for bit with the maximum-field distortion of the field curvature / distortion figure; tested.
• Image simulation: the test patterns (Siemens star, grid, bar groups, checkerboard; generated by the program) are defined in ideal-image coordinates, so the ideal image on the left is the test pattern itself. Each wavelength is computed separately, and the three channels are composed in the wavelength's color (short wavelength blue, long wavelength red, each channel normalized: white in, white out). mode=patch (default): a small patch near the relative field field, with edge length by default the larger of 40 × the Airy diameter and 20 × the geometric RMS radius; the PSF is constant within the patch, and the PSF of each wavelength is offset relative to the primary wavelength by the chief-ray lateral color — astigmatism blurs the spokes in one direction first and lateral color puts colored fringes on edges, both directly visible. mode=full: the whole field (a square with corners at the maximum field), where each wavelength is mapped back to object space from its own chief-ray image height (distortion, lateral color), multiplied by the relative illumination, then divided into 8 × 8 tiles, each convolved with the PSF at its location (grid fields' PSFs are computed along +y and rotated to the tile's azimuth; the rotation acts on the PSF's sampling coordinates and is exact). During convolution the area outside the image is extended by mirroring, so edges do not darken artificially. In full mode the pixels are usually much larger than the PSF (tens to hundreds of µm), so it mainly shows distortion and vignetting; use patch to see aberration blur. Ideal thin lens, full: distortion 0, corner brightness = relative illumination; a perfect mirror in patch mode is almost the test pattern itself; lateral color agrees with the chief ray; tested.
• surface=all: one cell per surface, normalized by that surface's clear semi-aperture (aperture circles all the same size), with the semi-aperture and beam usage written under each cell. The automatic semi-aperture is taken from the actual rays, so usage is necessarily about 100 %; only surfaces with a fixed aperture (U) reveal whether it is tight — usage ≥ 95 % is marked amber, overflow is marked red, and the info block names the tightest surface.