API Documentation

This section provides detailed API documentation for the individual modules within the stop-utils package.

Command-Line Interface (cli)

Command-line interface for WFE analysis.

stop_utils.cli.version_callback(value)[source]

Show version and exit.

Parameters:: value (bool)
Return type:: None

stop_utils.cli.print_coeffs(coefficients, zernikes)[source]

Logs polynomial coefficients line by line.

Parameters:

coefficients (List[float])
zernikes (List[float])

Return type:

None

stop_utils.cli.save_coefficients(output_dir, orthonormal_coefficients, zernike_coefficients, params)[source]

Save polynomial coefficients and ellipse parameters to JSON file.

Parameters:

output_dir (Path)
orthonormal_coefficients (List[float])
zernike_coefficients (List[float])
params (EllipticalParams)

Return type:

None

stop_utils.cli.validate_plot_format(value)[source]

Validate plot format option.

Parameters:: value (str)
Return type:: str

stop_utils.cli.run_analysis(input_file, output_dir, n_polynomials, plot_format, save_coeffs, no_plots, file_format=None)[source]

Run WFE analysis with given parameters.

Parameters:

input_file (Path)
output_dir (Path)
n_polynomials (int)
plot_format (str)
save_coeffs (bool)
no_plots (bool)
file_format (Optional[str])

Return type:

None

stop_utils.cli.callback(version=<typer.models.OptionInfo object>)[source]

Wavefront Error Analysis Tools - Analyze and visualize wavefront error data.

This tool provides functionality for analyzing wavefront error data using (orthonormal) polynomial decomposition on elliptical apertures and generating visualization outputs.

Parameters:: version (bool)
Return type:: None

stop_utils.cli.analyze(input_file=<typer.models.OptionInfo object>, output_dir=<typer.models.OptionInfo object>, n_polynomials=<typer.models.OptionInfo object>, plot_format=<typer.models.OptionInfo object>, save_coeffs=<typer.models.OptionInfo object>, no_plots=<typer.models.OptionInfo object>, file_format=<typer.models.OptionInfo object>)[source]

Analyze WFE data and generate results.

Parameters:

input_file (Path)
output_dir (Path)
n_polynomials (int)
plot_format (str)
save_coeffs (bool)
no_plots (bool)
file_format (Optional[str])

Return type:

None

stop_utils.cli.zmx_batch(base_folder=<typer.models.OptionInfo object>, output_dir=<typer.models.OptionInfo object>, surface_name=<typer.models.OptionInfo object>, wavelength_um=<typer.models.OptionInfo object>)[source]

Process all ZMX files in the specified directory.

Parameters:

base_folder (str)
output_dir (Path)
surface_name (str)
wavelength_um (Optional[float])

Return type:

None

stop_utils.cli.main()[source]

Main entry point for the CLI.

Return type:: None

WFE Analysis (wfe_analysis)

Core functionality for Wavefront Error analysis.

stop_utils.wfe_analysis.load_wfe_data(file_path, file_format=None)[source]

Load WFE data from file and convert to nanometers. Handles different formats based on the provided format string or defaults to generic.

Parameters:

file_path (Path)
file_format (Optional[str])

Return type:

ndarray[Any, dtype[float64]]

stop_utils.wfe_analysis.mask_to_elliptical_aperture(label_img)[source]

Convert an elliptical mask to a photutils EllipticalAperture.

Parameters:: label_img (ndarray[Any, dtype[int64]]) – Labeled image array where each region has a unique integer value
Returns:: (EllipticalAperture object, EllipticalParams object)
Return type:: tuple
Raises:: ValueError – If no regions found in mask

stop_utils.wfe_analysis.calculate_polynomials(pupil_mask, x, y, n_polynomials=15)[source]

Calculate orthonormal polynomials for given coordinates.

Parameters:

pupil_mask (ndarray[Any, dtype[bool_]]) – Boolean mask array
x (ndarray[Any, dtype[float64]]) – X coordinates array
y (ndarray[Any, dtype[float64]]) – Y coordinates array
n_polynomials (int) – Number of polynomials to calculate

Returns:

(Orthonormal polynomials array, Covariance matrix)

Return type:

tuple

stop_utils.wfe_analysis.fit_polynomials(errormap, pupil_mask, x, y, n_polynomials=15)[source]

