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.

How to Draw Specific Rays in Zemax Layouts

This article explains:
  • How to draw desired rays in the Zemax OpticStudio Layouts via the RAYLIST
  • What the RAYLIST is
  • The difference between IMPLICIT and EXPLICIT methods for defining rays in the RAYLIST
  • How to use each format with visual aids
Dan Hill
Analysis Features

What is the RAYLIST?

The normalized field and pupil coordinates (Hx, Hy, Px and Py respectively) of a ray are often used to indicate to Zemax OpticStudio exactly which ray is desired for analysis. For example, the Single Ray Trace calculation (via The Analyze Tab > Image Quality Group > Rays and Spots > Single Ray Trace) requires the specification of Hx, Hy, Px, and Py, as do many of the Merit Function operands.


Although the single ray trace calculation and merit function operands can return very useful information about a given ray, it is also helpful to have a qualitative feel for how a specific ray traverses through your optical system. This very concept may be applied to the various layout plots in Zemax OpticStudio via the RAYLIST.

The layouts in Zemax OpticStudio (excluding the 2D Layout) support a number of different Ray Patterns, including XY Fan, X Fan, Y Fan, Ring, Random, Grid, and List. By choosing List as the “Ray Pattern”, the rays within the layout are traced according to a simple text file.


This text file is entitled, “RAYLIST.TXT,” and is located in the <Documents>\Zemax\Miscellaneous directory. Note that the filename and directory MUST remain the same. Any changes made to the filename or the directory in which it is saved will not be recognized by Zemax OpticStudio.

The RAYLIST.TXT file is simply of ASCII format, and supports two distinct methods for defining rays, summarized below and discussed in more detail in the next chapter.

IMPLICIT Rays are defined by the normalized pupil coordinates
EXPLICIT Rays are defined by their starting coordinates, direction cosines, and wavelength



IMPLICIT:  The implicit format for the RAYLIST.TXT file consists of two numbers on each line: one for the Px and one for the Py normalized pupil coordinates. The syntax is as follows:

Px Py

For example, in a rotationally symmetric system, the two meridional marginal rays are defined in the RAYLIST.TXT file by:


These specified rays are traced at each defined field and wavelength in the settings of the respective layout plot.

Take the “Double Gauss 28 degree field.ZMX” sample file (Zemax\Samples\Sequential\Objectives directory) as an example. The Double Gauss design includes three fields (0, 10, and 14 degrees) and three wavelengths (F, d, and C wavelengths representing the visible spectrum).

If we choose to display the two defined meridional rays at the primary wavelength (wavelength 2) and from All fields, a total of 6 rays will be drawn.  That is, 2 marginal rays * 1 wavelength * 3 fields. Remember to select List as the “Ray Pattern”!




EXPLICIT:  The explicit format consists of the word EXPLICIT on the very first line of the RAYLIST.TXT file, followed by the values x, y, z, l, m, n, and wavenumber; where x, y, and z are the ray starting coordinates, l, m, n are the direction cosines of the ray, and wavenumber is the integer indicating the wavelength to use.

All coordinates are in object space. If the system is at infinite conjugates, then the spatial coordinates are relative to Surface 1. If the object in not at infinity, then the coordinates are with respect to Surface 0 (the OBJ surface). 

The syntax of the explicit format is as follows:

x y z l m n wavenumber

Using the “Double Gauss 28 degree field.ZMX” once again as an example, edit the RAYLIST.TXT file to trace the rays defined by the following starting coordinates, direction cosines, and wavelength:


When an EXPLICIT trace is defined, the field and wavelength settings are ignored, and only those rays listed in the file are traced. In the current example, the three above listed rays are traced as follows:



The RAYLIST is a feature within Zemax OpticStudio which provides and easy way to visualize the propagation of any number of rays via the layout plots in Zemax OpticStudio (excluding the 2D Layout). Rays may be defined one of two ways in the RAYLIST.TXT file:

  • IMPLICITLY:  rays are defined by their normalized pupil coordinates, Px and Py
  • EXPLICITLY:  rays are defined by their starting coordinates, direction cosines, a wavenumber


Zemax OpticStudio Help files, Zemax LLC