Analysis Functions

These functions provide methods to execute some type of optical analysis on the system.

skZemax.skZemax_subfunctions._analyses_functions.Analyses_ExtractSectionOfTextFile(in_file: list | str, start_marker: str | None = None, end_marker: str | None = None) → list

This is just a convince function which will extract only a section of a text file. Typically these text files are the output made by skZemax Analyses function (but this function is agnostic to where the text file came form). For instance, this can be useful for selection of only a part of an optical prescription.

See Example 03.

Parameters:

• in_file (Union[list, str]) – Can be a list where each element is a line of a loaded text file, or a string to a path to load the text file.

• start_marker (str, optional) – The starting marker denoting when to begin selecting a part of the text, defaults to None (start at the beginning)

• end_marker (str, optional) – The ending marker denoting when to stop selecting a part of the text, defaults to None (goes to the end)

Returns:

a list where each element is a line of the (sectioned) text file.

Return type:

list

skZemax.skZemax_subfunctions._analyses_functions.Analyses_FFTMTF(self, wavelength: int | float | ZOSAPI_SystemData_IWavelength = 0, field: int | ZOSAPI_SystemData_IField = 0, surface: int | ZOSAPI_Editors_LDE_ILDERow = 0, sample_size: str = '256x256', max_freq: float = 0, use_polarization: bool = True, configuration: int = None) → Dataset

Get the (sequential) FFT MTF of the system.

Parameters:

• wavelength (int | float | ZOSAPI_SystemData_IWavelength, optional) – System wavelength (as index, microns, or object) to do the MTF on. An int of 0 selects all all wavelengths, Defaults to 0.

• field (int | ZOSAPI_SystemData_IField, optional) – System field (index of object) to do the MTF on. An int of 0 selects all fields, defaults to 0

• surface (int, optional) – System surface (index or object) to do the MTF on. An int of 0 selects the image surface, defaults to 0

• sample_size (str, optional) – ‘32x32’, ‘64x64’, ‘128x128’, ‘256x256’, ‘512x512’, ‘1024x1024’, ‘2048x2048’, ‘4096x4096’, ‘8192x8192’, ‘16384x16384’, defaults to ‘256x256’

• max_freq (float, optional) – Max frequency of the analysis, 0 allows Zemax to select it, defaults to 0

• use_polarization (bool, optional) – Use polarization, defaults to True

• configuration (bool, optional) – MCE configration to perform the analysis on. If None will use the active configuration, defaults to None.

Returns:

The x and y data of the FFTMTF analysis.

Return type:

tuple[np.ndarray, np.ndarray]

skZemax.skZemax_subfunctions._analyses_functions.Analyses_FFTPSF(self, wavelength: int | float | ZOSAPI_SystemData_IWavelength = 0, field: int | ZOSAPI_SystemData_IField = 0, surface: int | ZOSAPI_Editors_LDE_ILDERow = 0, sample_size: str = '256x256', output_size: str = '512x512', image_delta_microns: int | float = 0, use_polarization: bool = True, use_normalization: bool = True, configuration: int = None) → Dataset

Get the (sequential) FFT PSF of the system.

Parameters:

• wavelength (int | float | ZOSAPI_SystemData_IWavelength, optional) – System wavelength (as index, microns, or object) to do the MTF on. An int of 0 selects all all wavelengths, Defaults to 0.

• field (int | ZOSAPI_SystemData_IField, optional) – System field (index of object) to do the MTF on. An int of 0 selects all fields, defaults to 0

• surface (int, optional) – System surface (index or object) to do the MTF on. An int of 0 selects the image surface, defaults to 0

• sample_size (str, optional) – Sampling of the PSF calulation. ‘32x32’, ‘64x64’, ‘128x128’, ‘256x256’, ‘512x512’, ‘1024x1024’, ‘2048x2048’, ‘4096x4096’, ‘8192x8192’, ‘16384x16384’, defaults to ‘256x256’

