PyZDDE 2.0.3

Current revision

2.0.3 (Last significant update on 10/02/2016)

Examples

Examples included with PyZDDE are in the folder “Examples”. Please move the examples to your desired location after extracting the PyZDDE package.

import pyzdde.zdde as pyz
ln = pyz.createLink() # DDE link object
print("Hello Zemax version: ", ln.zGetVersion())
ln.close()

Install PyZDDE from PyPI

You can either use pip or the setup.py script from the extracted folder.

Use the following command from the command line to install PyZDDE from PyPI:

pip install pyzdde

Note 1. By default only the latest stable version is installed by default, using the above command. To install pre-release versions add the –pre flag:

pip install pyzdde --pre

Note 2. When you install PyZDDE using pip (the above method), the “Examples” folder will not be downloaded. However, pip is the most convenient way to install Python packages. Also, ensure that you have the pip package in your environment.

If you would like to download the “Examples” folder too, please download and extract PyZDDE package from the Python Package Index. Then, cd into the extracted folder where the setup.py script is visible and execute the following in a command prompt:

python setup.py install

If you would like to see what files were added and where you may use:

python setup.py install --record files.txt

A list of all files that were added and their locations will be available in the file “files.txt” in the same directory.

Note 3. To uninstall pyzdde using pip use

pip uninstall pyzdde

Get the latest code

To get the latest PyZDDE code please download / fork / clone from GitHub repository.

Documentation

The PyZDDE documentation is currently hosted in the GitHub Wiki.

Initial setup

1. PUSH LENS PERMISSION: All operations through the DDE affect the lens in the DDE server (except for array ray tracing). In order to copy the lens from the DDE server to the Zemax application /LDE, you need to “push” the lens from the server to the LDE. To do so, please enable the option “Allow Extensions to Push Lenses”, under File->Preferences->Editors tab.

2. ANSI/UNICODE TEXT ENCODING: PyZDDE supports both ANSI and UNICODE text from Zemax. Please set the appropriate text encoding in PyZDDE by calling module function pyz.setTextEncoding(text_encoding) (assuming that PyZDDE was imported as import pyzdde.zdde as pyz). By default, UNICODE text encoding is set in PyZDDE. You can check the current text encoding by calling pyz.getTextEncoding() function. Please note that you need to do this only when you change the text setting in Zemax and not for every session.

3. PURE NSC MODE: (This is more of a note) If want to work on an optical design in pure NSC mode, please start ZEMAX in pure NSC mode before initiating the communication with PyZDDE. There is no way to switch the ZEMAX mode using external interfaces.

ZPL macros files supplied with PyZDDE

PyZDDE comes with few ZPL macro files that are present in the directory “ZPLMacros”. They are occasionally used by PyZDDE (for example in the function ipzCaptureWindowLQ()). Please copy/move the files from the folder “ZPLMacros” to the folder where Zemax/ Optic studio expects to find ZPL macros (By default, this folder is C:\<username>\Documents\ZEMAX\Macros). A copy of the “ZPLMacros” folder is always available in (installed with) the PyZDDE package.

Modules in PyZDDE

• zdde (import pyzdde.zdde as pyz): The main module in PyZDDE that provides all dataitems related functions for interacting with Zemax/OpticStudio using the DDE interface.

• arraytrace (import pyzdde.arraytrace as at): provides functions for tracing large number of rays

• zfileutils (import pyzdde.zfileutils as zfu): provides helper functions for various Zemax file handling operations such as reading and writing beam files, .ZRD files, creating .DAT and .GRD files for grid phase /grid sag surfaces, etc.

• systems (import pyzdde.systems as osys): provides helper functions for quickly creating basic optical systems.

• misc (import pyzdde.misc as mys): contains miscellaneous collection of utility functions that may be used with PyZDDE.

import pyzdde.zdde as pyz    # import pyzdde module
ln = pyz.createLink()        # create DDE link object
ln.zPushLens(1)              # method of type 1
ln.zExecuteZPLMacro('CEN')   # method of type 2
ln.ipzCaptureWindow2('Lay')  # method of type 3

pyz.zo.findZOperand("decenter")  # method of type 4 (same as pyz.findZOperand)
pyz.numAper(0.25)                # method of type 4

Dependencies

The core PyZDDE library only depends on the standard Python Library.

1. Python 2.7 / Python 3.3 and above; 32/64 bit version

2. Matplotlib (optional, used in some of the example programs)

License

The code is under the MIT License.

Contributions and credits

You are encouraged to use, provide feedbacks and contribute to the PyZDDE project. The generous people who have contributed to PyZDDE are in Contributors. Thanks a lot to all of you.

Other projects that are using PyZDDE are listed here.

Citing

If you use PyZDDE for research work, please consider citing it. Various citation styles for PyZDDE are available from zenodo.

Chat room