Jan 11, 2022

Understanding the basics of ZOS-API structure

Category: Product News

That blog article explains the basics of ZOS-API structure and the concepts of Object-Oriented programming that apply to ZOS-API. Although the object-oriented nature of ZOS-API is largely “hidden”, it can help in getting a better understanding of the vocabulary and organization of ZOS-API.

This article will also highlight some of the key concepts of Object-Oriented Programming and how they are used in ZOS-API. It is possible to use ZOS-API without being a developer but grasping a few basics will make working with ZOS-API much more straightforward.

What Is Object-Oriented Programming?

Object-Oriented Languages use an efficient way of programming. The data is organized using Objects and Classes so that the code can be reused for different projects instead of starting from scratch. That concept can be easily used to define an OpticStudio file.

Each zmx file represents an optical system that is different as it can be in sequential and/or non-sequential mode, it can have a different number of objects and/or surfaces, ...



In the object-oriented program, each optical system will be described as an API 'Object'. Optical systems have common characteristics like wavelengths, surfaces, ...

In object-oriented programming, the common characteristics are grouped into a master list. This master list of characteristics is called a Class or an Interface. 



The Classes are further grouped into libraries called Namespaces. Here is a summary of the code structure:

Namespace (Library containing Classes and Interfaces)

Class / Interface: group (template with attributes)

Functions (action)

Property (set or get a value)

For more information: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/general-structure-of-a-csharp-program

ZOS-API structure

ZOS-API is a hierarchy of Interfaces called a Namespace. Working with ZOS-API means creating API ‘Objects’, which are members of one of these Interfaces. The Interface determines what attributes are available for the Object.

The attributes are Properties or Functions:

  • A Property is like defining or reading a setting, a stored value.

  • A Function is a command; something that the object can do.

Calling a Function or Property of an Object always returns something. It can return:

  • A number (double, int, …), a text (string), a Boolean (true or false).

    int value = Object1.NumberOfFields;

  • A new Object, which is a member of an Interface.

    IField New_Object = Object1.GetField(1);

  • Some Properties are [get], and some are [get, set].

    To get the value, the syntax is value = Object1.Normalization;

    To set the value the syntax is Normalization = value;

A hierarchy of Interfaces

We can start to examine how the code is structured by using some sample code in conjunction with the ZOS-API help

  • Open the sample file “\Zemax\ZOS-API Sample Code\C#\CSharpStandalone_01_new_file_and_quickfocus.cs”. That sample file can be opened with a text editor.
    The sample file is in C#, but the concepts of Object-Oriented Programming are common to all languages using ZOS-API.

  • Open the Syntax Help File.

  • In the Help File, the main interface is called IOpticalSystem. It is equivalent to a single ZMX file.

  • By clicking IOpticalSystem you can access information about all the attributes of this interface.

Sandrine Auriol
Senior Optical Engineer
Zemax an Ansys Company

To learn more on the basics of ZOS-API structure, and key concepts such as inheritance, check out the additional resources below:

Webinar: Unleashing the Power of OpticStudio through the ZOS-API

Knowledgebase Article: Understanding the basics of ZOS-API structure

To try out Zemax capabilities please download a free trial here.