• output_size (str, optional) – Size of the output grid (for display). ‘32x32’, ‘64x64’, ‘128x128’, ‘256x256’, ‘512x512’, ‘1024x1024’, ‘2048x2048’, ‘4096x4096’, ‘8192x8192’, ‘16384x16384’, defaults to ‘512x512’

• image_delta_microns – The distance in micrometers between points in the image grid. Use zero for the default grid spacing, defaults to 0

• use_polarization (bool, optional) – Use polarization, defaults to True

• use_normalization (bool, optional) – If should normalize the PSF or not, defaults to True

• configuration (bool, optional) – MCE configration to perform the analysis on. If None will use the active configuration, defaults to None.

Returns:

The x and y data of the FFTMTF analysis.

Return type:

tuple[np.ndarray, np.ndarray]

skZemax.skZemax_subfunctions._analyses_functions.Analyses_Footprint(self, in_Surface: int | ZOSAPI_Editors_LDE_ILDERow, delete_vignetted: bool = False) → Dataset

Produces a footprint diagram.

ZOI-API interface for the footprint analysis is extremely limited. Data is only saved to a textfile of: - Ray X Minimum - Ray X Maximum - Ray Y Minimum - Ray Y Maximum - Maximum Radius - Ray X Center - Ray Y Center - Ray X Half Width - Ray Y Half Width - Wavelength as an aggregate of all the wavelengths/fields/configurations being looked at.

Note that this information does not capture any footprint descriptions beyond plotting an ellipse. Any more realistic ray-tracing is lost through the ZOS-API and needs to be examined directly in Zemax - or run your own ray trace using functions like LDE_RunRayTrace().

This function loops through all fields/wavelengths/configurations individually and records the above information in an xarray for user analysis. See AnalysisPlotting_Footprint().

Parameters:

• in_Surface (Union[int, ZOSAPI_Editors_LDE_ILDERow]) – The surface to study. Can be an index or LDE surface object.

• delete_vignetted (bool, optional) – If True wil delete vignetted ray, defaults to False

skZemax.skZemax_subfunctions._analyses_functions.Analyses_GetGeneralLensData(self)

This function does not do any “formal analysis” that Zemax does, instead it simply parses the “General Lens Data” section of Analyses_ReportSystemPrescription() in a way that is nice to use in python (a boxed dict).

There are functions like self.TheSystem.LDE.GetPupil() to get (most) of these values separately, but this is a succinct way to get most things one is interested in.

skZemax.skZemax_subfunctions._analyses_functions.Analyses_GetNamesOfAllAnalyses(self, print_to_console: bool = False) → list

This function is simply for user convenance to look up the ZOS-API names of all analysis types. This can be useful to look up what one may want to code as input to functions like Analyses_RunAnalysesAndGetResults().

Parameters:

print_to_console (bool, optional) – If True will print to console, defaults to False

Returns:

A list of the names of all analyses types the ZOS-API knows.

Return type:

list

skZemax.skZemax_subfunctions._analyses_functions.Analyses_HuygensMTF(self, wavelength: int | float | ZOSAPI_SystemData_IWavelength = 0, field: int | ZOSAPI_SystemData_IField = 0, pupil_sample_size: str = '64x64', image_sample_size: str = '64x64', image_delta_microns: int | float = 0, max_freq: float = 0, use_polarization: bool = True, configuration: int = None) → Dataset

Get the Huygens MTF of the system. Simply, this is more accurate than the FFT version, but (possibly much) slower.

Parameters:

• wavelength (int | float | ZOSAPI_SystemData_IWavelength, optional) – System wavelength (as index, microns, or object) to do the MTF on. An int of 0 selects all all wavelengths, Defaults to 0.

• field (int | ZOSAPI_SystemData_IField, optional) – System field (index of object) to do the MTF on. An int of 0 selects all fields, defaults to 0

