Prepare for OpticsBuilder

Effective December 31, 2021, SOLIDWORKS integrations with Zemax products are deprecated and will not be available in future software releases of OpticsBuilder or OpticStudio. Learn more.
This article is part of the Getting Started with OpticsBuilder free tutorial.

This article provides a general overview of the Prepare for OpticsBuilder tool within Opticstudio 20.1 and higher. The Prepare for OpticsBuilder tool converts OpticStudio lens files (.ZMX, .ZAR and .ZOS files) to the format used by OpticsBuilder (ZBD files). This enables the optical engineer to package their design in a format that is easily accessible from within an OpticsBuilder-supported CAD program.

Authored By Jacob Hart and Alexandra Culler and Mojtaba Falahati


Prepare for OpticsBuilder makes the handoff between optical and mechanical engineers more efficient by enabling a simple conversion from an OpticStudio model to an OpticsBuilder (ZBD) file. The simple conversion process has three steps: User Inputs, Drawing Inputs, and Save .ZBD File.

Prepare for OpticsBuilder overview

The Prepare for OpticsBuilder tool is located in the File...Convert section of OpticStudio. 

Tip: If you do not see the Prepare for OpticsBuilder button, you will need to upgrade to OpticStudio 20.1 or higher.

Prepare for OpticsBuilder has three setting tabs to match each step of the conversion process. The "User Inputs" tab enables optical engineers to set up their analysis preferences and define the allowable deltas for Spot Size, Beam Clipping, and Image Contamination when comparing OpticsBuilder ray trace results. The allowable delta for Spot Size is also the maximum Spot Size change allowed for a successful sequential to non-sequential model conversion. See section "Error 1: Spot sizes do not match" for more information. The "Drawing Inputs" tab allows for population of the information required to automatically generate an ISO 10110 optical drawing in OpticsBuilder. Finally, the "Save .ZBD File" tab allows you to input a message for your CAD user and saves the converted file with the updated analysis settings.


The Prepare for OpticsBuilder tool includes the ability to:

  • Convert a file from sequential to non-sequential Mode. For this purpose, Prepare for OpticsBuilder will:
    • Convert sequential surfaces to matching non-sequential geometry objects
    • Check to make sure rays are positioned correctly following conversion
    • Check to make sure rays are angled correctly following conversion
    • Confirm that spot size change has remained below an allowable value following conversion
    • Allow the user to open and inspect the non-sequential file after an unsuccessful conversion from sequential mode
  • Validate that a given non-sequential object is supported in OpticsBuilder and is able to be exported
  • Generate a static critical boundary ray set for sequential designs
  • Manual population of drawing data for singlets, cemented doublets, triplets, and quadruplets
  • Add comments to a ZBD file for other engineers to reference
  • Choose whether to enable scattering and/or ray splitting in the dynamic ray trace analysis
  • Define the aperture for OpticsBuilder to generate chief rays
  • Add allowable deltas to OpticsBuilder as design acceptance criteria

To perform the steps above, the Prepare for OpticsBuilder tool will make a copy of the initial file. Then, if the file is sequential, the Design Lockdown tool will be run, a Static Critical Rayset will be generated, and a non-sequential conversion will be applied. This is a similar process to the one used by the Convert to NSC Group tool. There is more information on each of these steps in the Help Systems file "The Tolerance Tab...Production Tools Group...Design Lockdown", "The Tolerance Tab...Production Tools Group...Critical Rayset Generator", and "The File Tab...Convert Group...Convert to NSC Group."

Once complete, the two files will be compared. First, the rotation and offset matrices will be pulled and compared. Then, a ray trace will be run in the non-sequential file one field at a time. The detector data is stored and compared to the spot size data from the sequential file as provided by the Geometric Image Analysis tool. The tool will have the following settings:

The tool will loop through each field. For each field, the pixel size will be determined by the number of X-direction pixels on the detector in the non-sequential model. The image size will be given by multiplying the X-Half Width of the detector by 2. 

Finally, the Static Critical Rayset will be loaded into the non-sequential file and the ray landing coordinates will be read from the detector. These coordinates will be compared to the original sequential file and any change will be compared to the settings entered by the user in the "User Inputs" dialog. 

If the file is non-sequential, Prepare for OpticsBuilder will check for incompatible objects and will run a ray trace to compare the initial file to the copied file. The ray trace is saved, and a Path Analysis is performed to locate the position of the detector.

The Prepare for OpticsBuilder tool will accept focal and afocal systems.

Steps for using Prepare for OpticsBuilder