Fit orthonormal polynomials to WFE data.

Parameters:

errormap (ndarray[Any, dtype[float64]]) – Wavefront error data array
pupil_mask (ndarray[Any, dtype[bool_]]) – Boolean mask array
x (ndarray[Any, dtype[float64]]) – X coordinates array
y (ndarray[Any, dtype[float64]]) – Y coordinates array
n_polynomials (int) – Number of orthonormal polynomials to use

Returns:

raw: Errormap to be fitted
coefficients: Fitted orthonormal polynomial coefficients
zernikes: Zernike coefficients (after removing first 3 terms from the orthonormal fit)
PTTF component map
Complete model map
Residual error map

Return type:

WFEResult object containing

stop_utils.wfe_analysis.analyze_wfe_data(wfe_file, n_polynomials=15, file_format=None)[source]

Analyze WFE data file.

Parameters:

wfe_file (Path) – Path to WFE data file
n_polynomials (int) – Number of polynomials to use
file_format (Optional[str]) – The format of the input file (e.g., ‘zemax’).

Returns:

(WFEResult object, EllipticalParams object)

Return type:

tuple

Raises:

FileNotFoundError – If wfe_file does not exist
ValueError – If data cannot be processed

Visualization (visualization)

Visualization utilities for WFE analysis.

stop_utils.visualization.plotlim(s, zoom)[source]

Calculate plot limits for zoomed view.

Parameters:

s (int) – Size of the dimension
zoom (int) – Zoom factor

Returns:

(min_limit, max_limit)

Return type:

tuple

stop_utils.visualization.setup_wfe_plot(data, title, zoom=4, cmap='jet')[source]

Set up a basic WFE plot with common formatting.

Parameters:

data (ndarray[Any, dtype[float64]]) – 2D array to plot
title (str) – Plot title
zoom (int) – Zoom factor for display
cmap (str) – Matplotlib colormap name

Returns:

(Figure object, Axes object)

Return type:

tuple

stop_utils.visualization.plot_wfe_data(data, aperture=None, title='Wavefront Error Map', output_path=None, zoom=4, cmap='gray_r')[source]

Plot WFE data with optional aperture overlay.

Parameters:

data (ndarray[Any, dtype[float64]]) – WFE data array
aperture (Optional[EllipticalAperture]) – Optional EllipticalAperture to overlay
title (str) – Plot title
output_path (Optional[Path]) – Optional path to save plot
zoom (int) – Zoom factor for display
cmap (str) – Matplotlib colormap name

Return type:

None

stop_utils.visualization.generate_plots(result, params, output_dir, format='png', zoom=1)[source]

Generate and save all analysis plots.

Parameters:

result (WFEResult) – WFEResult object containing analysis results
params (EllipticalParams) – EllipticalParams for the aperture
output_dir (Path) – Directory to save plots
format (str) – Output format (png, pdf, or svg)
zoom (int) – Zoom factor for display

Return type:

None

File Format Converters (converters)

stop_utils.converters.load_zemax_wfe(file_path)[source]

Loads Wavefront Error (WFE) data from a Zemax text file.

Parses the header to find wavelength and grid size, then reads the data grid and converts it from waves to nanometers.

Parameters:

file_path (Union[str, Path]) – path to the Zemax WFE map file (.txt). Can be a string or Path object.

Return type:

ndarray

Returns:

A 2D numpy array containing the WFE map in nanometers.

Raises:

FileNotFoundError – If the file does not exist.
ValueError – If the file format is incorrect or metadata is missing.

Types (types)

Type definitions for stop-utils package.

class stop_utils.types.EllipticalParams(x0, y0, a, b, theta)[source]

Bases: object

Parameters defining an elliptical aperture.

Parameters:

x0 (float)
y0 (float)
a (float)
b (float)
theta (float)

x0: float

y0: float

a: float

b: float

theta: float

class stop_utils.types.WFEResult(raw, coefficients, zernikes, pttf, model, residual)[source]

Bases: object

Results from WFE analysis.

Parameters:

raw (ndarray[Any, dtype[float64]])
coefficients (ndarray[Any, dtype[float64]])
zernikes (ndarray[Any, dtype[float64]])
pttf (ndarray[Any, dtype[float64]])
model (ndarray[Any, dtype[float64]])
residual (ndarray[Any, dtype[float64]])

