TravisAllen747

Introduction

For my course project, I wanted to learn more about the Image Systems Evaluation Toolbox (ISET) while incorporating some of my experience with optics and an optical design program known as Zemax OpticStudio. Several years ago (potentially 10-12 years ago), others had developed a basic capability for bringing lens parameters, as defined in Zemax, into ISET for use as "raytrace optics". The current implementation is pretty straightforward, but it is a bit dated. When this method was originally implemented, there was no inherent interoperability between Opticstudio and Matlab (the programming software that runs ISET). Now, in 2017, OpticStudio has options for interfacing with several external programs, including Matlab.

Since I was working alone and fairly unfamiliar with both ISET and the current method for interfacing with Opticstudio, my project began with the primary goal of taking a lens system in Zemax Opticstudio and importing it into ISET using the old method. Since the scripts that did this had not been used by anyone in quite some time, my plan was to work through each part of the process and fix anything that didn't work and clean up code that was unnecessary. My hope was to learn more about both ISET and Zemax OpticStudio along the way.

The second (stretch) goal was to try and modify the way the PSF's are currently applied in the raytrace optics chain in ISET. Currently, the PSF values are interpolated between field heights and wavelengths. A potentially better method, as described by Professor Wandell, would be to parameterize the PSF's as Gaussians and interpolate between those defining parameters (like variance). Unfortunately, I spent quite a bit of time on the first goal and was unable to make any meaningful progress on this second goal.

Background

In the Image Systems Evaluation Toolbox (ISET) in Matlab, one can simulate each part of an image capture chain: from the scene, to the optics, to the sensor, to the processor, and, finally, to the display. This project focused on the "optics" portion of that chain, which essentially transforms the scene radiance to the optical irradiance, which can then be captured by the simulated sensor. One lesser used method in ISET for describing and implementing this optics transformation system is called the "raytrace" method. The raytrace optics scripts and methods in ISET tend to revolve around output from Zemax Opticstudio, optical systems design software that is widely used in the industry. Since these scripts are rarely used, some of the code has become outdated and needed to be cleaned up.