The Prepare for OpticsBuilder tool may be accessed in Sequential or Non-Sequential Mode. To use it, open the file you would like to share and navigate to File...Prepare for OpticsBuilder. You will find yourself at the "User Inputs" tab. At this point, you will:


  1. Define the file loading format and the static critical ray trace tolerances. Currently, Creo is the only CAD software into which the ZBD file can be loaded. If the Read-only checkbox is selected the optical data cannot be edited using OpticsBuilder, however changes can be made using CAD tools. You may choose the amount of allowable change in the location and angle of the critical rays. Position Tolerance represents the maximum allowed difference between a ray's landing position in the original file, and in the copied file. The Angle Tolerance will represent the maximum allowed angle between the target ray's vector, and the actual ray's vector. If the file is Sequential you may want to have the STOP surface as an annulus object in the CAD environment by selecting the Convert STOP Surface to Hard Aperture checkbox. If the file is non-sequential you need to select the Stop Surface/Object from the drop-down menu in Pupil Definition.

  2. Choose the number of analysis rays used during the preparation process (if the file is sequential) and select the analysis preferences and allowable deltas. Here, you may choose whether to consider scattering or ray splitting in the ray trace. Additionally, you may also define the amount of change that is allowed on the image plane following the change in file formats. In particular, the "Spot Size" allowable delta will be used to define the acceptable change in spot size that may occur when the file is converted from Sequential to non-sequential Mode.  
  3. Click Prepare. At this point, the tool will parse the file to make sure there are no errors or invalid object types. If starting with a sequential design, this is the step where the design is converted into a non-sequential design to be used in OpticsBuilder. 

If the ZBD file creation is successful, the user may move on to the "Drawing Inputs" tab by clicking Next. If ZBD file creation is unsuccessful, an error message is displayed indicating why the process failed and steps the user may use to fix issues.

The "Drawing Inputs" tab is where the user inputs drawing data for automatic generation of ISO 10110 optical manufacturing drawings in your CAD platform. OpticsBuilder users may also setup a map of this information onto their own custom drawing template for CAD. This will then allow the information to autopopulate onto their own template every time they use the Drawing feature in OpticsBuilder.


Each lens surface pair is represented by a labeled tab at the top of the screen. If an element type is chosen to be other than singlet, a tab is created after that element to specify cement properties.

For sequential models, the following information is automatically populated on the "Drawing Inputs" tab.

  • Front and back surface radii of curvature
  • Front and back surface clear aperture
  • Lens material
  • Index of refraction
  • Abbe number
  • Center thickness
  • Reference Wavelength

This data is pulled from the Lens and Tolerance Data Editors. Other data fields must be entered manually. All data in the Drawing Inputs tabs may be edited during this step.

For non-sequential models, the following information is automatically populated on the "Drawing Inputs" tab:

  • Lens material

After populating drawing inputs the user should select Next to go to the "Save .ZBD File" tab to enter notes. These notes will be attached to the generated file and will be visible to other engineers. When the user is ready to create a ZBD file they should click Save.

ZBD file format

The ZBD file format used by OpticsBuilder is intended to carry all necessary information needed for an iterative optomechanical packaging analysis; thus, allowing easy back-and-forth exchange between OpticStudio and a supported CAD program. This file type may be opened in OpticsBuilder and in OpticStudio 20.1 or later. The information within a ZBD file includes:

  • Sequential model (if applicable)
  • Non-sequential model
  • OpticStudio ray trace baseline results
  • Static critical ray bundle (sequential models only)
  • Material properties
  • Allowable deltas for RMS spot size, beam clipping, and image contamination
  • Optical drawing information
  • Optical tolerancing values
  • Any exported mechanical CAD parts

When the ZBD file is opened in OpticStudio, the user may choose to open the original sequential design or a ZAR containing the non-sequential model and any additional mechanical components exported from OpticsBuilder. If the design originated in non-sequential mode and a sequential model is not present, the non-sequential ZAR will open automatically.

Potential conversion errors

The Prepare for OpticsBuilder tool leaves converting from OpticStudio to a CAD-friendly ZBD file up to the optical engineer. For that purpose, it will deliver an error if the conversion does not perform as expected. This gives the engineer a chance to update the file and fix any problems before passing it along. There are six error messages that may be displayed:

  1. Error: Spot sizes do not match within the specified threshold
  2. Error: Objects are not supported in CAD platform
  3. Error: Critical Rays failed. Open non-sequential file for review
  4. Error: Convert to non-sequential failed. Open non-sequential file for review
  5. Error running analysis: A design lockdown did not succeed
  6. Error running analysis: Object reference not set to an instance of an object

Error 1: Spot sizes do not match

As part of the "User Inputs" in the Prepare for OpticsBuilder dialog, an "allowable delta" may be specified for spot size. When the system is converted from Sequential to Non-Sequential Mode, the spot size for all fields is analyzed. If there is a change in spot size that is larger than the value set by the user, then this error will be given. Oftentimes, this is an indication that the "allowable delta" value is too small and should be updated. In general, there will always be some noise between a non-sequential ray trace and a ray trace performed in Sequential Mode. It is expected that the two modes have some slight variation in spot size.

In addition to the above, there are a few typical reasons that the spot size will change:

  • The Design Lockdown portion of the conversion is generating apertures that are adversely affecting the beam profile
  • The system did not properly convert and the detector is no longer located at the correct location
  • The system is very large and generates an equally large spot size. A percent change in spot size is much larger for a 1000 um spot than for a 10 um spot.

The above list is not comprehensive. If you have already updated the spot size delta to a reasonable level, then you may want to check each step of the conversion individually. First, run the design lockdown tool under Tolerance...Design Lockdown and observe how the application of apertures affects the ray trace. Then, open the non-sequential version and check for errors in element placement or definition. 

