Generate the executable in Python for ZOS-API User Extensions

Abstract

This article will show how to create a Python executable which can be used as ZOS-API User Extension with a sample code written in Python. Python executable files are compiled executable which can be used as small extensions to OpticStudio from our User Extensions functionality. Python executable are easy and secure way to share the Python User Extensions. Clicking on the Python executable name will execute that extension.

Authored By Nicolas Azais, Iridescence S.A.R.L.

download example (.zip)

A brief description of the User Extension

OpticStudio  allows the user to integrate an application program using ZOS API as a User Extension. Basically, it’s the user program bundled in an .exe file under ZEMAX_FOLDER\ZOS-API\Extensions.

Project Setup

• The pre-requisites in order to have the support of the ZOS-API User Extension are the following: Have OpticStudio  20.1 or higher installed
• Set up ZOS-API with Python.NET (see this article for detailed explanations)
• Have the python module numpy installed (in the command prompt, type python -m pip install numpy)
• Have the python module matplotlib installed (in the command prompt, type python -m pip install matplotlib==XX.XX.XX)
• Have the python module pyinstaller (in the command prompt, type python -m pip install pyinstaller)
• Have the folder PYTHON_FOLDER\Scripts (for instance: C:\Python38\Scripts) declared as a PATH environment variable. This article explains how to add an environment variable for Windows 10

A Basic Example

Source Example

We will use one of the code samples provided in the ZOS-API Documentation: Example 02: NSC Ray Trace. Hereafter the python code sample, using the Standalone Application (Source file: PythonStandalone_02_NSC_ray_trace.py in the ZOS-API Sample Code folder):

 

 

Basically, this code opens the Zemax File located in ZEMAX_FOLDER\Samples\Non-sequential\ Miscellaneous\Digital_projector_flys_eye_homogenizer.zmx, launches a Ray Tracing operation, and displays the result on the detector, using the matplotlib library.

 

We can transpose this Standalone Application code into a User Extension code following these steps, described in the sections below:

1. Create a Python class PythonUserExtension
2. Use this new class within the code sample and create a .exe file using the pyinstaller library
3. Open in a OpticStudio instance the Digital_projector_flys_eye_homogenizer.zmx and execute the generated User Extension.

The PythonUserExtension class

The following class has to be used in a ZOS-API User Extension code written in Python.

 

 

In the main code, we now have to call this class (instead of the PythonStandaloneApplication class). Moreover, there is no need to keep the code that loads the Zemax File (the User Extension will be called in the opened instance). Hereafter the reworked main part of the example:

 

 

Generate the executable

We now have a reworked python code sample, nscraytrace_user_extension.py (attached to this article), and we have to generate a .exe file in order to use it as an User Extension.

 

For this purpose, the python library pyinstaller can be used. In your working folder, open the command prompt and type:

 

 

This will generate a dist folder, and within it a .exe file nscraytrace_user_extension.exe that can be used as an User Extension. The pyinstaller module will also generate a pycache and a build subfolders : these folders and their content can be deleted.

 

Note that the --onefile option bundle the script and all its dependencies into a single executable. This is the simplest solution, considering that the executable has to be launched from a OpticStudio instance, but pyinstaller provides other bundling possibilities.

 

Using the extension

All there is to do now is to copy the executable file nscraytrace_user_extension.exe into ZEMAX_FOLDER\ZOS- API\Extensions folder. Then, open a OpticStudio  instance and load the file ZEMAX_FOLDER\Samples\Nonsequential\Miscellaneous\Digital_projector_flys_eye_homogenizer.zmx. Our program should be in the User Extension list:

 

 

This extension can be launched, and works exactly as the standalone application code.

 

Conclusion

This article has shown how to make a ZOS-API User Extension with a Python script. It was illustrated with a basic example, but with the Python script boilerplate attached to this article (PythonUserExtension.py), it can be used with any Python script using ZOS-API.