How to locate geometry errors: part I

When using the non-sequential ray tracing capabilities of OpticStudio, geometry errors sometimes arise, causing some rays to terminate prematurely. These errors do not necessarily mean the ray trace is invalid, but are intended to warn the user of potential issues in the simulation. This article discusses how to locate and diagnose these types of errors.

Authored By Dan Hill


At times, you may encounter geometry errors when working in Non-Sequential or hybrid, mixed mode in OpticStudio. Geometry errors occur when OpticStudio encounters a section of your design where it is not sure how to trace. The user is alerted to these errors which are then logged to the ray database during an analysis. By tracking these errors down, you can have confidence that your system results are accurate.

This article discusses the tools that are built in to OpticStudio that will help the user identify and assess geometry errors. 

Why is it important to know how to locate geometry errors?

Geometry errors may be an indication of a serious flaw in your setup, leading to erroneous ray tracing results. Thus, it is very important to be able to determine where the error is occurring. However, it is also important to note that some perfectly good systems occasionally have a few rays fail. This is primarily due to the fact that these rays are incident upon boundaries between facets or surfaces, therefore accurate intercept points are not possible to compute. These rays are generally “trapped” internally by OpticStudio, and are absorbed or terminated. For the most part, the amount of “lost energy” associated with these rays is small relative to the total power of all sources defined in the design. Therefore, these rays can be safely ignored, as they do not have much significance in the final system results.

So how can you determine the proportion of energy which is lost due to errored rays? Once a ray trace is complete, OpticStudio will report the lost energy due to thresholds as well as the lost energy due to errors.


This value is reported in absolute system units (Watts, for example). If the value of the lost energy is significant, further investigation is required. If the lost energy is extremely small, then chances are just a few rays cannot be traced, and these can be ignored. If the lost energy is small enough to be negligible or if it is zero, then you may proceed with your design in confidence that the ray trace results are correct!

Common causes of geometry errors

As you have probably already guessed, geometry errors are not unique. That is, there is more than one possible scenario or reason as to their existence. Three of the most frequent causes of geometry related errors are outlined in the table below:

INVALID PLACEMENT OF ENTRY & EXIT PORTS Neither the Entry nor Exit Port may intersect with any objects in a Non-Sequential Component (NSC) group. Nor can the Exit port be in direct contact with a surface of a Non-Sequential (NS) object. It is important to ensure that both the ports are separated by at least the glue distance from any of the objects in the NSC group.
INVALID PLACEMENT OF SOURCES Sources can exist inside of volume objects, but they must be specified as such using the "Inside Of" flag in the Non-Sequential Component Editor. Sources may not straddle boundaries of volume objects. Misplaced Source Objects will often result in geometry errors.
INVALID CONSTRUCTION OF SOLID OBJECTS Sometimes, user defined objects, such as Polygon Objects or Imported Objects, are improperly defined. For example, if a Polygon Object is not fully enclosed, OpticStudio cannot determine when a ray left that object and will issue a geometry error. Geometry errors can also arise if the rendering quality of certain high precision objects is too low. This can be addressed in the Draw Tab of the Object Properties.


What information is contained within the error message?

When working in a Mixed Mode system, it is likely that any issued geometry errors are as a result of invalid placement of Entry and/or Exit Ports. Nonetheless, especially in pure NS systems, the error message contains useful information as to where the ray trace encountered an error. The reported geometry error message looks something like following

Zemax error message

This error message indicates information about the very first ray which was not successfully traced.


  • LINE 1: The first line contains the Non-Sequential Component (NSC) group surface number as well as the Source Object number that the ray originated from. The NSC group surface number corresponds to the surface number of the Non-Sequential Components surface in the Lens Data Editor. This can prove to be useful when more than one NSC group is present in a hybrid system. In a pure non-sequential system, the NSC group surface number is always equal to 1. The Source number corresponds to the object number of the source in the NSC Editor. Note that the Source number is equal to zero if the ray failure is due to a sequential ray in a Mixed Mode system.
  • LINE 2: The second line of the error message includes the NSC object number in which the error was encountered.
  • LINES 3 & 4: Lines three and four of the geometry error message include essential information about the initial ray position and direction cosines in global coordinates. For hybrid systems, the global coordinate reference is the vertex of the entry port. Note that upon updating a hybrid mode system, OpticStudio internally must launch specific rays for determining various system properties. Therefore, the reported direction cosines and positions of the ray could be from any one of these internally used rays. In other words, the ray may not necessarily be one which was user defined in the settings of the 3D Layout, for example.

Given these pieces of information, it is possible that in some cases the error in setup becomes quite obvious, though other times it is necessary to further analyze the propagation of the erroneous ray. Since we have the direction cosines and starting positions of the ray, we could set up a Source Ray to mimic the propagation through our optical system. This isn’t very difficult to do, but OpticStudio has a tool which automates this process for you, called the Create Error Ray tool!

The Create Error Ray tool

Any time a geometry error is issued, OpticStudio stores the position and direction cosine information of that ray. These starting values may be used to create a single Source Ray that duplicates the ray with the error. Anytime a geometry error is issued, you may ask OpticStudio to generate this source ray from Setup...Create Error Ray.

Create Error Ray

Upon selecting this option, OpticStudio will generate a Source Ray automatically in your NSC Editor with the appropriate position and direction cosines, and turn all of your other sources off by setting the # Layout Rays and # Analysis Rays to zero. Once the Geometry Error Test Ray is in place, you may use the layouts, OpticStudio Ray Database Viewer, and other diagnostic tools to narrow down the cause for the invalid ray trace. In doing this, it will be helpful to temporarily turn on the Ignore Trace Errors flag, so that you are not continually issued an error message every time you rotate a plot or move your cursor within the editor.


Note that this a global switch, and it is tied to the Ignore Errors checkbox in the Ray Trace/Detector Control window.


To save and view the details of a ray trace, choose Ignore Errors and save the rays to a desired filename (using the ZRD extension). 

Within the Ray Database (Analyze...Ray Database Viewer), you can view the all of the details of the propagation of the ray, right up to the point in which the error was experienced (denoted by the * in the Z column). This way you can determine the object the ray hit when terminated, the face number of that object, and the entire propagation history. This is very useful in targeting the area of your setup which needs modification in order to proceed without error.

Ray Database Viewer

Next Article: How to locate geometry errors part II - design examples


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



Please sign in to leave a comment.