ZOS-API.NET: An Overview

An application programming interface (API) for OpticStudio enables connections to, and customization of, the application using the latest software technology.
05/03/2015
OpticStudio
ZOS-API.NET
Programming Zemax

Introduction

An application programming interface (API) has been developed for OpticStudio that enables connections to, and customization of, the application using the latest software technology. While the API relies on a COM interface, it is rooted in .NET libraries, and as such programming with the API can be done using either C++ (COM) or C# (.NET) – depending on the user’s comfort with either language.

The connection between your application program and OpticStudio is classified in 1 of 4 Program Modes

1)    Standalone Mode. 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.

2)    User Extensions Mode. This mode allows for applications to be built that are similar to extensions written under the DDE protocol for inter-process communication (for more details on DDE extensions, see the following: http://www.zemax.com/support/knowledgebase?categoryname=Extensions; note that DDE has been deprecated with the introduction of ZOS-API). 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.

3)    User Operands Mode. 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.

4)    User Analysis Mode. 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.

These modes can be generally grouped into 2 categories: 1) Full Control (Standalone and User Extensions modes), in which the user generally has full control over the lens design and user interface and 2) Limited Access (User Operands and User Analysis modes), in which the user is locked down to working with a copy of the existing lens file.

Once the application has initialized communication to OpticStudio in 1 of the 4 available modes, files may be loaded, system settings may be changed, and data may be obtained from any number of analyses (more details below). Note that multiple system designs (i.e. ZMX files) can be loaded in any of the 4 available communication modes.

Getting started with ZOS-API.NET

There are two different methods to connect to OpticStudio via ZOS-API.NET: Your application is standalone and will start up its own copy of OpticStudio with which to interact (Standalone Mode), or OpticStudio is already running and will call your application (all other modes, which we will refer to as ‘Inherent’ Modes).

