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_index: int = 0, field_index: int = 0, surface_index: int = 0, MTF_type: str = 'mod', sampleSize: str = '256x256', maxFreq: float = 0, ShowDiffractionLimit: bool = True, UseDashes: bool = True, UsePolarization: bool = True) → tuple[ndarray, ndarray]

Get FFTMTF of the system.

Parameters:

• wavelength_index (int, optional) – System wavelength index to do the MTF on. 0 is for all wavelengths, Defaults to 0.

• field_index (int, optional) – System field index to do the MTF on. 0 is for all fields, defaults to 0

• surface_index (int, optional) – System surface index to do the MTF on. 0 is for image surface, defaults to 0

• MTF_type (str, optional) – Type of MTF to report: ‘modulation’, ‘real’, ‘imaginary’, ‘phase’, ‘square wave’, defaults to ‘mod’

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

• maxFreq (float, optional) – Max frequency of the analysis, 0 to default, defaults to 0

• ShowDiffractionLimit (bool, optional) – Include diffraction limited curves, defaults to True

• UseDashes (bool, optional) – Use dashes, defaults to True

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

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.

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_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_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 | 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