This article will walk through the basics of getting Python set up on your system in order to run ZOS-API.

Authored By Michael Humphreys, Edited By Alexandra Culler

Introduction

This article shows what needs to be installed in order to get Python running and communicating with ZOS-API.

Disclaimer

Zemax LLC does not officially support or endorse any of the following software or products. The views and opinions expressed in this article are those solely of the author, who is a Zemax employee, and these are only provided as guidance for other users of the ZOS-API to help get started.

 

Communicating with ZOS-API

ZOS-API is written as a .NET library and using languages that can directly communicate with .NET gives the most flexibility and the best performance. The Python.NET allows this direct communication and is the preferred method to communicate with ZOS-API. 
For more information about Python.NET, please read "ZOS-API using Python.NET".

Another method to connect Python to the ZOS-API is using COM with the pywin32 module. Because ZOS-API is written as a .NET library, it uses win32com to communicate with pure COM based languages. 

 

Installing Python

To use Python with ZOS-API, you need to install both Python and a module to communicate with ZOS-API. It can be Python.NET (recommended one) or pywin32 module that allows Python to communicate with other COM based Windows applications. 

The latest version of Python can be found at https://www.python.org/downloads/windows/. 
There are 2 main branches of Python: 2.7.x and 3.x. The ZOS-API can be used with either branch and for either the 32-bit or 64-bit version of Python. The Python organization has decided to maintain security patches for 2.7.x, but no new features are being added to that branch. If you do not currently have Python installed on your system, you should install the 3.x version of Python to get the latest features.

 

If multiple users:

When installing Python, if you expect to have multiple people using the computer, you should not install Python to the default location. The default location will be under your own user directory which may not be available to others depending on their permission levels.  You should install Python to the C:\ directory (if you don’t have permission, contact your Administrator and have that person install the software). 

• If you are installing Python 2.7, I would recommend installing it at C:\Python27.
• If you are installing Python 3.x, I would recommend installing it at C:\Python3x. 

 

PATH environment variable:

Next, you should change your PATH environment variable to include the Python path.  You can accomplish this by clicking on the Start icon and typing in “environment variables”.

 

 

Make sure that you have administrator rights when you navigate to these settings. If you're not sure, go through your Control Panel. Navigate to Control Panel...System...Advanced System Settings. 

 

 

Next, in the System Variables, highlight “Path” and click "Edit".  If there is no System Variable named Path yet, click on "New" and name it Path (it is highly likely that this variable is already created so make sure you check twice before creating a variable named Path).

 

 

Then click “New” and enter in the path to your Python directory. Then, click OK enough times to exit out of the System Properties dialog box.

 

 

Now you’ll be able to open a CLI window and simply use the “python” word to call the Python executable in the path you just installed.

 

Importing modules

• Python.NET (recommended):
  Ensure you are running Python 3.4, 3.5, 3.6, 3.7, or 3.8. PythonNET is continually updated to work with more recent editions of Python, but Zemax staff has not tested compatibility with any versions later than 3.8.
  Install pythonnet installed from pip or check it is installed.
  Open a Command Prompt window and type:
  python -m pip install pythonnet
  The message below means that pythonnet is installed:
  
  

 

• pywin32 (if not using Python.NET):
  To connect Python to the ZOS-API using COM, install the Python extension called pywin32 that implements win32com. There are 2 versions of the pywin32 module, a 32-bit and a 64-bit. There is a random issue with how the 32-bit pywin32 handles specific interfaces, so we recommend only using 64-bit Python along with 64-bit pywin32 module. The ZOS-API can run with either Python 2.x or Python 3.x as long as the pywin32 is 64-bit and references the correct Python build. 
  The newest pywin32 builds can be found at https://github.com/mhammond/pywin32/releases. 

 