The main file that needed to be updated was the Zemax Opticstudio export macro. When the capability to import raytrace lens parameters from a program like OpticStudio was originally conceived, there was no straightforward method for exporting parameters into external programs (like Matlab) for manipulation. However, Zemax did allow for macro programming in order to rapidly execute tasks. So, about 10 years ago, the ISET team wrote a macro that went in, executed several commands, and exported data in a well-defined format. This macro is written in the .ZPL format which, when run, will output wavelength and field height-dependent Point Spread Functions (PSF's), relative illumination, and distortion parameters for the optics system currently loaded in OpticStudio. This macro had a lot of obsolete keywords that needed to be updated and a few parts that needed to be modified to work with more general lens files.

On the ISET side, there are a series of scripts that need to be implemented to import the data from the files created by the macro into a usable format in Matlab. There were several files that needed to be updated to ensure that the data was transferred into ISET in a correct manner.

Methods / Updates Made

Zemax OpticStudio Export Macro

The import macro I focused on for this project was the ISET_RT_ZEMAX_2D.ZPL macro. There is a 3D version, but, since I am uncertain as to whether or not it is currently implemented in ISET, I focused on the 2D file. Throughout the macro, there were obsolete keywords and formatting issues that needed to be addressed. I made these changes and added comments throughout in order to document them. There was also an issue with an initial RAYTRACE command that appeared to rely on the original lens file to have a few different field heights available by default (which is not always the case). Additionally, since ISET is expecting FFT PSF output, and the macro had been changed to output a Huygen PSF, I changed it back to the expected format. ISET import scripts are literally hard-coded to read the FFT PSF file format in the current implementation. I also added back into the script the ability to output grid distortions, which had been part of an early version of the macro but was removed at one point. I commented out this portion of the script because it does not appear to be used currently in ISET, but these files may be useful at a later date and I wanted to capture that.

ISET_RT_ZEMAX_2D.ZPL has now been fully updated to work with Zemax OpticStudio 17.5 and should execute correctly when placed in the Zemax/Macros folder.

The macro generates a set of files all ending with a ".dat" extension. They all have a "basename" which is stripped from the lens file name. For the purposes here, I'll use the basename for the lens I demonstrated this process on: AB0618MG. The output files are the following:

1. <basename>_2D_PSF_Fld<FldHtIdx>_Wave<WavelengthIdx>.dat (PSF Data Files -- lots of them -- # wavelengths x # field hts)
2. <basename>_RI_.dat (Relative Illumination data)
3. <basename>_DI_.dat (Distortion Data)
4. <basename>_CRA_.dat (Chief Ray Angle Data)
5. <basename>_GridDistortion_Fld<FldHtIdx>_Wave<WavelengthIdx>.dat [if enabled] (Grid Distortion Data Files -- same number as PSF files)

The macro requires some input from the user. There is a section near the top with 6 input parameters: PSF Size, Grid Spacing (for the PSF), Number of Wavelengths, Wavelength Min/Max, and Number of Image Heights (from 0 to the Max FOV). I would also recommend taking a look at the comments at the top of the file since they contain some useful information and instructions to ensure the macro will work when executed. Taking a few minutes up front will likely prevent hours of frustration later.

Once the parameters are changed and you have read the header information/instructions, save the macro and place it in the correct directory. See Figure 1 for an illustration of where to put this file.

Figure 1: Where to Place the Macro

It's fairly simple and straightforward to run the macro. Once you have updated those parameters and placed the file in the correct directory, you then go into Zemax OpticStudio and run the script using the commands as illustrated in Figures 2 and 3.

Figure 2: How to Run the Macro (Step 1 of 2)

Figure 3: How to Run the Macro (Step 2 of 2)

When you execute the macro, you should see a window pop up with a bunch of output as can be seen in Figure 4.

Figure 4: Example of the Macro Running

Once the macro is finished running, the exported files will reside in a directory inside of Zemax/Samples. This directory is created based on the name of the lens (here AB0618MG).

Figure 5: Location of the Exported Files

One Note: while the macro is capable of creating this directory on its own, it will NOT create the ISETPARMS.txt file that it needs to write to within this directory. For that reason, it makes sense to create the directory and place a blank .txt file in it with the name ISETPARMS.txt. Then there should be no errors.

ISET Import Scripts

When importing the exported files from OpticStudio, the first step is to make sure they are in the correct directory. I personally had to transfer the files from one system to another, so the "baseLensFileName" parameter in the ISETPARMS.txt file did not point to the correct directory for import. Thus, before attempting to import, go into the ISETPARMS.txt file and make sure that the "baseLensFileName" points to the correct location of the lens file and that all of the ".dat" files output by the macro are in that same directory. See Figure 6 for a screenshot of both the correct location for the files and how the ISETPARMS.txt file should look.

Figure 6: Importing into ISET -- File Location, ISETPARMS.txt, and the Import Script

When using the rtImportData.m import script, you have to designate the location of the ISETPARMS.txt file. From there, the scripts should do the rest of the work as long as everything is in the correct place. At the end of the script, you should be asked to save the data as a ".mat" file. Once you do that, you should not need to run the import script again.

Some of the changes I had to make to the ISET files in order to ensure that the import was successful were:

1. Changing the file format in rtFileNames.m (they had been changed in the macro in January 2014, but the import script had never been updated to reflect this change).
2. Updating the rtImportData.m file to account for a logic error in the reshape() method (wavelength and field height were swapped).
3. The logic error from #2 flowed into DIInterp.m and RIInterp.m, which interpolate between the sampled distortion and relative illumination data, respectively. I had to swap the wavelength and field heights in both of these files.
4. I changed the polynomial for the polyfit() function in rtGeometry.m to be an 8th degree polynomial. The comments said this was a pretty good number, but had it as a 6th degree beforehand. I changed this while troubleshooting the logic error for parts 2 and 3. This was less of an essential change and may not have a large impact on the output.

I have also created a basic Zemax OpticStudio import tutorial script called t_ZemaxImport.m so that people can understand, on a very basic level, how to import these files. That is included with the code.

Appendix

You can write math equations as follows: $y=x+5$

You can include images as follows (you will need to upload the image first using the toolbox on the left bar.):