Matlab script to group rays from ZRD file to separate paths
This Matlab function imports a raw Zemax ray database stored in ZRD file, groups the rays into distinct paths based on i) the exact same sequence of objects hit AND ii) ray events (such as reflection, splitting etc.), and outputs this information in a form of graphs, human-readable variables and, most importantly, a summary table storing each path in descending total power, object sequence, total ray events and so on, which can be further processed either using Matlab's native capabilities, or exported and processed using Excel or a simple text editor.
It DOES NOT need Zemax to be installed onto your system and does not use any API to connect to it. It is a completely standalone function.
The need for this custom function came clear during one project at work as the native Zemax ray paths tool was insufficient. As per official documentation, it now groups it based on the sequence of FACES the rays hit. In contrast, this function retains a full low-level list of objects and events. It also stores all other ray information (such as phase, direction cosines etc.) for later use, shall the user might need it. At the same time, it provides a high-level overview of interactions in the table. I hope it would be useful for advanced analysis and I would gladly update it based on the feedback.
Although this function is shared free for use and any modification as you might see fit, I would appreciate it if you would quote me in case you are going to use it for any non-personal tasks.
Page 1 / 1
Hi, Kris. Nice work, and thanks for sharing it with everyone.
In case you missed it, we have added face support to our ray databases and path analyses, highlighted below. And maybe we could contact you for some feedback on one of our new tools coming in the 25R1 release in January.! We are always looking for customers who are willing to exercise our new features.
Regards,
Erin
Dear @Erin.Elliott, how could I upload an updated version of my code? Should I simply modify the original post to make sure the newest version stays at the top of page?
Yes, edit the post if the system will let you. If not, you may need to attach it to a new comment, here.
Hello @Kris ,
Thank you for proving this to the community.
I’m attempting to use it for the first time and receive:
I’ve tried all three options: uncompressed full data, compressed basic data, and compressed full data. Each returns a different version number, but all have the same error.
I’m using 2024 R2.02. Must I use an earlier version?
Thank you,
John
@Kris , @John.Hygelund - If you have time, would you please try out our new Sequence Selector? It’s in the latest release, under Help/Feature Experiements/Sequence Selector! And please share your feedback here:
Hello @Kris ,
Thank you for proving this to the community.
I’m attempting to use it for the first time and receive:
>> &paths_table,paths]=zemax_group_paths('553-0033-03_wGlue_scan1_v4.1wAOI.ZRD'); ZRD file version is 2004. Error using zemax_group_paths (line 55) Only UFD format is supported at this moment.
I’ve tried all three options: uncompressed full data, compressed basic data, and compressed full data. Each returns a different version number, but all have the same error.
I’m using 2024 R2.02. Must I use an earlier version?
Thank you,
John
Could you either share your UFD file (full uncompressed), or, due to IP concerns, run a simulation with merely 1 ray and share it?
@Kris , @John.Hygelund - If you have time, would you please try out our new Sequence Selector? It’s in the latest release, under Help/Feature Experiements/Sequence Selector! And please share your feedback here:
This sounds interesting @Erin.Elliott! I would love to try it out but currently, this version is not allowed in my company. Shall there be a chance to install it, I will definitely try it out.
@John.Hygelund It looks like you’re using a ZRD from Ansys OpticStudio 2024 R1 or more recent; OpticStudio bumped up the ZRD version from 2002 to 2004. In 2024 R1, there were several values added to each ray segment including flags for TIR, OPL, and diffraction orders. The Matlab script uses the published UFD version in the old Help Files (2002) but the current Help Files has an updated struct. Basically, each segment now has an additional 24 bytes per segment:
double optical_path_w
double optical_path_lu
int order_x
int order_y
You can modify the Matlab code around line 103 to add these new values to the struct and update the rest of the code accordingly (also update the version check around line 44).
Hello @Kris and @MichaelH
Thanks for your responses!
It sounds like my newer version with the extra database values is the reason. I’m on 2024 R2.02.
I’ll try the suggested edits when I’m back in the office.
I wrote a simpler MATLAB script that parses the saved .txt output from a ray database viewer. It creates a #raysX#segment.property structure named by headings in the text file. It also calculates and adds the AOI (angle of incidence) in degrees for each segment. This is working for my current needs (and I'm happy to share if interested).
FYI, my workflow is to run a trace saving a database file with the detector filter on. Then, I run path analysis and step through the paths sorted by energy (using the nifty spacebar shortcut). When I find a potentially problematic path, I use the automatic _# path filter in the ray database viewer and save the text file. I then run my MATLAB script on the text file and can plot things like segment AOI vs. intensity to check coatings, etc.
Thanks!
@John.Hygelund It looks like you’re using a ZRD from Ansys OpticStudio 2024 R1 or more recent; OpticStudio bumped up the ZRD version from 2002 to 2004. In 2024 R1, there were several values added to each ray segment including flags for TIR, OPL, and diffraction orders. The Matlab script uses the published UFD version in the old Help Files (2002) but the current Help Files has an updated struct. Basically, each segment now has an additional 24 bytes per segment:
double optical_path_w
double optical_path_lu
int order_x
int order_y
You can modify the Matlab code around line 103 to add these new values to the struct and update the rest of the code accordingly (also update the version check around line 44).
Good note about the newer version of the ray database files @MichaelH, I will surely update it in my future releases.
One note, is the new file format documented officially somewhere @MichaelH?
I am glad about the documentation @, however, the variables double optical_path_w, optical_path_lu and int order_x, order_y are not mentioned there. May you describe them in your own words, if possible?
Hi, @Kris. I’m asking about this now. We’ll update the descriptions in the Help file to include it, too.
@Kris - The “order” terms are diffraction orders, I’m fairly sure, and we use a value of 100 to indicate not diffracted. And the “optical path w” is optical path length (OPL) at the wavelength of that particular ray, “optical path lu” is the OPL in lens units.
@Kris - The “order” terms are diffraction orders, I’m fairly sure, and we use a value of 100 to indicate not diffracted. And the “optical path w” is optical path length (OPL) at the wavelength of that particular ray, “optical path lu” is the OPL in lens units.
Thanks for your responses @Erin.Elliott, I am intrigued to see those features in new editions of Zemax.
I am delighted to announce that the function has been updated and now supports ZRD both file versions 2002 and 2004, reading and writing!
Hopefully this would be especially useful to you @John.Hygelund.