• Matplotlib: The vanilla version of Python is powerful, but one of the best features about Python is the open-source nature of community and the modules you can import into your script. In order to get Matlab™-like features in Python, you can install matplotlib (https://en.wikipedia.org/wiki/Matplotlib), which is a plotting library and is based on NumPy, a numerical mathematics extension for Python. 
  To install matplotlib, you can simply use pip, which comes packaged with the standard Python installation. Older versions of pip will not successfully install matplotlib, so you might want to update pip before installing matplotlib. If you have just installed Python with this tutorial, you can skip to step 3 below. 
  1. You can use the following CLI command to check the pip version:
  python -m pip -–version
  2. To upgrade pip, you can use the following CLI command:
  python -m pip install --upgrade pip
  3. To install matplotlib, you can use the following CLI command:
  python -m pip install matplotlib
  You should get a command window like the one shown below:
  
  

 

At this point, you should be able to run both basic ZOS-API code as well as all of the sample files. 

 

Integrated Development Environment (IDE)

It is highly recommended to use an IDE when writing your Python script.  Although you can use any plain text editor to write a Python script (such as Notepad or Notepad++), or Python's own IDLE, an IDE provides the ability to debug a Python script and view the attributes of a given object, similar to Code Completion in Visual Basic™ or Matlab™.  Jet Brains offers a community edition of their PyCharm (https://www.jetbrains.com/pycharm) IDE which is what this author uses. PyCharm provides code completion, syntax error checking, a built-in console, and a debugging tool with break points. This last feature is one of the best features of the IDE since you can inspect the properties of any object in the ZOS-API environment.

For example, if you want to inspect the properties of an NSCRayTrace, you can insert a breakpoint below the object by left clicking on the sidebar below the object you want to inspect.  Then, right click on the main window and select “Debug” rather than “Run”.

 

 

Then, in the Variables list, you can expand the variable and then expand the _prop_map_get_ property.

 

 

To run code in the Pycharm IDE, the "python.exe" file that corresponds to your latest download must be set as the system interpreter. You can check to ensure this is the case in Settings by clicking Ctrl+Alt+S. Once there, find your project title on the left hand side and click "Project Interpreter". If you have the proper interpreter set, you should see a window like the one below.

 

 

If this is not what you see, then you will have to manually add the interpreter by clicking on the settings icon and selecting "Add...".

 

 

Then, under "System Interpreter" use the three dots to find "python.exe". If you followed the steps in this article, the address should be similar to "C:\PythonXX\python.exe".

 

Troubleshooting Python

Pywin32 Wrappers

If you are connecting Python to the ZOS-API using COM, anytime you change either the OpticStudio environment or the Python environment, you might “break” the wrappers for pywin32.  Each boilerplate template has instructions at the top of the script to walk you through re-registering the wrappers, but here is a detailed instruction:

1. Navigate to {Python}\Lib\site-packages\win32com\gen_py\*.* and delete all the filed in that (gen_py) directory.
2. Open a Windows "cmd” window (Windows Key + R -> type “cmd” -> press “Enter”)
3. Change directory to your {PythonEnv}\Lib\site-packages\wind32com\client\ folder (i.e., “cd C:\Python27\Lib\site-packages\win32com\client”)
4. Type “python makepy.py” and press enter.  When the Select Library window pops up, use the Ctrl key to select both the ZOSAPI and the ZOSAPI_Interfaces and click OK.
   
   

 

Note on troubleshooting with alternate Python distributions and IDEs

Some Python environments will make a copy of the Python download to an alternate program-specific folder. Two examples are the Visual Studio IDE and Anaconda distribution. These alternate locations will be where the gen_py folder is stored. To troubleshoot with these types of programs, perform the steps above at the copied location. The alternative locations may look something like the following:

• Visual Studio: C:\Users\Username\AppData\Local\Programs\Python\Python37
• Anaconda: C:\Users\Username\AppData\Local\Temp\gen_py\3.7 or C:\Users\xxx\Anaconda\Python

You can pin this alternative location to your Windows File Explorer by right-clicking on the folder name and clicking "Pin to Quick access". This will make it available on the left-hand side of the File Explorer at all times. 

 

Example files

Example files are included with your installation of OpticStudio and are located in the {Zemax}\ZOS-API Sample Code folder. Some sample require NumPy and matplotlib to be installed before running these files. As long as those libraries are installed, an example may be run directly from the sample code folder. OpticStudio is not required to be opened for those, as they are Standalone Applications. 

For information on running an Interactive Extension, see "Connect to OpticStudio from Python with the ZOS-API Interactive Extension."

KA-01620