When a value is designated as a "double" or "int", it is asking for a numerical input from the user. Conversely, an "out double" or "out int" variable is one that is output as a result of the user inputs. This distinction allows a single API command to output multiple variables in one call.





Some commands that use this syntax are found in the IBatchRayTrace interface: GetDirectFieldCoordinates and GetPhase.

GetDirectFieldCoordinates is a "bool" type while GetPhase is a "void" type. This means that in addition to the "out double" variables, GetDirectFieldCoordinates will also output a true or false statement indicating whether it has successfully evaluated or not. It will therefore require an additional "out" variable to be defined in the beginning of the call. That is represented by "result" below.





In Matlab, these two commands may be evaluated by using the following structure:


 

raytrace = TheSystem.Tools.OpenBatchRayTrace();


% GetDirectFieldCoordinates


% Result is the Boolean output, "X, Y, Z, L, M, N" are the "out double" variables as defined in the syntax guide


[result,X,Y,Z,L,M,N] = raytrace.GetDirectFieldCoordinates(wavenumber, ZOSAPI.Tools.RayTrace.RaysType.Real, hx, hy, px, py);


% GetPhase 


% Result is the Boolean output, "exr, exi, eyr, eyi, ezr, ezi" are the "out double" variables as defined in the syntax guide 


[exr,exi,eyr,eyi,ezr,ezi] = raytrace.GetPhase(L, M, N, jx, jy, xPhaseDeg, yPhaseDeg, intensity); 


raytrace.Close();

Sample 5 – "Parsing a ZRD File" – provides an example of using "out" variables from the IZRDReaderResults interface to obtain ZRD information. 

Generally, the ZOS-API syntax is comparable between Matlab and Python. In this instance, however, Python has a different method for obtaining 'out' variables. I will list the steps to obtain these values below. In this example, we will be extracting the values for the command GetGlobalMatrix which accepts one input, and provides 12 outputs:

1. At the top of the code, add the line from System import Enum, Int32, Double

2. Before calling the command GetGlobalMatrix, add the line sysDbl = Double(1.0) Note: this is required because Python NET requires all arguments to be passed in as reference, so we need to have placeholders

3. Now, to call GetGlobalMatrix, use this line: output = TheLDE.GetGlobalMatrix(nsur-1, sysDbl, sysDbl, sysDbl, sysDbl, sysDbl, sysDbl, sysDbl, sysDbl, sysDbl, sysDbl, sysDbl, sysDbl)

The output for the code is shown below. I am using Visual Studio to provide a side-by-side comparison of the code (left) with the local variables (right)

The results match up with what we see in OpticStudio for the same file at surface 7:

Please note: this is PythonNET syntax. PythonNET is the preferred method to connect to the API and was introduced as the default boilerplate in OpticStudio 20.2.