Note: This issue may appear more frequently for afocal systems. In those cases, the spot size delta will need to be much larger. Typically, 20-100 um will work for an afocal system.   

This error will only appear in Sequential Mode.

Error 2: Objects are not supported in CAD platform

In some cases a non-sequential object is not able to be exported to a ZBD file. These object types will need to be converted. 

In most cases, this occurs when an object that is currently in the model does not have a physical equivalent. A notable example of a non-supported object is a User Defined Object. When a User Defined Object is in use, OpticStudio is defining the object geometry through an external DLL. This information cannot be read into an external mechanical design program so it cannot be translated into a ZBD file format. One method to repair this error would be to convert the invalid object into a Grid Sag Surface or a Boolean object. There is more information on the Boolean object types in the Knowledgebase article "How to use the Boolean CAD, Boolean Native and Compound Lens objects, and the Combine Objects tool." 

There are a few objects with known compatibility issues. They are listed below:

  • CAD Assembly: Autodesk Inventor
  • CAD Assembly: Creo
  • CAD Part: Autodesk Inventor
  • Freeform Z
  • Grid Sag Lens
  • Swept

This error will only appear in non-sequential Mode.

Error 3: Critical Rays failed

This error may appear in OpticStudio 20.1, but was removed as a conversion criterion in 20.2. 

The Prepare for OpticsBuilder tool will perform a ray trace through the system to look for any deviations in critical ray angle and position. If the deviation is larger than the specified tolerances, the conversion will fail. Similarly, if apertures are applied that cut off a Marginal or Chief ray, the Critical Rays will not be generated. The best way to observe how these rays are being traced through the system is to open the non-sequential file. Then, take a look at the layout plot and see how the rays are moving through the system. This will give you a chance to find out if any rays are missing objects or are being cut off prematurely.

Alternatively, if you started in sequential Mode, you may want to re-open your initial file and perform a Design Lockdown. You can do this by navigating to Tolerance…Design Lockdown. The Design Lockdown tool applies apertures to all surfaces which may clip the beam. You can find out if that's the case by navigating to Setup…System Check after applying the Design Lockdown. If there are any "Errors" or "Warnings" they will need to be addressed before converting the file.

This error will only appear in sequential Mode.

Error 4: Convert to non-sequential failed

Occasionally, a conversion from sequential to non-sequential Mode will fail. Usually this is due to using a non-supported surface or aperture type, although it can sometimes be caused by settings in the System Explorer. If you receive this error, it will be useful to familiarize yourself with the conversion process found in the Help System file "The File Tab...Convert Group...Convert to NSC Group...Converting sequential surfaces to non-sequential objects."

Additionally, a list of known conversion compatibility issues is available in the Help System file "The File Tab...Convert Group...Convert to NSC Group...Exceptions and Restrictions." Read through this list and make sure your system does not have any incompatible surface settings. For more information on the non-sequential conversion process, please see the Knowledgebase article "Converting sequential surfaces to non-sequential objects."

This error will only appear in Sequential Mode.

Error 5: A design lockdown did not succeed

The Design Lockdown tool converts all idealized inputs of a system into real manufacturing inputs. As part of this, semi-diameters are fixed and any model glass types are converted to real glasses. There are several reasons that a Design Lockdown may fail, so when this error is given, the tool will also try to inform you where the error came from. Additionally, some typical fixes are listed. An example of this error is below:

In the above example, the error reports "Can't find glass *F2* in catalog!" This error was given because no catalogs were listed under System Explorer...Material Catalogs...Catalogs to Use. Without a catalog to reference, the tool cannot convert the model glasses to an analogous real material. 

If you see this error, try working through the list of potential fixes given by the Prepare for OpticsBuilder tool. 

This error will only appear in sequential Mode.

Note: In version 20.1, the button "Open Non-Sequential File" populates with this error. That is incorrect, and will open a faulty file. 

Error 6: Object reference not set to an instance of an object

This error represents a "Cannot determine object coordinates!" error in sequential Mode. Typically, this error is given when the ray aiming algorithm is failing to find the STOP surface. This is rare, but it happens in extremely decentered, tilted, or highly aberrated systems. This error will be given during the conversion, and is most likely the result of a problem in the Design Lockdown step. If you received this error while using Prepare for OpticsBuilder, try manually applying a Design Lockdown to the initial file. Check and see if the error appears. If it does, you may need to manually update the system settings to help the ray trace along. Check out the Knowledgebase article "What is Pupil Shift and how is it calculated?" for information on how to do that. 

In non-sequential Mode, this error will appear when the path analysis of the ray trace fails. As of 20.1, this is a known bug where at least one ray is incorrectly listed as starting from a non-source object. Because this failure affects (at most) a handful of rays in a particular ray trace, you can circumnavigate this error by re-running the Prepare for OpticsBuilder tool. This will re-run the ray trace with a new, random set of rays. This will not adversely affect the conversion or the system. 

This error will appear in sequential and non-sequential Mode.


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



Article is closed for comments.