raw: ndarray[Any, dtype[float64]]

coefficients: ndarray[Any, dtype[float64]]

zernikes: ndarray[Any, dtype[float64]]

pttf: ndarray[Any, dtype[float64]]

model: ndarray[Any, dtype[float64]]

residual: ndarray[Any, dtype[float64]]

static rms(errormap)[source]

Calculate RMS of the WFE errormap.

Parameters:: errormap (ndarray[Any, dtype[float64]])
Return type:: float

static rss(coefficients)[source]

Calculate RSS of coefficients.

Parameters:: coefficients (ndarray[Any, dtype[float64]])
Return type:: float

static ptp(errormap)[source]

Calculate Peak to Valley of the WFE errormap.

Parameters:: errormap (ndarray[Any, dtype[float64]])
Return type:: float

class stop_utils.types.AnalysisConfig(n_polynomials, save_coeffs, generate_plots, plot_format, output_dir)[source]

Bases: object

Configuration for WFE analysis.

Parameters:

n_polynomials (int)
save_coeffs (bool)
generate_plots (bool)
plot_format (str)
output_dir (Path)

n_polynomials: int

save_coeffs: bool

generate_plots: bool

plot_format: str

output_dir: Path

Zemax Integration (zemax)

Note

The Zemax integration modules require a Windows system with Zemax OpticStudio installed. These modules use the Zemax ZOS-API which is only available on Windows platforms.

Prerequisites:

Windows operating system
Zemax OpticStudio (Premium, Professional, or Standard Edition)
Valid Zemax license for API use
Python.NET (pythonnet) package installed

The Zemax submodule provides integration with Zemax OpticStudio through its ZOS-API.

Core ZOS-API Interface (zemax.zemax_wfe)

class stop_utils.zemax.zmx_boilerplate.Mock(*args, **kw)[source]: Bases: MagicMock

class stop_utils.zemax.zmx_boilerplate.PythonStandaloneApplication(path=None)[source]

Bases: object

exception LicenseException[source]: Bases: Exception

exception ConnectionException[source]: Bases: Exception

exception InitializationException[source]: Bases: Exception

exception SystemNotPresentException[source]: Bases: Exception

OpenFile(filepath, saveIfNeeded)[source]

CloseFile(save)[source]

SamplesDir()[source]

ExampleConstants()[source]

reshape(data, x, y, transpose=False)[source]

Converts a System.Double[,] to a 2D list for plotting or post processing

Parameters:

data (System.Double[,] data directly from ZOS-API)
x (x width of new 2D list [use var.GetLength(0) for dimension])
y (y width of new 2D list [use var.GetLength(1) for dimension])
transpose (transposes data; needed for some multi-dimensional line series data)

Returns:

res – a numpy array using numpy.asarray(res)

Return type:

2D list; can be directly used with Matplotlib or converted to

transpose(data)[source]

Transposes a 2D list (Python3.x or greater).

Useful for converting mutli-dimensional line series (i.e. FFT PSF)

Parameters:: data (Python native list (if using System.Data[,] object reshape first))
Returns:: res
Return type:: transposed 2D list

Wavefront Extractor (zemax.wavefront_extractor)

stop_utils.zemax.wavefront_extractor.process_single_file(zemax_file_path, base_folder, output_dir='WavefrontOutputs', surface_name='EXPP', wavelength_um=0.633)[source]

Process a single Zemax file and extract wavefront data.

Parameters:

zemax_file_path (str) – Path to the Zemax file
base_folder (str) – Base folder for output
output_dir (str) – Directory for output files
surface_name (str) – Name of the surface to analyze
wavelength_um (float) – Wavelength in micrometers to use

Batch Processor (zemax.zmx_batch_processor)

stop_utils.zemax.zmx_batch_processor.batch_process_zmx(base_folder, output_dir='WavefrontOutputs', surface_name='EXPP', wavelength_um=None)[source]

Process all ZMX files in the specified directory.

Parameters:

base_folder (str)
output_dir (str)
surface_name (str)
wavelength_um (Optional[float])

Warning

Attempting to use these modules on non-Windows platforms will result in import errors for Windows-specific dependencies like ‘winreg’ and the Zemax API components.