Drawing specific rays in layout plots

This article demonstrates how to use RAYLIST to draw the desired rays in an OpticStudio layout. Both the IMPLICIT and EXPLICIT methods within RAYLIST will be discussed and shown with an example file.

Authored By Dan Hill



OpticStudio provides users with the ability to both quantitatively and qualitatively trace rays through a Sequential system. Quantitatively, the program provides the Single Ray Trace analysis feature as well as several merit function operands. These are quick ways to obtain the location of a particular ray.

There are some cases in which seeing a ray running through the system is more useful than having its coordinate locations. For these situations, OpticStudio provides the RAYLIST text file. RAYLIST allows users to visually trace a given ray through the system using the 3D or Shaded Model layout plots. 

In this article, two examples of using the RAYLIST text file are provided. 

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 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 OpticStudio via the RAYLIST.

The layouts in 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 {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 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 following sections.




Rays are defined by the normalized pupil coordinates


Rays are defined by their starting coordinates, direction cosines, and wavelength


The IMPLICIT format

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”!





The EXPLICIT format

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:




Was this article helpful?
5 out of 6 found this helpful



Article is closed for comments.