There are a few methods for extracting the detector data through an API script – most of which are exemplified in samples #8 and #24 within the {Zemax}\ZOS-API Sample Code folder. Based on those samples, we see there are two general interfaces we can use, which I will outline below.

ZOSAPI.Analysis.I_Analyses Interface

The I_Analyses interface allows us to call a Detector Viewer object in the same way we would open one within the GUI.  This method has the advantage of having a very explicit set of controls for choosing the type of data you want.

When you open a detector, you can update the view and the type of data that’s pulled in. If you don’t update the settings, then the detector opens with the last-saved settings. Using the API, you can choose which detector to look at, what type of data you would like to look at, and more – all provided within the Syntax Guide’s page on “ZOSAPI.Analysis.Settings.RayTracing.IAS_DetectorViwere Interface Reference”.

Once you’ve updated the settings, you can apply them and pull the results. If you are using a full color plot, the results will be given as a Data Grid. If you’re using a cross section view, the results will be given as a Data Series. If you’re using a Detector Color, then the results will be given as a Data Grid or Data Series RGB. I have discussed how to extract results in this forum post.

The disadvantage to this method is that opening the Detector Viewer may take extra time for a detector with a large amount of pixels. Additionally, you should be sure to close the window after you extract the data or else you will have many windows open that will slow down computation time.

Below is an example of how many of the settings can be updated in the MATLAB API to update the Detector Viewer results. The variable type required for each setting is given in the IAS_DetectorViewer help page (shown above).

  TheSystem = TheApplication.PrimarySystem;
  
  % Open the Detector Viewer
  detector = TheSystem.Analyses.New_Analysis(ZOSAPI.Analysis.AnalysisIDM.DetectorViewer);

  % Open the settings of the Detector Viewer
  detSettings = detector.GetSettings();

  % Select which detector we care about
  detSettings.Detector.SetDetectorNumber(7);

  % Select data to Show As type (enumerated variable)
  detSettings.ShowAs = ZOSAPI.Analysis.DetectorViewerShowAsTypes.FalseColor;

  % Select the Data Type we want (enumerated variable)
  detSettings.DataType = ZOSAPI.Analysis.DetectorViewerShowDataTypes.CoherentIrradiance;

  % Select the scale (enumberated variable)
  detSettings.Scale = ZOSAPI.Analysis.Settings.DetectorViewerScaleTypes.Linear;

  % Set the Smoothing (integer value)
  detSettings.Smoothing = 2;

  % Select the Maximum Plot Scale (double value)
  detSettings.PlotScaleMaximum = 20.0;

  % Save to an output file (string value)
  detSettings.OutFile = 'Detector_7_Image.JPG';

  % Apply the settings
  detector.ApplyAndWaitForCompletion();

ZOSAPI.Editors.NCE.INonSeqEditor

The INonSeqEditor interface provides us with several properties that allow us to immediately extract detector data without needing to open a Detector Viewer. This is similar in functionality to the NSDD optimization operand except here, the data will be pulled as a full matrix of information, instead of as a single value.

For a Detector Rectangle, one of the properties we can use is GetAllDetectorDataSafe. This property requires us to declare an array to store the data, and asks us to provide two inputs: detector number and data type. The detector number corresponds to the object number in the NSCE, and the data type refers to flux, flux/area, or flux/solid angle. The type of data you pull (Incoherent vs Coherent) will be given by the property you choose. GetAllDetectorDataSafe will deliver incoherent. For coherent data, use GetAllCoherentDataSafe.

Here is an example in Python of how this property can be utilized. This will pull flux/area data for detector 7. Detector 7 has the parameter Data Type set to '0', so I will get a matrix of Incoherent Irradiance data.

TheNCE = TheSystem.NCE

detector7 = TheNCE.GetAllDetectorDataSafe(7,1)

data7 = np.flipud(detector7)

plt.imshow(data7)

There are several other properties for this type of data extraction, and they are all in the INonSeqEditor Interface:

I am using the ZOS-API in standalone mode in Python. I've turned the detector output to some valid array with the DoubleToNumpy() function, but the results are non-sensical. Even though the output data are 500x500 (this is my detector rectangle pixel numbers), this can't be the color plot I see in the detector viewer, it seems as only one column is retrieved when you plot it. In addition, the data is non-sensical. I defined 2 detectors rectangle in the NSC editor as I want to plot the false color plots accordingly, data type=0 for incoherent data, color = 2 for false color etc, but this doesn't work. 

