Soon, we will launch a new and updated customer portal, which is an important step toward providing our customers with one place to learn, interact, and get help.
Learn more.

Generating a list of output data types for each analysis in the ZOS-API

This article explains how to use Python and MATLAB to generate a list of available data types for each analysis in the ZOS-API.
 
Michael Cheng
02/01/2018
OpticStudio
ZOS-API
Data types

Introduction
When using the ZOS-API to access OpticStudio, it’s common to run analyses like Spot Diagram, the Modulation Transfer Function (MTF), or the Point Spread Function (PSF). Different analyses provide different types of data. The ZOS-API supports the following data types:


 
Typically, an analysis returns only one or two kinds of data types. For example, results from a Fast Fourier Transform (FFT) MTF analysis are returned in a DataSeries. A request for DataGrid from analysis FFT MTF results in empty or null data. Not all analyses windows have populated results. Although each analysis has an associated data type, test the corresponding data type to ensure it includes data. For analyses that do not have data, use the brute force GetTextFile to save the data to disk and then manually parse the data.
 
A table makes it easy to see the data types that are available for an analysis. The following two examples show how to generate a table using Python and MATLAB. The source code for both tables is provided in the "Sample File" section of this article.
 
 
Python Example
After the boilerplate code is generated from OpticStudio, start from the line “# Insert Code here” The following code snippet is the first block of code. By default, this code tests sequential analyses. To generate a table for non-sequential analyses, uncomment the second line of code.
 

# Insert Code here
TheSystem = zosapi.TheSystem

# Uncomment following line for non-sequential analyses
# TheSystem.MakeNonSequential()
TheAnalyses = TheSystem.Analyses

In the next code snippet, all the enumeration names are retrieved using “constants.__dicts__[0].keys()” (“constants” contains all the enumeration used by the ZOS-API). A for-loop then checks all the enumerations to find the ones that include “AnalysisIDM_.” When a matched enumeration is found, the code snippet looks up the value using “constants.__dicts__[0].get(i)” and records it in the list “analIDM.” Finally, the code snippet sorts the analIDM list so it’s easy to use.
 
analIDM = []
API_enum = list(constants.__dicts__[0].keys())
for i in API_enum:
    if i.find('AnalysisIDM_') != -1:
        analIDM.append(constants.__dicts__[0].get(i))
        print(constants.__dicts__[0].get(i), ':  ', i)
analIDM.sort()



The next line prints the data type names.
 


print('Name\tSetting\tDatGrid\tDatGridRgb\tDatSrs\tDatSrsRgb\t' +
    'DatScat\tDatScatRgb\tRayData\tCriRayDat\tPathAnal\tSpotDat')
The list analIDM includes all the analyses. In the next code snippet, a for-loop is used to open all the available analyses using “TheAnalyses.New_Analysis(k).”
 
If the analysis is a None type, an error message is printed. To get information about these analyses, the codes should change the system to corresponding mode (sequential or non-sequential) as described above.
 
If the analysis is a valid type (not a None type), the following code snippet tests and reports the availability of each data type.
 

for k in analIDM:
    a = TheAnalyses.New_Analysis(k)
    if a is None :
        print('This analysis cannot be opened in ',
               'Sequential Mode' if TheSystem.Mode == 0 else 'Non-Sequential Mode',
               ': enumID ',k)
        continue
    ar = a.GetResults()
    print(a.GetAnalysisName, '\t',
           a.HasAnalysisSpecificSettings, '\t',
           ar.DataGrids is not None and ar.NumberOfDataGrids > 0, '\t',
           ar.DataGridsRgb is not None and ar.NumberOfDataGridsRgb > 0, '\t',
           ar.DataSeries is not None and ar.NumberOfDataSeries > 0, '\t',
           ar.DataSeriesRgb is not None and ar.NumberOfDataSeriesRgb > 0, '\t',
           ar.DataScatterPoints is not None and ar.NumberOfDataScatterPoints > 0, '\t',
           ar.DataScatterPointsRgb is not None and ar.NumberOfDataScatterPoints > 0, '\t',
           ar.RayData is not None, '\t',
           ar.CriticalRayData is not None, '\t',
           ar.PathAnalysisData is not None, '\t',
           ar.SpotData is not None)
    a.Close()





