Understanding the basics of ZOS-API structure

That 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.

Authored By Sandrine Auriol


This article will 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, ...


Different optical systems


In the object-oriented program, each optical system will be described as an API 'Object'. Optical systems have common characteristic 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


Optical System Template


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 Object1.Normalization = value;


A hierarchy of Interfaces

Let’s open a sample file and see how the code is structured.

  • Open the sample file "\Zemax\ZOS-API Sample Code\C#\CSharpStandalone_01_new_file_and_quickfocus.cs". That sample file can be open 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.

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

  • In the sample file, the main class IOpticalSystem or ZOSAPI.IOpticalSystem is used on line 56. In the code, it is written:
    IOpticalSystem TheSystem = TheApplication.PrimarySystem;
    This line means that an object called TheSystem is defined. That object is an instance of the IOpticalSystem Interface. It means that a new empty optical system, a new zmx file has been created.
  • To define the characteristics of that system, click on ZOSAPI.IOpticalSystem:

    Click IOpticalSystem


Functions and Properties of an Interface

The characteristics of TheSystem can be described by the Functions and Properties of the IOpticalSystem Interface.
The concept of Class is handy because when defining TheSystem as an Object of the IOpticalSystem class, it gives access to all the attributes of IOpticalSystem. These attributes define common characteristics to ZMX files.


Attributes of IOpticalSystem

One property of the IOpticalSystem Interface is LDE. The LDE Property gets the Lens Data Editor as we can see below in the Help File:




Back to the sample file, line 95, in the code it is written:

ILensDataEditor TheLDE = TheSystem.LDE;

The code creates an Object called TheLDE which is the Lens Data Editor. To create TheLDE, the code uses the LDE Property of TheSystem. That Property returns an Interface called ILensDataEditor. As can be seen, the ZOS-API is built on a hierarchy of Interfaces.

The Object creation is called an Instantiation. The TheLDE object is an instance of the class ILensDataEditor. The Functions and Properties of the ILensDataEditor Interface are then available for the TheLDE Object .

In the Help File, to see the attributes of the ILensDataEditor Interface, click on ILensDataEditor.

Click ILensDataEditor



In the ILensDataEditor Interface, there are Properties and Functions. But there are also Inherited Properties from the IEditor Class:


Inherited properties


The IEditor Class is called a Parent Class. The IEditor Parent Class defines common characteristics to all editors.
The ILensDataEditor Child Class defines Functions and Properties specific to the Lens Data Editor.

Let’s click on IEditor. It shows the inheritance diagram.


Inheritance diagram


All Properties and Functions of the Parent Class will be accessible to the Child Class.

For example AddRow() is a Property common to all editors. It is defined in the Parent Class and accessible to Child Classes.




ZOS-API structure at a glance

The image below summarizes the ZOS-API structure:


Reminder of the terminology



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



Article is closed for comments.