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

Introduction

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

 

 

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. 

 

 

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.
  
  
   
• 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:
  
  

 

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.

 

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.

 

Inheritance

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

 

 

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.

 

 

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

• Namespace: is a library containing a hierarchy of Interfaces and Classes.
  https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/namespaces/index

• Class: is a data structure that encapsulates a set of data and behaviors. The Class contains Properties and Functions. When a Class is used, the code tells in which Namespace the Class is. The code can either import the Namespace by writing using Namespace or give the fully qualified type name including namespace, for example Namespace.Class.

• Interface: is a Class template; it contains definitions for functionalities that a Class can implement. In ZOS-API, Class names preceded by the letter I are Interfaces. Interfaces are interesting because of Inheritance.
  A Class can inherit one Class (Single Inheritance)
  A Class and an Interface can inherit several Interfaces (Multi Inheritance).
  https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/interfaces/index

• Object: is a variable. It is a member/ an instance of a Class/Interface.
  https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/objects

• Member: represents the data and behavior of classes. It can be the properties or the functions of the classes.
  https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/members

• Enumeration: is a distinct type that consists of a set of named constants called the enumerator list. The enum keyword is used to declare an enumeration.
  https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/enum

• Inheritance: is one of the fundamental attributes of object-oriented programming. It allows to define a Child Class that reuses (inherits), extends, or modifies the behavior of a Parent Class.
  https://docs.microsoft.com/en-us/dotnet/csharp/tutorials/inheritance

 

KA-01805