The result looks like this:



 

Different values are separated by tabs, so you can easily copy and paste the data into a Microsoft Excel spreadsheet.




 
MATLAB Example
First, generate the boilerplate code in OpticStudio, and then add the custom code after the line “% Add your custom code here...”. The following code snippet is the first block of code. By default, this code tests sequential analyses. To generate a table for non-sequential analyses, uncomment “TheSystem.MakeNonSequential()” line.
 


% Add your custom code here...
% Uncomment following line for non-sequential analyses
% TheSystem.MakeNonSequential()
TheAnalyses = TheSystem.Analyses;

 


In next block of code, the code snippet saves the analysis enumerations ZOSAPI.Analysis.AnalysisIDM in the variable analIDM, and then gets the value by using “System.Enum.GetValues(analIDM.GetType).”
 


analIDM = ZOSAPI.Analysis.AnalysisIDM;
analValue = System.Enum.GetValues(analIDM.GetType);

 

The next line prints the data type names. The LogicStr is defined for printing the Boolean values in an output that’s easier to read. In MATLAB, if you print a Boolean value, by default, the output will be “0” for Boolean-false and “1” for Boolean-true. By predefining a LogicStr, we can print “true” for Boolean-true and “false” for Boolean-false.

 

print('Name\tSetting\tDatGrid\tDatGridRgb\tDatSrs\tDatSrsRgb\t' +

    'DatScat\tDatScatRgb\tRayData\tCriRayDat\tPathAnal\tSpotDat')


The list analIDM includes all the analyses. In the next block, a for-loop opens all the available analyses using “TheAnalyses.New_Analysis(analValue(idx))”.  If the returned analysis object is not empty, the code snippet tests and reports the availability of each data type. If the returned analysis object is empty, the code prints an error message. To get information about these analyses, the code snippet changes the system to the corresponding mode (sequential or non-sequential).
 

for idx = 1:analValue.Length
    a = TheAnalyses.New_Analysis(analValue(idx));
    if not(isempty(a))
        ar = a.GetResults();
        fprintf('%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n',...
            char(a.GetAnalysisName),...
            LogicalStr{(a.HasAnalysisSpecificSettings > 0) + 1},...
            LogicalStr{(ar.NumberOfDataGrids > 0) + 1},...
            LogicalStr{(ar.NumberOfDataGridsRgb > 0) + 1},...
            LogicalStr{(ar.NumberOfDataSeries > 0) + 1},...
            LogicalStr{(ar.NumberOfDataSeriesRgb > 0) + 1},...
            LogicalStr{(ar.NumberOfDataScatterPoints > 0) + 1},...
            LogicalStr{(ar.NumberOfDataScatterPointsRgb > 0) + 1},...
            LogicalStr{(ar.NumberOfRayData > 0) + 1},...
            LogicalStr{(~isempty(ar.CriticalRayData)) + 1},...
            LogicalStr{(~isempty(ar.PathAnalysisData)) + 1},...
            LogicalStr{(~isempty(ar.SpotData)) + 1});
        a.Close()
    else
        fprintf('This analysis cannot be opened in %s. Mode. enumID: %s\n', char(TheSystem.Mode), char(analValue(idx)));
    end
end


The result appears like this:
 


 
The different values are separated by tabs, so that you can copy and paste them into an Excel spreadsheet. Here is an example:




Summary
This article explains how to use Python and MATLAB to generate a list of available data types for each analysis in the ZOS-API, such as Spot Diagram, MTF, and PSF. You can then copy and paste this list into an Excel spreadsheet to help you organize and use the data.

For more information about accessing data for analyses that do not have values in the data type, refer to the GetTextFile() method in the ZOS-API Syntax Help. For more information about the ZOS-API, see the Knowledgebase articles, ZOS-API.NET: An Overview and Support Material for ZOS-API Users. In OpticStudio 17 and later, you can find the full documentation of the ZOS-API on the Programming tab > ZOS-API Help > ZOS-API Syntax Help.