Support Material for ZOS-API Users

Support Material for ZOS-API Users
Tess Jacobs
OpticStudio 
ZOS-API.NET
Programming Zemax

General

An application programming interface (ZOS-API) has been developed for OpticStudio that enables connections to, and customization of, the application using the latest software technology. While ZOS-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.
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++ and Python) or .NET (C#) code [Matlab as well- which category?]. 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.
This article will provide an overview of the four programming languages that are compatible with our API: MATLAB, Pyton, C++, and C#.
 
Boilerplate: 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;
            }
        }
    }
}

Interactive Extension

The Interactive Extension mode is almost identical to a User Extension except an Interactive Extension does not have to be a standalone executable. This capability allows connections from scripting environments such as Matlab or Python where there is no compiled executable that OpticStudio can launch.

More information about Interative Extenstion can be found in this article

Related KBAs

ZOS-API.NET: An Overview

Related Webinars

Accessing the Ray Database with the ZOS-API using MATLAB - Jan 25, 2017
Matlab & ZOS-API.NET

MATLAB

Matlab Header

Modes

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.
Interactive Extension: The Interactive Extension mode is almost identical to a User Extension except an Interactive Extension does not have to be a standalone executable. This capability allows connections from scripting environments such as Matlab or Python where there is no compiled executable that OpticStudio can launch.

Sample Code

Matlab sample code is included with every license of OpticsStudio. These sample code files can be found within your Zemax > ZOS-API Sample Code folder. The files are also attached to this article. 

The topics include: 
  1. Starting a new file and preforming a Quick Focus
  2. Preform a non-sequential ray trace
  3. Open a sequential file and perform and optimization
  4. Extract data from the FFT MTF analysis window

Related KBAs

ZOS-API using MATLAB

Related Webinars

Accessing the Ray Database with the ZOS-API using MATLAB - Jan 25, 2017
Matlab & ZOS-API.NET
 

Python

Python Header

Modes

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.
Interactive Extension: Matlab. The Interactive Extension mode is almost identical to a User Extension except an Interactive Extension does not have to be a standalone executable. This capability allows connections from scripting environments such as Matlab or Python where there is no compiled executable that OpticStudio can launch.

Sample Code

Python sample code is included with every license of OpticsStudio. These sample code files can be found within your Zemax > ZOS-API Sample Code folder. The files are also attached to this article. 

The topics include: 
  1. Starting a new file and preforming a Quick Focus
  2. Preform a non-sequential ray trace
  3. Open a sequential file and perform and optimization
  4. Extract data from the FFT MTF analysis window

Related KBAs

Getting Started with Python
ZOS-API using Python
How to build and optimize a singlet using ZOS-API with Python


C++

C++ Header

Modes

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.
User Extension: 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.
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.
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.

Sample Code

C++ sample code is included with every license of OpticsStudio. These sample code files can be found within your Zemax > ZOS-API Sample Code folder. The files are also attached to this article. 

The topics include: 
  1. Sag Data from a user defined surface

C#

Modes

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.
User Extension: 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.
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.
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.
 

Sample Code

C# sample code is included with every license of OpticsStudio. These sample code files can be found within your Zemax > ZOS-API Sample Code folder. The files are also attached to this article. 

The topics include: 
  1.  Extract information from analysis window
  2. Sample Extension