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. Professors Wandell and Farrell, as well as the course TA Trisha Lian, all suggested I focus my project on the area where these two software packages currently overlap.
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:
- <basename>_2D_PSF_Fld<FldHtIdx>_Wave<WavelengthIdx>.dat (PSF Data Files -- lots of them -- # wavelengths x # field hts)
- <basename>_RI_.dat (Relative Illumination data)
- <basename>_DI_.dat (Distortion Data)
- <basename>_CRA_.dat (Chief Ray Angle Data)
- <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.
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.
When you execute the macro, you should see a window pop up with a bunch of output as can be seen in Figure 4.
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).
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.
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:
- 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).
- Updating the rtImportData.m file to account for a logic error in the reshape() method (wavelength and field height were swapped).
- 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.
- 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.
Results
I went ahead and ran the macro with 33 wavelengths between 400nm and 720nm (that's a spacing of 10nm) and 21 field heights (from 0 out to the max FOV).
I was able to fully import the exported .dat files into Matlab. I then created a relatively high resolution scene of gridlines (see Figure 7).
After creating the scene, I computed an optics object using the imported raytrace data from Zemax OpticStudio and displayed the simulated irradiance (see Figure 8).
One might notice that I used a pretty high FOV for the scene (20.0 degrees). This is because the greater the FOV, the more of the sampled field heights I would use for the PSF interpolation. The tradeoff is that a higher FOV means fewer PSF samples per scene resolution. Thus, the resolution of the scene had to be increased in order to get an acceptable spatial sample rate for the PSFs. However, with a higher sample rate came greater computational load (and greater compute times). This is a trade-off that I've come to appreciate and that I believe could be looked at closer by someone in the future in order to find a more optimal balance.
For the second (stretch) goal for this project, I was not able to make any substantive progress on updating the method for interpolation of the PSF's for ISET's optics modeling process. It appears the the code that would need to be understood and modified is found in rtPrecomputePSFApply.m.
Conclusions / Next Steps
While doing this project, I learned a lot about how both Zemax OpticStudio and ISET work. I am more confident working with both tools and excited to work with them more in the future. While I was unable to do much beyond just get the capability back to where it was 12 years ago, I do believe that there is a lot of potential for this capability in the future.
As far as I can tell, there is now a decent, inherent capability to transfer data between Zemax OpticStudio and Matlab. If one were to dedicate some time to this endeavor, I believe the old macro export / script import method could eventually be done away with. However, many of the raytrace scripts in ISET are expecting specific kinds of input. So the ISET raytrace script ecosystem would likely need to be overhauled. While this may be more work, I think there may be some great benefits to doing this in the future.
Another area ripe for additional exploration is the tradeoff between the field of view (FOV) and scene sampling (scene resolution). As mentioned in the results section, this is an area where I'm sure additional work could be done to better understand what's happening and what settings might be optimal for a raytrace optics model.
In addition to looking at the FOV vs. Scene Resolution tradeoff, it might be a good idea to go back and look at how the geometric distortion is being calculated and used. After looking at the Zemax macro, it looks to me as if it assumes radial symmetry for the lens system. While this may be the case for many lenses, it's certainly not true for all of them. Might be something work looking at closer.
And lastly, while I did not get a chance to fully explore changing the method for PSF interpolation, I definitely see the merit in someone going and taking a closer look at this problem. I know Zemax does this exact scene simulation in OpticStudio, so it might be worth it for a future project to have someone go in and try a few different methods, show the comparisons between these methods, and also do some comparisons with the Zemax OpticStudio method. These were suggestions by Professor Wandell and Trisha that I believe have a lot of merit and I wish I had been able to pursue myself.
At the end of the day, I learned a lot, enjoyed tinkering around with all of the code, and hope that my contributions to the code base can be used for some good in the future.
Appendix
The following is a list of relevant project files:
- This is a PDF of the final presentation I gave:
- This is a zip file containing the edited macro, the tutorial script, and the edited ISET rt scripts: