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.

Batch Processing of Ray Trace Data using ZOS-API in MATLAB

An update to the ZRDLoader.dll to include both batch processing of sequential ray trace (direct or normalized, polarized or unpolarized) and batch processing of non-sequential ZRD files using ReadNextSegmentFull() method.
Michael Humphreys
04/24/2018
ZOS-API

The RayTrace.dll combines the legacy ZRDLoader.dll, incorporating the new ReadNextSegmentFull method, along with the 4 IBatchRayTrace interfaces in sequential mode.  The new 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 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, 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 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 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.
 

Matlab 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 MATLAB file can be downloaded and run without modification.  The RayTrace.dll needs to be placed in the same folder as any MATLAB 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

  1. MATLAB_BatchRayTrace_Direct.m – (SEQ Direct). That example 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.
  1. MATLAB_BatchRayTrace_Normalized.m – (SEQ Norm) ). That example is an example of use of the IRayTraceNormUnpolData interface. It 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.
  1. MATLAB_ZRDLoaderFull.m – (NSC ZRD). That example 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

  1. MATLAB_BatchRayTrace_Surface_AOI.m – (SEQ Direct). That example 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.
  1. MATLAB_BatchRayTrace_Ex22_Performance_Comparison.m – (SEQ Norm). That example 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.  
  1. MATLAB_ZRD_Pixelated_Detector_xybin.m – (NSC ZRD). That example 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 on 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