Connect to OpticStudio from Python with the ZOS-API Interactive Extension

This article is part of the Getting Started with ZOS-API free tutorial.

This article demonstrates how to connect to the ZOS-API with the Interactive Extension using Python. Once connected to OpticStudio, an Interactive Extension can perform any task that a User Extension is capable of and the OpticStudio Interface will interactively display the result of that task.

Authored By Sandrine Auriol



The Interactive Extension mode is almost identical to a User Extension except an Interactive Extension does not have to be a standalone executable. This capability allows connections from scripting environments such as Matlab or Python where there is no compiled executable that OpticStudio can launch.

The Interactive Extension interactively controls the OpticStudio Interface from external scripting environment. That article will explain how to connect OpticStudio with the Interactive Extension.

Creating an Interactive Extension script

To create a boilerplate template to connect to the Interactive Extension, click Programming...Python...Interactive Extension.


Programming > Python > Interactive Extension


The script will be placed in the ZOS-API Project Folder:  ..\Documents\Zemax\ZOS-API Projects\PythonZOSConnection

If more than one Interactive Extension is created, then the file names will be sequentially numbered.


The software will open the File Explorer at the file location:

File Explorer


Connecting to the Interactive Extension

To start the Interactive Extension, click Programming...Interactive Extension.


Programming > Interactive Extension


A dialog window will open, and OpticStudio will wait for an external application, in this case Python, to connect.


Interactive Extension Window


The dialog box shows the instance ID for the running instance of OpticStudio. This allows Python to connect to a specific instance of OpticStudio if more than one instance is running.


The next step depends on the Integrated Development Environment (IDE) being used.


IDLE (Native IDE that comes with Python)


Edit with IDLE


  • Run the code


Run Module


  • The status of the Interactive Extension shows the extension is now connected.


Status Connected


  • Individual commands can now be executed in the Python Command Window. 
    For example, a sample file can be loaded:

Python Shell


  • The open instance of OpticStudio will display the loaded file and the Python command window will return the Boolean value True as the file has been successfully loaded.

OpticStudio Connected


Python Shell returns True


  • Once the command has been executed, the shell displays “>>>” meaning that it is ready for a new command.


PyCharm IDE:

  • In PyCharm open the code of
  • Right click and select “Run File in Console”:

PyCharm Run File in Console


  • The Console window will indicate the status of the connection. Then individual commands can be executed in the Console.

PyCharm connection


The right pane displays the variables available for the project.

It means that there is an “Intellisense” when working with the Interactive Extension.




Blocks of codes can also be executed. For example, open the attached file. This script is an extract from the sample file "\Zemax\ZOS-API Sample Code\Python\". The lines of code related to the connection to ZOS-API have been removed.

Select the script. Right-click and select “Execute Selection in Console”.


Execute Selection in Console


OpticStudio displays the newly created file.

OpticStudio displaying the created file


And the Console shows the new variables:


Variables in the Console


Terminating the connection

The connection can be terminated either by clicking Terminate in the Interactive Extension dialog box


Terminate Interactive Extension


or by running the CloseApplication method in the Python Command Window





This article is part of the Getting Started with ZOS-API free tutorial.

Previous article: Creating a Standalone Application I: MATLAB & ZOS-API.NET
Next article: Interactive Extension: FAQ


Was this article helpful?
8 out of 9 found this helpful



Article is closed for comments.