detector_output = TheSystem.NCE.GetAllDetectorDataSafe(4, 1)


detector_input = TheSystem.NCE.GetAllDetectorDataSafe(final_no_objects, 1)

data_output = zosapi.DoubleToNumpy(detector_output)


data_input = zosapi.DoubleToNumpy(detector_input)

peak_out = np.max(data_output)

peak_in = np.max(data_in)

The peak values for the input and output are 226 and 180, but when I open the zemax file and read the false color plots of the incoherent data, these values are around 60 and 50. Anyway, the exact values don't matter, only that these are not the same.

Please could you also explain to me why the data type even though it's 0 for incoherent irradiance, it becomes 1 in the GetAllDetectorDataSafe() second argument, that in the ZOS-API help manual is referred vaguely as int Data. At first I thought it was supposed to be the data type, and had set it to 0.

Edit 1: I assume that this Data parameter follows the same rules as the respective field in NSDD command, the field Data. I tried to do what I need to do with a ZPL macro and set #Pix number to -1 for the max value. There is a discrepancy again between what I see in the detector viewer and what the command reads. Why is that? Thank you.

Edit 2: I found out that this discrepancy stems from smoothing the data. Even though I have set the same smoothing in the detector viewer and the respective field in the NSC editor for the Detector Rectangle, when I calculate it with the NSDD command, the results are those without any smoothing. This is such a strange behavior. Have I missed a step?

ps. I am using an older version, and example 8 is not included. So, please don't simply refer me to it. I am sorry for the inconvenience.

Ally,

I’m afraid parts of this feature are broken

 % Select the Data Type we want (enumerated variable)
  detSettings.DataType = ZOSAPI.Analysis.DetectorViewerShowDataTypes.CoherentIrradiance;

The above does not work for me.  Any clues?

Best,

Brian

Hi Brian,

For the DataType to be set to Coherent Irradiance, you need to also have the ShowAs set to something that supports Coherent Irradiance, namely one of the 2D data types such as Grey Scale or False Color.  If you have the ShowAs set to something like FullListing, TrueColor or GeometricMtf, then although it looks like you’re setting the DataType to CoherentIrradiance, OpticStudio will not accept this value.

Also, you need to make sure the detector is set to a Detector Rectangle; no other detector type can calculate and display coherent irradiance.

Attached is a sample Python code which creates the following tilt fringes from 2 Source Ellipses and a Detector Rectangle (using 22.2):

@MichaelH  - thanks for the feedback.  There seems to be an issue with the enumerated data type.  A simple “echo back” as in the code below produces unexpected results.

TheSystem = TheApplication.PrimarySystem;

TheSystem.MakeNonSequential();

objNonSeq = TheSystem.NCE.AddObject;
objNonSeq.ChangeType(objNonSeq.GetObjectTypeSettings(ZOSAPI.Editors.NCE.ObjectType.DetectorRectangle));

analysisDetector = TheSystem.Analyses.New_Analysis(...
    ZOSAPI.Analysis.AnalysisIDM.DetectorViewer);
settingsDetector = analysisDetector.Settings;

listTypes = {...
    ZOSAPI.Analysis.DetectorViewerShowDataTypes.IncidentFlux, ...
    ZOSAPI.Analysis.DetectorViewerShowDataTypes.AbsorbedFlux, ...
    ZOSAPI.Analysis.DetectorViewerShowDataTypes.AbsorbedFluxVolume, ...
    ZOSAPI.Analysis.DetectorViewerShowDataTypes.IncoherentIrradiance, ...
    ZOSAPI.Analysis.DetectorViewerShowDataTypes.CoherentIrradiance, ...
    ZOSAPI.Analysis.DetectorViewerShowDataTypes.CoherentPhase, ...
    ZOSAPI.Analysis.DetectorViewerShowDataTypes.RadiantIntensity, ...
    ZOSAPI.Analysis.DetectorViewerShowDataTypes.RadiancePositionSpace, ...
    ZOSAPI.Analysis.DetectorViewerShowDataTypes.RadianceAngleSpace ...
    };

for iType = 1:length(listTypes)
    typeCurrent = listTypes{iType};
    disp("Attempt to set type to: " + char(typeCurrent.ToString));
    settingsDetector.DataType = typeCurrent;

    disp("..Current Type: " + char(settingsDetector.DataType.ToString));
end

Hi Brian,