While any development system should work fine (as long as it can interface with .NET and C#), the examples have all been generated using Microsoft’s Visual Studio 2012 .NET Framework 4.5 and written in C#.

To create a new project using Visual Studio:

Choose ‘FILE’ -> ‘NEW’ -> ‘PROJECT’
Select ‘Template’ -> ‘Visual C#’ -> ‘Console Application’
Change the Name, Location and Solution name to something appropriate for your Solution/Project

You should see something along the lines of:


 
Click ‘OK’ and after your Solution/Project are generated, you should see something like:

 
 

In your ‘Solution Explorer’, <Right Click> on ‘Refereces’ and in the Menu select ‘Add Reference…’
In the ‘Reference Manager’ <Click> ‘Browse’ and Navigate to your Zemax OpticStudio’s installed directory 
<Click> on ZOSAPI.dll, <Ctl-Click> to add ZOSAPI_Interfaces.dll and your screen should look like:


 


<Click> ‘Add’ to get:
 

<Click> ‘OK’ to get to:


 

<Right Click> on ‘Refereces’ and in the Menu select ‘Add Reference…’. 
In the ‘Reference Manager’ <Click> ‘Browse’ and Navigate to ZOS-API/Libraries
<Click> ZOSAPI_NetHelper.dll to get:
 

<Click> ‘Add’ to get to:
 


<Click> ‘OK’ to get to:
 

In ‘Solution Explorer’ -> ‘References’ <Right Click> on ‘ZOSAPI’ and select ‘Properties’ from the menu:


 

Change ‘Copy Local’ from ‘True’ to ‘False’.

In ‘Solution Explorer’ -> ‘References’ <Right Click> on ‘ZOSAPI_Interfaces’ and select ‘Properties’ from the menu:


 

Change ‘Copy Local’ from ‘True’ to ‘False’.

You do not change any Properties for ZOSAPI_NetHelper.

Boilerplate Code

The code snippets below are the standard boilerplate code that every application built using ZOS-API.NET needs. Note that these samples include no error handling. It is strongly advised that you add your own style of error handling. Checking each return value against ‘null’ before using it is good practice. Similarly, wrapping code in try/catch blocks will help you handle untoward behavior.

The variable names used here are intended to be ‘self-documenting’, but you are of course free to change them as desired.

NOTE: ‘Main’ initializes the system and then calls another function (ZOSAPI_Worker) to actually ‘connect’ to the API and do the actual work for your application. Due to possible ‘order of operation optimizations’ imposed by the operating system and by the compiler optimization, it is possible that certain code sequences could ‘pre-load’ functions which “aren’t there yet”. Therefore, it is best practice to have ‘Main’ call a secondary function and have that secondary function directs all the ‘work’ for your application.

NOTE: While not strictly necessary, it is good practice to check your license status prior to running any application built for the API. If your license is not up-to-date, or another license error occurs while attempting to connect to OpticStudio, the likelihood of your application running correctly is minimized.

Standalone Mode boilerplate code

using ZOSAPI;

namespace My_ZOS_Application
{
    class Program
    {
        static void Main(string[] args)
        {
            ZOSAPI_NetHelper.ZOSAPI_Initializer.Initialize();

            ZOSAPI_Worker();
        }

        private static void ZOSAPI_Worker()
        {
            var TheConnection = new ZOSAPI_Connection();
            var TheApplication = TheConnection.CreateNewApplication();

            switch (TheApplication.LicenseStatus)
            {
                default: break;
                case LicenseStatusType.EE: break;
                case LicenseStatusType.IE: break;
                case LicenseStatusType.SE: break;
                case LicenseStatusType.Unknown: break;
                case LicenseStatusType.KeyNotWorking: break;
                case LicenseStatusType.NewLicenseNeeded: break;
            }
        }
    }
}

Inherent Modes boilerplate code

using ZOSAPI;

namespace My_ZOS_Application
{
    class Program
    {
        static void Main(string[] args)
        {
            ZOSAPI_NetHelper.ZOSAPI_Initializer.Initialize();

            ZOSAPI_Worker();
        }

        private static void ZOSAPI_Worker()
        {
            var TheConnection = new ZOSAPI_Connection();
            var TheApplication = TheConnection.ConnectToApplication();

            switch (TheApplication.LicenseStatus)
            {
                default: break;
                case LicenseStatusType.EE: break;
                case LicenseStatusType.IE: break;
                case LicenseStatusType.SE: break;
                case LicenseStatusType.Unknown: break;
                case LicenseStatusType.KeyNotWorking: break;
                case LicenseStatusType.NewLicenseNeeded: break;
            }
        }
    }
}

Inherent Modes notes

Note that while applications built using Inherent Modes compile to executable (.exe) files (just as with applications built using Standalone Mode), in order for Inherent Mode applications to be used by OpticStudio the exe files need to be copied (or built) into certain folders in your OpticStudio installation. The given folder name will be specific to your personal installation; we will refer to this as the {program} folder. Within that folder:
•    Applications built in User Extensions Mode need to be placed in the {program}\ZOS-API\Extensions folder
•    Applications built in User Operands Mode need to be placed in the {program}\ZOS-API\Operands folder
•    Applications built in User Analysis Mode need to be placed in the {program}\ZOS-API\User Analysis folder

Applications placed in the {program}\ZOS-API\Extensions folder or the {program}\ZOS-API\User Analysis folder will appear under the corresponding lists in the ZOS-API Applications section of the Programming tab: 

 


Functionality available through ZOS-API.NET

Many of the details provided in the previous two sections of this article (Getting Started with ZOS-API.NET and Boilerplate Code) were taken from the full documentation for ZOS-API.NET, which may be found in the section entitled “About the ZOS-API” in the OpticStudio Help File. This content may be accessed by selecting the Help System icon in the ZOS-API Applications section of the Programming tab:

  

We strong recommend reading the full documentation in the Help File prior to developing applications for the API. Note that specific documentation on the interfaces used by the API may be found in the Interface Documentation Help File, which may be accessed by selecting the corresponding icon in the ZOS-API Applications section of the Programming tab:

 

Below we provide a general summary of the functionality currently available in ZOS-API.NET.

System Explorer
•    The values of all items can be obtained and modified in all program modes

All editors (Lens Data, Non-Sequential Component, Multi-Configuration, Merit Function, Tolerance Data)
•    The values in all cells can be obtained and modified in all program modes
o    Note that in all cases cells are referenced by column number and not column header
•    The values of all data in the properties dialogs can be obtained and modified in all program modes

Analyses
•    For the following analyses, settings can be defined directly through the API and results may be retrieved directly into arrays of data:
o    Detector Viewer
o    Field Curvature and Distortion
o    Longitudinal Aberration
o    Lateral Color
o    Chromatic Focal Shift
o    Wavefront Map
o    Interferogram
o    Foucault Analysis
o    FFT PSF
o    FFT PSF Cross-Section
o    FFT Line/Edge Spread
o    Huygens PSF
o    Huygens PSF Cross-Section
o    FFT MTF
o    FFT Through Focus MTF
o    FFT Surface MTF
o    FFT MTF vs. Field
o    FFT MTF Map
o    Huygens MTF
o    Huygens Through Focus MTF
o    Huygens Surface MTF
o    Huygens MTF vs. Field
o    Geometric MTF
o    Geometric Through Focus MTF
o    Geometric MTF vs. Field
o    Geometric MTF Map
o    RMS vs. Field
o    RMS vs. Wavelength
o    RMS vs. Focus
o    RMS Field Map
o    Diffraction Enclosed Energy
o    Geometric Enclosed Energy
o    Geometric Line/Edge Spread
o    Extended Source Enclosed Energy
o    Surface Sag
o    Surface Phase
o    Surface Curvature
o    Surface Sag Cross-Section
o    Surface Phase Cross-Section
o    Surface Curvature Cross-Section

For the above analyses, the resulting output data may be based on data in the current database (e.g. as saved as a part of the session file if reading data from an opened file), or by modifying the settings for the analysis and then getting the results. Results include the calculated values themselves, as well as any text/header data that would appear if viewing the analysis in the user interface.

•    For the following analyses, settings can be defined directly through the API and results may be retrieved using the GetTextFile method:
o    Single Ray Trace
o    Ray Fan
o    Standard Spot Diagram
o    Footprint Diagram
o    Through Focus Spot Diagram
o    Full Field Spot Diagram
o    Matrix Spot Diagram
o    Configuration Matrix Spot Diagram
o    OPD Fan
o    Pupil Aberration Fan
o    Grid Distortion
o    Seidel Coefficients
o    Seidel Diagram
o    Zernike Fringe Coefficients
o    Zernike Standard Coefficients
o    Zernike Annular Coefficients
o    Zernike Coefficients vs. Field
•    For all other analyses, settings may be defined using the ModifySettings method and results may be retrieved using the GetTextFile method.

Tools
•    The following tools are supported (the tool location is provided in parentheses):
o    Add Coatings to All Surfaces (Lens Data Editor)
o    Convert Global To Local Coordinates (Lens Data Editor)
o    Convert Local To Global Coordinates (Lens Data Editor)
o    Convert Semi Diameters to Circular (Lens Data Editor)
o    Convert Semi Diameters to Floating (Lens Data Editor)
o    Convert Semi Diameters to Maximum (Lens Data Editor)
o    Remove All Apertures (Lens Data Editor)
o    Replace Vignetting with Apertures (Lens Data Editor)
o    Reload Object (Non-Sequential Component Editor)
o    Reload All Objects (Non-Sequential Component Editor)
o    Delete Configuration (Multi-Configuration Editor)
o    Insert Configuration (Multi-Configuration Editor)
o    Next Configuration (Multi-Configuration Editor)
o    Previous Configuration (Multi-Configuration Editor)
o    Insert Configuration with Pickups (Multi-Configuration Editor)
o    Make Single Configuration (Multi-Configuration Editor)
o    Insert Merit Function (Merit Function Editor)
o    Load Merit Function (Merit Function Editor)
o    Save Merit Function (Merit Function Editor)
o    Delete All Operands (Merit Function Editor)
o    Create Archive (File Tab)
o    Load Archive (File Tab)
o    Export CAD (File Tab)
o    Non-Sequential Ray Trace (Analyze Tab – Non-Sequential UI mode)
o    LightningTrace (Analyze Tab – Non-Sequential UI mode)
o    Remove All Variables (Optimize Tab)
o    Set All Radii Variable (Optimize Tab)
o    Set All Thickness Variable (Optimize Tab)
o    Quick Adjust (Optimize Tab)
o    Quick Focus (Optimize Tab)
o    Local Optimization (Optimize Tab)
o    Hammer Optimization (Optimize Tab)
o    Global Optimization (Optimize Tab)
o    Ray Trace of custom rays (not directly in UI; previously supported with DDE)
•    All DDE data items are supported by ZOS-API.NET, with the following exceptions:
o    CloseUDOData
o    ReleaseWindow
o    SetUDOData
o    ExportCheck
o    GetAddress
o    GetAspect
o    GetMetaFile
o    GetRefresh
o    GetSequence
o    GetSettingsData
o    GetUDOSystem
o    PushLens
o    PushLensPermission
o    SetSettingsData
o    WindowMaximize
o    WindowMinimize
o    WindowRestore

Finally, note that Undo/Redo functionality is not currently supported in the API, nor is the ability to obtain or modify any values in the Project Preferences dialog.

Tools for building ZOS-API Applications

A number of templates are provided for starting work on a new API-based application. These templates may be found in the section entitled ZOS-API Application Builders within the Programming tab of OpticStudio:

 

Note that templates have been provided for programming applications using C#, C++, MATLAB, and Python. For both C# and C++, templates are available for all communication modes:

 

In MATLAB and Python, templates have been provided for Standalone Mode applications:

 

Note that when using Visual Studio Express to compile applications built with ZOS-API.NET, you will need to use the editions for Windows Desktop or for Community; other versions of Visual Studio Express will not be compatible with the API.

Summary

ZOS-API.NET provides a powerful means of communicating with and/or customizing OpticStudio. The API provides the ability to write applications built on either COM (C++) or .NET (C#) code. The API allows applications to either communicate directly with opened instances of OpticStudio or to run OpticStudio as a background process. A significant amount of functionality exists in the API, and will continue to be built upon with future releases of OpticStudio.