This article provides a brief overview of the ZOS-API sample files that are provided with your OpticStudio installation. They will help you get started using this feature.
Authored By Tess Jacobs, reviewed by Sandrine Auriol
Introduction
OpticStudio features an application programming interface (ZOS-API) which enables external programs to either communicate directly with opened instances of OpticStudio (Interactive mode), or to run it as a background process (Standalone mode). A significant amount of functionality exists in the API and will continue to be built upon with future releases of OpticStudio.
This article will provide an overview of the material available in the four fully supported programming languages compatible with our API: MATLAB, Python, C++, and C#.
Modes: Different ways of connection
The connection between the application program (MATLAB, Python, C++, C#, …) and OpticStudio is classified in 1 of 4 Program Modes.
These modes are described in the built-in Help File under The Programming Tab > About the ZOS-API > Introduction (about the zos-api).
Here is a description of these modes:
| Mode | Description |  |
 |
 |
 |
| Standalone Application | In this mode the application launches an entirely new instance of OpticStudio (the other modes rely on the presence of an existing instance already being open). Thus, care must be taken to ensure that 1 or fewer instances of OpticStudio are already open before launching an application in this mode (to stay within the licensing constraints for OpticStudio). In this mode OpticStudio is effectively being run as a service, with no user interface. | x | x | x | x |
| Interactive Extension | The Interactive Extension mode connects to an already open instance of OpticStudio. OpticStudio interface is kept up-to-date with changes made in the program when run in this mode. It is almost identical to a User Extension except this capability allows connections from scripting environments such as MATLAB or Python where there is no compiled executable that OpticStudio can launch. |
x | x | ||
| User Extension | This mode is launched from an open instance of OpticStudio and gives full control over the lens design and user interface. It is a like "user defined tool". A toggle has been provided that determines whether or not the user interface is kept up-to-date with changes made in the program when run in this mode. This mode is the closer to the deprecated DDE extensions. |
x | x | ||
| User Analysis | This mode is linked to a single analysis window. This mode is nearly identical to User Operands mode, except it is used to populate data for a custom analysis. The data is displayed using the modern graphics provided in OpticStudio for most analyses. | x | x | ||
| User Operand | This mode is linked to a user defined operand in the Merit Function Editor, which is added to the editor using the UDOC operand. This mode would not allow changes to the current lens system or to the user interface (i.e. in this mode only changes to a copy of the system are allowed). Access to the list of open analyses in the file has not been provided in this mode, since a new instance of an analysis can always be run if needed. | x | x |
Accessing Examples
The ZOS-API help documentation is linked within the Zemax OpticStudio Programming tab. This help documentation was designed to be easier to follow and includes examples in all 4 target environments (C#, C++, MATLAB, & Python). To access the help documentation, you can click on either Programming...ZOS-API Help...ZOS-API Syntax Help or Help...ZOS-API Syntax Help.
All the examples in the ZOS-API Syntax Help are in Standalone Application mode, the exception being Example 16. Example 16 is a user-defined operand.
The sample codes are included with every license of OpticsStudio. These sample code files can be found within your {Zemax}\ZOS-API Sample Code folder. In those folders, there are also 3 more examples: a user-defined operand, a user-defined analysis and a user-defined extension.
Standalone Application
| Example# | Summary | Description | Filename |
| 1 | New File and QuickFocus |
New lens file is created and saved in samples directory. Changes are made to aperture value, field point is added, and wavelength preset for FdC is selected. Comments, thicknesses, and radii are changed in the LDE; an F# solve is placed on the last surface's radius. Finally, the quick focus tool is opened, executed, and closed. |
CSharpStandalone_01_new_file_and_quickfocus.cs CppStandalone_01_new_file_and_quickfocus.cpp MatlabStandalone_01_new_file_and_quickfocus.m PythonStandalone_01_new_file_and_quickfocus.py |
| 2 | NSC Ray Trace | A NSC sample file (…\Non-sequential\Miscellaneous\Digital_projector_flys_eye_homogenizer.zmx) is opened, ray trace settings are modified, and then a ray trace is run. Ray trace progress is stored and displayed. After the trace, detector parameters (width, height, number of pixels, etc.) are extracted, as well as pixel data, and detector viewer is recreated and plotted. |
CSharpStandalone_02_NSC_ray_trace.cs CppStandalone_02_NSC_ray_trace.cpp MatlabStandalone_02_NSC_ray_trace.m PythonStandalone_02_NSC_ray_trace.py |
| 3 | Open File and Optimize | An API file (…\Samples\API\[language]\e01_new_file_and_quickfocus.zmx) is opened, and some surfaces and radii are made variable. A merit function which constrains air and material thicknesses, and targets astigmatism and coma, is generated manually by inserting operands and adjusting parameter values. The local optimizer is run to completion, and then the hammer optimizer is run for 10 seconds. |
CSharpStandalone_03_open_file_and_optimise.cs CppStandalone_03_open_file_and_optimise.cpp MatlabStandalone_03_open_file_and_optimise.m PythonStandalone_03_open_file_and_optimise.py |
| 4 | Retrieve Data from FFT MTF | A sample file (…\Sequential\Objectives\Cooke 40 degree field.zmx) is loaded and a new FFT MTF analysis window is opened. The maximum frequency and sampling is modified. Results are retrieved and the data series are plotted; the OpticStudio FFT MTF plot is recreated. |
CSharpStandalone_04_pull_data_from_FFTMTF.cs CppStandalone_04_pull_data_from_FFTMTF.cpp MatlabStandalone_04_pull_data_from_FFTMTF.m PythonStandalone_04_pull_data_from_FFTMTF.py |
| 5 | Parsing a ZRD File | A sample file (..\Non-sequential) is opened, a ray trace is performed while saving the ZRD file, the ZRD file is opened and all ray segment data is read. |
CSharpStandalone_05_Read_ZRD_File.cs CppStandalone_05_Read_ZRD_File.cpp MatlabStandalone_05_Read_ZRD_File.m PythonStandalone_05_Read_ZRD_File.py |
| 6 | NSC Phase | A file with a simple spherical wavefront is created using a point source, which propagates to a detector. Rather than using a Detector Viewer to extract the phase of the wavefront, the GetAllCoherentDataSafe() method is used to extract a 2D array to manually calculate the phase. The GetAllCoherentDataSafe() method will only return the real & imaginary parts of the electric field, so atan2(image, real) is used to calculate the phase. Note that for C++, GetAllCoherentData() method is used to return a 1D array which is then read out in nested FOR loops and provides the 2D phase data in the correct orientation. |
CSharpStandalone_06_nsc_phase.cs CppStandalone_06_nsc_phase.cpp MatlabStandalone_06_nsc_phase.m PythonStandalone_06_nsc_phase.py |
| 7 | Create File From Prescription Data | Coming soon… | |
| 8 | Flux vs Wavelength Analysis | Coming soon… | |
| 9 | NSC CAD | A new file is opened, Object 1 is set to "CAD Part: STEP/IGES/SAT" object type, and a CAD file is referenced and inserted. The CAD object’s data is then exposed, and face/surface data is altered. Creation of a polygon object file is then demonstrated by directly writing the object to a POB file; a cube is defined using POB syntax, and it is then inserted into the NSCE. |
CSharpStandalone_09_NSC_CAD.cs CppStandalone_09_NSC_CAD.cpp MatlabStandalone_09_NSC_CAD.m PythonStandalone_09_NSC_CAD.py |
| 10 | NSC ZRD Filter String | A sample file is opened, all detectors are cleared, and a ray trace is run while saving a ZRD file. The ZRD file is played back on a detector viewer window, while a filter string is applied to the detector. The number of ray hits and total flux is retrieved from the detector for each pixel. For Premium only, a Ray Path Analysis window is opened, the ZRD is loaded and the output is saved to a text file. |
CSharpStandalone_10_NSC_ZRD_filter_string.cs CppStandalone_10_NSC_ZRD_filter_string.cpp MatlabStandalone_10_NSC_ZRD_filter_string.m PythonStandalone_10_NSC_ZRD_filter_string.py |
| 11 | Basic Sequential | A new sequential file is created and saved. The system aperture value (entrance pupil diameter) and apodization type are changed. Thickness, radii, and material are changed and a rectangular aperture is placed on surface 1. The Scale Lens tool is used to change the system units to inches. A quick focus is performed and then a universal plot is created. The settings for the universal plot are changed to display the RMS spot size as a function of the thickness on the last surface. |
CSharpStandalone_11_BASIC_SEQ.cs CppStandalone_11_BASIC_SEQ.cpp MatlabStandalone_11_BASIC_SEQ.m PythonStandalone_11_BASIC_SEQ.py |
| 12 | Sequential System Explorer | A new file is created and all values for each section of the sequential system explorer are changed; adjustments are made to wavelength, field, polarization, materials catalog, system title/notes, default coating/scatter files, and lens units. |
CSharpStandalone_12_SEQ_SystemExplorer.cs CppStandalone_12_SEQ_SystemExplorer.cpp MatlabStandalone_12_SEQ_SystemExplorer.m PythonStandalone_12_SEQ_SystemExplorer.py |
| 13 | Sequential Maximum AOI on Surface | Coming soon… | |
| 14 | Tolerancing | A sequential tolerance analysis (tolerance data editor) is setup via the tolerancing wizard, specifying the surface/element tolerances. Several settings in the tolerancing window are modified, such as the sensitivity mode, criterion, fields, and number of Monte Carlo runs. The tolerance is then run and the Monte Carlo files are saved to Samples\API\{language}\e14_seq_tolerance. Lastly, the file is converted to non-sequential mode. |
CSharpStandalone_14_Seq_Tolerance.cs CppStandalone_14_Seq_Tolerance.cpp MatlabStandalone_14_Seq_Tolerance.m PythonStandalone_14_Seq_Tolerance.py |
| 15 | Sequential Optimization | The quick focus and optimization tools are demonstrated. A sample file is opened, and the ‘remove all variables’ and ‘quick focus’ tools are used. Some variables and solves are specified, and a merit function is generated with the merit function wizard. The local, global, and hammer optimizers are each run and closed in sequence. |
CSharpStandalone_15_Seq_Optimization.cs CppStandalone_15_Seq_Optimization.cpp MatlabStandalone_15_Seq_Optimization.m PythonStandalone_15_Seq_Optimization.py |
| 17 | Bulk Scatter | A copy of the bulk scatter sample file (…\Non-sequential\Scattering\Bulk scatter.zmx) is created from scratch. The volume scattering profile is set on a rectangular volume. Both a shaded model and a detector viewer are opened with user-defined settings (rotating the XYZ orientation) via the ModifySettings() method. A non-sequential ray trace with scattering enabled is performed. Note that to observe scattering in the created ZMX file, the Scatter NSC Rays setting will have to be manually checked in the NSC Shaded Model. |
CSharpStandalone_17_NSC_BulkScatter.cs CppStandalone_17_NSC_BulkScatter.cpp MatlabStandalone_17_NSC_BulkScatter.m PythonStandalone_17_NSC_BulkScatter.py |
| 18 | Multiple Configurations | A sample file is opened and multiple configurations, along with MCE operands, are added to the system. The THIC multi-configuration operand is created and each configuration is refocused by looping through all configurations and running the quick focus tool. A multi-configuration system is manually created for thermal analysis, with all the appropriate thermal operands and thermal pickups. |
CSharpStandalone_18_SetMultiConfiguration.cs CppStandalone_18_SetMultiConfiguration.cpp MatlabStandalone_18_SetMultiConfiguration.m PythonStandalone_18_SetMultiConfiguration.py |
| 19 | Surface Properties | A chain of prisms is built in sequential mode. Several surfaces are inserted into the LDE and surface properties are alerted to tilt the front and rear face of each prism. Coordinate breaks are inserted around the prism and then the sequence of coordinate breaks and prism surfaces are copied to create a semi-circle chain of prisms. Both the Local to Global and the Global to Local tools are demonstrated with this system. This sample is the equivalent of the KBA article “How to Work in Global Coordinates in a Sequential Optical System” |
CSharpStandalone_19_Surface_Properties.cs CppStandalone_19_Surface_Properties.cpp MatlabStandalone_19_Surface_Properties.m PythonStandalone_19_Surface_Properties.py |
| 20 | Exporting as CAD File | The IExportCAD interface is used to export a non-sequential system (…\Non-sequential\Miscellaneous\Digital_projector_flys_eye_homogenizer.zmx) as a STEP file. The Export tool settings are customized and the tool is run to completion with a custom timeout. |
CSharpStandalone_20_export_CAD_File.cs CppStandalone_20_export_CAD_File.cpp MatlabStandalone_20_export_CAD_File.m PythonStandalone_20_export_CAD_File.py |
| 21 | White LED Phosphor | Starting from a blank file, the non-sequential sample file …\Samples\Non-sequential\Phosphors and Fluorescence\White LED Phosphor.zmx is created from scratch. All necessary objects including sources, STEP files, lenses and detectors, are inserted. Both a scatter profile and photoluminescence are applied to the lens while all appropriate files are set for the volume physics model. A (lengthy) ray trace is run and the percent completion is displayed. Two detector viewers are opened to show the irradiance and the radiant intensity. |
CSharpStandalone_21_White_LED_Phosphor.cs CppStandalone_21_White_LED_Phosphor.cpp MatlabStandalone_21_White_LED_Phosphor.m PythonStandalone_21_White_LED_Phosphor.py |
| 22 | Sequential Analysis | A batch ray trace is run in a sequential sample file. A list of 315 rays is generated and passed to ZOS-API for tracing in a single operation. This greatly reduces overhead when tracing a large number of rays. Resulting ray data is stored and displayed outside of OpticStudio. Using the native OpticStudio spot diagram analysis, geometric and RMS spot radius are retrieved, and are also displayed. |
CSharpStandalone_22_seq_spot_diagram.cs CppStandalone_22_seq_spot_diagram.cpp MatlabStandalone_22_seq_spot_diagram.m PythonStandalone_22_seq_spot_diagram.py |
| 23 | Ray Fan User Analysis | Using a batch ray trace, a Ray Fan analysis is generated via both the native OpticStudio code as well as manually via the IBatchRayTrace interface. The results, including proper scaling and execution time, are displayed for comparison purposes. |
CSharpStandalone_23_ray_fan_native_manual_comparison.cs CppStandalone_23_ray_fan_native_manual_comparison.cpp MatlabStandalone_23_ray_fan_native_manual_comparison.m PythonStandalone_23_ray_fan_native_manual_comparison.py |
| 24 | Non-Sequential Detector Data | A basic non-sequential system is built with several different object types, and changes are made to object parameters through the INCERow interface. Face type, coating, and scatter profile properties are set on volumetric objects. A ray trace is run and a native OpticStudio detector is opened for reference. Then, the detector pixel data is extracted and plotted outside of OpticStudio. |
CSharpStandalone_24_nsc_detectors.cs CppStandalone_24_nsc_detectors.cpp MatlabStandalone_24_nsc_detectors.m PythonStandalone_24_nsc_detectors.py |
| 25 | Source Spectrum Diffraction Grating | A non-sequential system with two black body sources of different temperatures and a diffraction grating is built. The system is setup with multi-configuration to control the number of analysis rays traced for each source. Only a single source has analysis rays during a ray trace. The true color results are plotted for each configuration. |
CSharpStandalone_25_source_spectrum_diffraction_grating.cs CppStandalone_25_source_spectrum_diffraction_grating.cpp MatlabStandalone_25_source_spectrum_diffraction_grating.m PythonStandalone_25_source_spectrum_diffraction_grating.py |
| 26 | Modify Project Preferences | A new system is opened with a user-specified OpticStudio.CFG configuration file. All available Project Preferences are modified and displayed. |
CSharpStandalone_26_modify_project_preferences.cs CppStandalone_26_modify_project_preferences.cpp MatlabStandalone_26_modify_project_preferences.m PythonStandalone_26_modify_project_preferences.py |
User Extension
| Example# | Summary | Description | Filename |
| Build a doublet, optimize and analyze with Huygens PSF | A user-defined extension creates a new sequential system. It is a F/5 doublet made of N-BAF10, SF10 in visible (F,d,C wavelengths). The Entrance Pupil Diameter is 10 and the maximum half field angle is 10 degrees. The extension builds a merit function. The doublet is optimized (display of the merit function at each cycle) and then it computes the Huygens PSF and Huygens MTF. The source code as well as the compiled version are provided. The compiled version can be run from Programming…User Analyses…User Extension. | SampleExtension1.cs |
User Analysis
| Example# | Summary | Description | Filename |
| Replicate FFT MTF vs Field Analysis |
A user-analysis is created and replicates the FFT MTF vs Field analysis under Analyze…MTF. The setting windows give access to the wavelengths. The source code as well as the compiled version are provided. The compiled version can be run from Programming…User Analyses…SampleAnalysis1. |
SampleAnalysis1.cs |
User Operand
| Example# | Summary | Description | Filename |
| 16 | Sum Absolute Thickness |
A user-defined operand (UDOC) is created which provides the total center thickness between 2 surfaces. Surface 1 is Hx argument and Surface 2 is Hy argument. Since a UDOC is an executable that needs to be called from OpticStudio, a UDOC can only be created by languages which can compile code (C#/C++). The source code is provided, but it needs to be compiled with the USER OPERAND solution rather than the standalone application solution. The EXE also needs to be named UDOC##.exe and placed in the ZOS-API\Operands folder. |
CSharpUserOperand_16_SumAbsoluteThickness |
| Compute Sag at x,y |
This user-defined operand computes the sag of a surface (Hx argument) at any x and y coordinates (Px and Py arguments). If Data=0, it computes the sag. If Data=1, it computes the alternate sag. For more information, check the definition of the GetSag function in the ZOSAPI.Editors.LDE.ILensDataEditor Interface in ZOS-API Syntax Help. The source code as well as the compiled version are provided. The compiled version can be run by typing UDOC Prog# 1 from the Merit Function Editor. |
UDOC01.cpp |
Previous article: Navigating the ZOS-API Syntax Help document - Part 3
Next article: Understanding the main Interfaces of ZOS-API using MATLAB