I think you’re correct that there is an issue with how the enumeration is reported when you read it out. However, applying it still works as intended. So, for example, I can apply the Incoherent Irradiance data type to a Detector Rectangle with the following code:

detSet.DataType = ZOSAPI.Analysis.DetectorViewerShowDataTypes.IncoherentIrradiance;

Applying within an Interactive Extension, I see that this works. The setting updates to “Incoherent Irradiance”. However, if I ask the API to report to me the current data type, this is what I receive:

I have noticed a bug like this before with respect to how ShowAsType is reported. I will check in on that report to see if the developers have any updates. Unless @MichaelH has any other thoughts?

gEdit to note: I’m not using ApplyAndWaitForCompletion because I am working in Interactive Mode so can view the detector’s progress myself]

Hi Brian and Allie,

Thanks for the clarification.  Brian, you’re not going to like this answer, but it’s “not a bug”, but rather “non-ideal practices” with both the decades old OpticStudio source code and your Matlab implementation.  A Enum is simply a collection of a fixed number of variable options and when implemented in .NET, the variable Name is assigned an integer Value.  The name and value can be accessed via the Enum.GetName() and Enum.GetValue() methods.  Now, the best practice for creating Enums is to assign a unique integer value to each name (this is the default method in .NET if a value is not assigned and just the values are listed), but .NET allows you to reuse values for different names. 

Based on legacy OpticStudio code, the ZOS-API reuses the values for different names.  If you actually look at what each Enum name for the DetectorViewerShowDataTypes is mapped to, you can see that there are 19 Names but only 6 Values:

import zosapi
from System import Enum

# connect to OpticStudio to get the Enums
zos = zosapi.App();

# get the values and names of enums
__showdata__ = zos.ZOSAPI.Analysis.DetectorViewerShowDataTypes
integers = Enum.GetValues(__showdata__);
names = Enum.GetNames(__showdata__)

# loop through each name is the enum
print('#     Enum Value : Name')
for idx, (i, n) in enumerate(zip(integers, names)):
    print('%3i | %10i : %s' %(idx + 1, i, n))

The original reason why there are multiple values for “0”, “1”, etc is because each one of these values is unique based on combining with another setting in the Detector Viewer.  If you cycle through the settings via the GUI, you will notice that the most values in the Show Data dropdown will be 6 and these values change based on other settings.  In the Show Data dropdown, you will never have two names with the same value.  So, based on the logic tree in the source code, this is not a bug and I doubt this will be changed in the ZOS-API.  I recommend using the .NET Enum namespace and directly manipulate the enum rather than casting it to an integer.  

  TheSystem = TheApplication.PrimarySystem;
  
  % Open the Detector Viewer
  detector = TheSystem.Analyses.New_Analysis(ZOSAPI.Analysis.AnalysisIDM.DetectorViewer);

  % Open the settings of the Detector Viewer
  detSettings = detector.GetSettings();

  % Select which detector we care about
  detSettings.Detector.SetDetectorNumber(7);

  % Select data to Show As type (enumerated variable)
  detSettings.ShowAs = ZOSAPI.Analysis.DetectorViewerShowAsTypes.FalseColor;

  % Select the Data Type we want (enumerated variable)
  detSettings.DataType = ZOSAPI.Analysis.DetectorViewerShowDataTypes.CoherentIrradiance;

  % Select the scale (enumberated variable)
  detSettings.Scale = ZOSAPI.Analysis.Settings.DetectorViewerScaleTypes.Linear;

  % Set the Smoothing (integer value)
  detSettings.Smoothing = 2;

  % Select the Maximum Plot Scale (double value)
  detSettings.PlotScaleMaximum = 20.0;

  % Save to an output file (string value)
  detSettings.OutFile = 'Detector_7_Image.JPG';

  % Apply the settings
  detector.ApplyAndWaitForCompletion();

TheNCE = TheSystem.NCE

detector7 = TheNCE.GetAllDetectorDataSafe(7,1)

data7 = np.flipud(detector7)

plt.imshow(data7)

Hi, I am a newer to ZOS-API. How can I use ZOS-API to extract the detector data with filter string in INonSeqEditor rather than opening a Detector Viewer? thanks.

Hi @Roger.Ouyang 

Apologies for the delay in my response!

At this time, the only way to apply filter strings in the API is by applying them to a ZRD file (either in the Ray Trace Control dialog or in the ZRD Reader), or by applying them in the Detector Viewer settings. This is exemplified in sample 10 within the ZOS-API Sample Code folder.

Let me know what questions you have about that!