Getting Started with Python

This article will walk through the basics of getting Python setup on your system in order to run ZOS-API.  There are 2 required downloads (Python and pywin32) along with a few recommended downloads (an IDE and Python modules).  Except for the 2 required downloads, all other recommendations are based on a Zemax Engineer's personal preference and do not reflect an official endorsement as to the quality of these products or any competitiors.

CONTENTS:
Michael Humphreys
11/14/2016
ZOS-API, ZOS-API.NET


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.

Note on Python 3.6 Compatability Issues

The newest version of Python, 3.6, currently has known compatability issues with pywin32.  In following this tutorial, it is recommended to install version 3.5 to avoid problems in the pywin32 install, until further notice.
 

Installing Python

To use Python with ZOSAPI, you need to install both Python and the pywin32 module that allows Python to communicate with other COM based Windows applications.  Note that pywin32 is not officially part of the Python install and you will need to install it after you have installed Python.  The latest version of Python can be found at https://www.python.org and the main repository for pywin32 is located at https://sourceforge.net/projects/pywin32/.  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.


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 user directory and depending on the permission levels of the next user, they might not be able to use Python properly.  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 and if you are installing Python 3.x, I would recommend installing it at C:\Python3x
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”. 



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.  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.
The pywin32 module needs to match both your version and bit of Python.  If you have a 64 bit version of Python, the filename for pywin32 will look like pywin32-220.win-amd64-py3.x.exe and if you have a 32 bit version of Python, the filename for pywin32 will like pywin32-220.win32-py3.4.exe.

Recommended Modules

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.  Note that 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 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 which looks like below


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

 

IDE

It is highly recommended to use an Integrated Development Environment (IDE) when writing your Python script.  Although you can use any plain text editor to write a Python script (such as Notepad or Notepad++), 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 ZOSAPI 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.


Troubleshooting Python

Pywin32 Wrappers

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


You can use the following script to automate this process.  To use the script, copy and paste the text into a text file.  Then, rename the text file from TXT to BAT.  Note, you should verify compatibility of this script with your version of Windows and your corporate policy on running batch files.  Zemax LLC provides this code as-is and does not take any responsibility misuse or abuse of this code.  Note that you should not have to change any of the paths in the following script.

::parses the Python environmental path
@ECHO OFF
echo.
FOR /f %%p in ('where python') do SET PYTHONPATH=%%p
setlocal enabledelayedexpansion
set S=%PYTHONPATH%
set I=0
set L=-1
:l
if "!S:~%I%,1!"=="" goto ld
if "!S:~%I%,1!"=="\" set L=%I%
set /a I+=1
goto l
:ld
 
::creates gen_py and makepy.py directory path variables
SET root=!PYTHONPATH:~0,%L%!
SET folder=%root%\Lib\site-packages\win32com\gen_py
SET makepy=%root%\Lib\site-packages\win32com\client\makepy.py
 
::deletes gen_py file and subfolders
cd /d %folder%
for /F "delims=" %%i in ('dir /b') do (del "%%i" /s/q)
 
::creates a python variable to call rather than the ENV variable
SET py=%root%\python.exe
 
::run the make_py python script
ECHO.
ECHO. "building ZOSAPI..."
ECHO.
%py% %makepy% ZOSAPI
ECHO.
ECHO. "building ZOSAPI_Interfaces..."
ECHO.
%py% %makepy% ZOSAPI_Interfaces
ECHO.
 
endlocal
 
cd %mypath%
 
::timeout /t 10
ECHO.
ECHO. "Finished building ZOSAPI/ZOSAPI_Interfaces"
pause

Example Files

There are 4 example files for Matlab™ that are included with your installation of OpticStudio and are located in the Zemax\ZOS-API Sample Code folder.   These example files are discussed in detail in the Matlab & ZOS-API.NET webinar.  Two of these files (new_file_and_quickfocus and open_file_and_optimise) can be run directly from Python without any extra modules but the two files that graph information (NSC_ray_trace and pull_data_from_FFTMTF) require NumPy and matplotlib discussed above.  Please install matplotlib before running these files.