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.
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.
This is a useful feature because the program can work directly with the opened instance of Zemax, and the end user of the script doesn’t have to set up a development environment. However, this feature is only available for C++ and C# languages. For Python, there are only samples of codes for the Interactive Extension or the Standalone Application.
Nevertheless, ZOS-API User Extension can be supported in Python with a small modification of the Standalone Application sample code.
- 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
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:
- Create a Python class PythonUserExtension
- Use this new class within the code sample and create a .exe file using the pyinstaller library
- 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.
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.