• pupil_sample_size (str, optional) – Selects the size of the grid of rays to trace to perform the computation. Higher sampling densities yield more accurate results at the expense of longer computation times. ‘32x32’, ‘64x64’, ‘128x128’, ‘256x256’, ‘512x512’, ‘1024x1024’, ‘2048x2048’, ‘4096x4096’, ‘8192x8192’, ‘16384x16384’, defaults to ‘64x64’

• image_sample_size (str, optional) – The size of the grid of points on which to compute the diffraction image intensity. This number, combined with the image delta, determine the size of the area displayed. ‘32x32’, ‘64x64’, ‘128x128’, ‘256x256’, ‘512x512’, ‘1024x1024’, ‘2048x2048’, ‘4096x4096’, ‘8192x8192’, ‘16384x16384’, defaults to ‘64x64’

• image_delta_microns – The distance in micrometers between points in the image grid. Use zero for the default grid spacing, defaults to 0

• max_freq (float, optional) – Max frequency of the analysis, 0 allows Zemax to select it, defaults to 0

• use_polarization (bool, optional) – Use polarization, defaults to True

• configuration (bool, optional) – MCE configration to perform the analysis on. If None will use the active configuration, defaults to None.

Returns:

The x and y data of the FFTMTF analysis.

Return type:

tuple[np.ndarray, np.ndarray]

skZemax.skZemax_subfunctions._analyses_functions.Analyses_HuygensPSF(self, wavelength: int | float | ZOSAPI_SystemData_IWavelength = 0, field: int | ZOSAPI_SystemData_IField = 0, pupil_size: str = '64x64', image_size: str = '64x64', image_delta_microns: int | float = 0, rotation: int = 0, use_polarization: bool = True, use_normalization: bool = True, use_centroid: bool = False, configuration: int = None) → Dataset

Get the (sequential) Huygens PSF of the system. Simply, this is more accurate than the FFT version, but (possibly much) slower.

Parameters:

• wavelength (int | float | ZOSAPI_SystemData_IWavelength, optional) – System wavelength (as index, microns, or object) to do the MTF on. An int of 0 selects all all wavelengths, Defaults to 0.

• field (int | ZOSAPI_SystemData_IField, optional) – System field (index of object) to do the MTF on. An int of 0 selects all fields, defaults to 0

• pupil_sample_size (str, optional) – Selects the size of the grid of rays to trace to perform the computation. Higher sampling densities yield more accurate results at the expense of longer computation times. ‘32x32’, ‘64x64’, ‘128x128’, ‘256x256’, ‘512x512’, ‘1024x1024’, ‘2048x2048’, ‘4096x4096’, ‘8192x8192’, ‘16384x16384’, defaults to ‘64x64’

• image_sample_size (str, optional) – The size of the grid of points on which to compute the diffraction image intensity. This number, combined with the image delta, determine the size of the area displayed. ‘32x32’, ‘64x64’, ‘128x128’, ‘256x256’, ‘512x512’, ‘1024x1024’, ‘2048x2048’, ‘4096x4096’, ‘8192x8192’, ‘16384x16384’, defaults to ‘64x64’

• image_delta_microns – The distance in micrometers between points in the image grid. Use zero for the default grid spacing, defaults to 0

• rotation (int, optional) – Rotation specifies how the surface plots are rotated; either 0, 90, 180, or 270 degrees, defaults to 0

• use_polarization (bool, optional) – Use polarization, defaults to True

• use_normalization (bool, optional) – If should normalize the PSF or not, defaults to True

• use_centroid (bool, optional) – If true, the plot will be centered on the geometric image centroid. If false, the plot will be centered on the chief ray, defaults to False

• configuration (bool, optional) – MCE configration to perform the analysis on. If None will use the active configuration, defaults to None.

Returns:

The x and y data of the FFTMTF analysis.

Return type:

tuple[np.ndarray, np.ndarray]

skZemax.skZemax_subfunctions._analyses_functions.Analyses_ReportSurfacePrescription(self, in_Surface: int | ZOSAPI_Editors_LDE_ILDERow, save_textfile_path: str | None = None) → list

