This article will demonstrate how to use the Zemax OpticStudio Application Programming Interface (ZOS-API) for accessing the Ray Database (ZRD) using the ZRDLoader.dll in Matlab or Python. This article include Matlab examples for batch processing of sequential ray trace (direct or normalized, polarized or unpolarized) and Matlab and Python examples for batch processing of non-sequential ZRD files using ReadNextSegmentFull() method.

Authored By Michael Humphreys

Downloads

Article Attachments

What is "RayTrace.dll"?

The RayTrace.dll combines the legacy ZRDLoader.dll, incorporating the ReadNextSegmentFull method, along with the 4 IBatchRayTrace interfaces in sequential mode. The DLL includes the following interfaces and inherited methods from the ZOSAPI.Tools.RayTrace namespace:

• IRayTraceDirectPolData (sequential):
  In that interface you can perform a batch polarized ray trace, using direct x/y/z coordinates; this is similar to the DDE ray trace command, mode 3. That interface is an interface of IBatchRayTrace.
   
• ​IRayTraceDirectUnpolData (sequential):
  In that interface you can perform a batch unpolarized ray trace, using direct x/y/z coordinates; this is similar to the DDE ray trace command, mode 1. That interface is an interface of IBatchRayTrace.

• IRayTraceNormPolData (sequential):
  In that interface, you can Perform a batch polarized ray trace, using normalized pupil coordinates; this is similar to the DDE ray trace command, mode 2. That interface is an interface of IBatchRayTrace.

• IRayTraceNormUnpolData (sequential):
  In that interface you can perform a batch unpolarized ray trace, using normalized pupil coordinates; this is similar to the DDE ray trace command, mode 0.
• IZRDReader (non-sequential):
  Setup and run RayDatabaseReader in Matlab while reading each segment’s value in a C# dll.

The DLL is only designed to pass the raw values for each ray or segment back to MATLAB or Python as a property of the declared object; no calculation, consolidation or analysis is performed within the DLL. The main purpose of the DLL is to hand-off time intensive for loops from MATLAB or Python, which handles the very inefficiently, to a native compiled C# program. The C# program then passes back the raw values after looping through all the results back to MATLAB or Python for final processing.

For sequential interfaces, there are 2 methods which require the use of for loops: AddRays() and ReadNextResults().  Therefore, to achieve maximum efficiency, both adding rays and reading results need to be handled by the DLL. There are 2 examples of efficiently creating a square grid and dithered rays in each sequential example. Based on the desired ray pattern (if different from above), a similar approach of using MATLAB’s native array indexing should be used to add rays to the DLL.

The results which are passed back to the MATLAB or Python object are the same properties listed for each interface’s most verbose output, either ReadNextResult() or ReadNextResultFull(), including the exact phrase and case. To efficiently utilize the results, one should use MATLAB’s array indexing rather than using for or while loops.

Examples using the DLL

There are 3 basic examples and 3 advanced examples which show how to use the RayTrace.dll for sequential direct, sequential normalized, and non-sequential ZRD ray tracing. Each file can be downloaded and run without modification. The RayTrace.dll needs to be placed in the same folder as any MATLAB or Python script that calls it. The source code for each C# file is also provided along with the Visual Studio solution used to generate the DLL. 

Basic files

• MATLAB_BatchRayTrace_Direct.m – (SEQ Direct).
  This is an example of use of the IRayTraceDirectUnpolData interface. It uses the function ReadDirectUnpolData from the RayTrace.dll (DirectUnpol.cs). It traces a footprint diagram to a given lens surface while plotting both the Clear Semi-Diameter and Mechanical Semi-Diameter.
  
  
• MATLAB_BatchRayTrace_Normalized.m – (SEQ Norm).
  This is an example of use of the IRayTraceNormUnpolData interface, which uses the function ReadNormUnpolData from the RayTrace.dll (NormUnpol.cs). It traces a square pattern of over 10,000 rays up to the image surface for a single field point in under 1 second.
  
• MATLAB_ZRDLoaderFull.m or PythonNET_ZRDLoaderFull.py – (NSC ZRD)
  This is an example of use of the IZRDReader interface. It uses the function ReadZRDData from the RayTrace.dll (ZRDLoaderFull.cs). It parses a ZRD file and determines the total power on a given detector.
  
  

Advanced files

• MATLAB_BatchRayTrace_Surface_AOI.m – (SEQ Direct).
  This is an example of use of the IRayTraceDirectUnpolData interface. It uses the function ReadDirectUnpolData from the RayTrace.dll (DirectUnpol.cs). It traces a grid of rays to a given surface in a system; uses the LMN direction cosine vector and Nxyz normal vector to calculate the angle of incidence at each XY point on the surface.
  
  
   
• MATLAB_BatchRayTrace_Ex22_Performance_Comparison.m – (SEQ Norm).
  This is an example of use of the IRayTraceNormUnpolData interface. It uses the function ReadNormUnpolData from the RayTrace.dll (NormUnpol.cs). It plots a full field spot diagram using a dithered ray pattern; can trace 10,000 rays in 1 second while the same file using native MATLAB for loops can plot 961 rays in over 4 seconds. Based on computer performance, uses can see up to a 40x speed increase.  
  
  
   
• MATLAB_ZRD_Pixelated_Detector_xybin.m – (NSC ZRD).
  This is an example of use of the IZRDReader interface. It uses the function ReadZRDData from the RayTrace.dll (ZRDLoaderFull.cs). It creates a new system with a Source Rectangle, a Slide object using “LETTERF.BMP” and a Detector Rectangle. The “F” pattern appears on a detector. Uses the ZRD file’s xybin property to sum the flux through each pixel and recreates a binned detector directly from a ZRD file without using the Detector Viewer Analysis Feature.
  
  
  
  

Troubleshooting

If you download the Visual Studio solution and get errors when compiling, ensure that the ZOSAPI and ZOSAPI_Interfaces references are correct. If you open the Solution Explorer, expand the References and you see a yellow warning symbol next to ZOSAPI and ZOSAPI_Interfaces, you will need to:

• Delete the current references (right click > Remove)
• Right click Reference and select Add References…
• Click Browse and the bottom and navigate to the OpticStudio install folder
• Use Shift+Click to select both ZOSAPI and ZOSAPI_Interfaces and click Add
• Click OK to add to solution
• Highlight both references, open the Properties and change Copy Local from True to False

KA-01651