Skip to main content

Matlab script to group rays from ZRD file to separate paths


Kris
  • Infrared
  • 13 replies

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.

Did this topic help you find an answer to your question?

17 replies

Forum|alt.badge.img+1
  • Zemax Staff
  • 51 replies
  • November 5, 2024

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


Kris
  • Author
  • Infrared
  • 13 replies
  • November 20, 2024

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?


Forum|alt.badge.img+1
  • Zemax Staff
  • 51 replies
  • November 20, 2024

Yes, edit the post if the system will let you.  If not, you may need to attach it to a new comment, here.


John.Hygelund
Fully Spectral
Forum|alt.badge.img+1
  • Fully Spectral
  • 71 replies
  • February 22, 2025

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


Forum|alt.badge.img+1
  • Zemax Staff
  • 51 replies
  • February 24, 2025

@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: 
 

 


Kris
  • Author
  • Infrared
  • 13 replies
  • February 26, 2025
John.Hygelund wrote:

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
  • Author
  • Infrared
  • 13 replies
  • February 26, 2025
Erin.Elliott wrote:

@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.


MichaelH
Ansys Staff
Forum|alt.badge.img+2
  • Ansys Staff
  • 342 replies
  • February 26, 2025

@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).


John.Hygelund
Fully Spectral
Forum|alt.badge.img+1
  • Fully Spectral
  • 71 replies
  • February 26, 2025

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!


Kris
  • Author
  • Infrared
  • 13 replies
  • February 27, 2025
MichaelH wrote:

@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.


Kris
  • Author
  • Infrared
  • 13 replies
  • February 27, 2025

One note, is the new file format documented officially somewhere ​@MichaelH?


Forum|alt.badge.img+1
  • Zemax Staff
  • 51 replies
  • February 27, 2025

@Kris  - The new file format appears in the online Help files, here:
https://ansyshelp.ansys.com/public/account/secured?returnurl=/Views/Secured/Zemax/v242/en/OpticStudio_User_Guide/OpticStudio_Help/topics/The_ZRD_Uncompressed_Full_Data_Format_UFD.html
 

Note that “int hit_face” is also new. 

typedef struct{unsigned int status;int level;int hit_object;int hit_face;int unused;int in_object;int parent;int storage;int xybin, lmbin;double index, starting_phase;double x, y, z;double l, m, n;double nx, ny, nz;double path_to, intensity;double phase_of, phase_at;double exr, exi, eyr, eyi, ezr, ezi;double optical_path_w, optical_path_lu;int order_x, order_y;} RAYPATH;

Kris
  • Author
  • Infrared
  • 13 replies
  • February 28, 2025

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?


Forum|alt.badge.img+1

Hi, ​@Kris.  I’m asking about this now. We’ll update the descriptions in the Help file to include it, too.


Forum|alt.badge.img+1

@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
  • Author
  • Infrared
  • 13 replies
  • March 4, 2025
Erin.Elliott wrote:

@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.


Kris
  • Author
  • Infrared
  • 13 replies
  • March 17, 2025

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.


Reply


Cookie policy

We use cookies to enhance and personalize your experience. If you accept you agree to our full cookie policy. Learn more about our cookies.

 
Cookie settings