Constructs the prescription report of a sequential (LDE) surface in optical system. This is returned as text information which can be saved in a .txt file.

Parameters:

• in_Surface (Union[int, ZOSAPI_Editors_LDE_ILDERow]) – The surface to analyze as an LDE surface object or as an index.

• save_textfile_path (str, optional) – Full absolute .txt file path to save prescription data text file, defaults to None (no custom saving)

Returns:

A list where each element is a line of the prescription report.

Return type:

list

skZemax.skZemax_subfunctions._analyses_functions.Analyses_ReportSystemPrescription(self, save_textfile_path: str | None = None) → list

Constructs the prescription report of the optical system. This is returned as text information which can be saved in a .txt file.

Parameters:

save_textfile_path:save_textfile_path – Full absolute .txt file path to save prescription data text file, defaults to None (no custom saving)

Returns:

A list where each element is a line of the prescription report.

Return type:

list

skZemax.skZemax_subfunctions._analyses_functions.Analyses_RunAnalysesAndGetResults(self, analysis: str, analysis_settings: dict | Box | ndarray[int] = None) → ZOSAPI_Analysis_Data_IAR

This is a generalized function to run a Zemax analysis on the optical system. It is intended to facilitate users - with some familiarity with the ZOS-API - to support their own analysis code if a wrapper function for the analysis doesn’t exist, or if the user would like more direct access to the results. User ZOS-API familiarity is expected to be on the topics of the analysis setting documentation, and processing the output of a GetResults() call for the analysis (which differs based on the type of analysis being done).

It is recommended to use a wrapper function, such as Analyses_FFTMTF(), for robustness and ease of use.

Note that this function will adjust all settings through analysis configuration (.CFG) files rather than direct property assignment. The reason for this is that much of the direct assignment through the ZOS-API does not work or was never supported to begin with.

Analysis settings are intended by ZOI-API to be adjusted through a configuration file with a ModifySettings() function call. If analysis settings are provided to this function as a python dictionary formatted as dict[MODIFYSETTINGS KEYWORD] = str(value), this method is attempted.

Documentation on the analysis settings - and the keys to provide in the settings dictionary - can be found in the pdf help file in Section 10.2.14.92. MODIFYSETTINGS (keywords).

There are analysis settings which are either simply not documented by ZOI-API within Section 10.2.14.92, or support for them simply doesn’t exist through the ZOS-API. In this case it is possible to directly adjust the binary values of the configuration file to implement the settings you want.

In this case supply a numpy array of integer values for these settings. Since these are undocumented it may take some trial and error will to work out what to enter. However, a fairly reliable way is to look at the settings interface for the analysis in the typical Zemax application user interface.

The order of the settings to enter into the np.ndarray will typically be the order of the options in the settings menu - starting with each option in the left most column of settings, then each in the next column, and so on all the way to the right most column.

Values are (typically) 1 meaning enabled and 0 meaning disabled - or in the case of multiple options, an integer value selecting the item in the user interface’s drop down menu for that option.

As an example: For the Cardinal Point Data Analysis the settings menu in the typical Zemax application user interface looks like:

+========================+============+ | First Surface | Wavelength | +————————+————+ | Last Surface | Orientation | +========================+============+

Where applicable, the menu options are sorted by index. Other (such as orientation here) have the options as: [Y-Z, X-Y]. Therefore, for settings

• First Surface = second in the system

• Last Surface = fourth in the system

• Wavelength = third in the system

• Orientation = ‘Y-Z’

The array this function wants will be: [2, 4, 3, 1].

… and yes, I know this sucks … one of the reasons for the wrapper functions in skZemax.

Parameters:

• analysis (str) – The name of the analysis to perform. See output of Analyses_GetNamesOfAllAnalyses() for names.

• analysis_settings (Union[dict, np.ndarray[int]], optional) – User settings of the analysis. See descriptions above, defaults to None

Returns:

The output of the analysis GetResults() function call.

Return type:

ZOSAPI_Analysis_Data_IAR