zospy.zpcore.ZOS

zospy.zpcore.ZOS#

class zospy.zpcore.ZOS#

Bases: object

A Communication instance for Zemax OpticStudio.

This class manages the connection between Python and Zemax OpticStudio through .NET, and controls OpticStudio instances. Only one instance of ZOS can exist at any time. If a second instance is attempted to be created, the existing instance is returned.

Parameters:

preloadbool: A boolean indicating if nested namespaces should be preloaded upon initiating ZOS. Defaults to False.
zosapi_nethelperstr | None: Optional filepath to the ZOSAPI_NetHelper dll that is required to connect to OpticStudio. If None, the Windows registry will be used to find the ZOSAPI_NetHelper dll. Defaults to None.
opticstudio_directorystr, optional: Path to the directory containing the OpticStudio DLLs. If None, the directory will be acquired through the zosapi_nethelper. Note that either the zosapi_nethelper or the opticstudio_directory has to be specified, not both.

Attributes:

ZOSAPINone | netModuleObject: The ZOSAPI interface once loaded, else None.
ZOSAPI_NetHelperNone | netModuleObject: The ZOSAPI_NetHelper interface once loaded, else None.

Methods

`connect`([mode, instance_number, message_logging])	Connect to Zemax OpticStudio.
`create_new_system`([system_mode])	Create a new OpticStudioSystem.
`disconnect`()	Disconnect from the connected OpticStudio instance.
`get_instance`()	Get the current instance of ZOS.
`get_primary_system`()	Get the primary optical system.
`get_system`([pos])	Get the optical system at the specified position.
`get_txtfile_encoding`()	Determine the encoding used to write text files in OpticStudio.
`retrieve_logs`()	Retrieve messages logged by OpticStudio.

Examples

Preferred methods:

Connecting as extension:
Make sure OpticStudio is running and the “Interactive Extension” mode in the programming tab is active.
>>> import zospy as zp >>> zos = zp.ZOS() >>> oss = zos.connect(mode="extension")

Launching OpticStudio in standalone mode:

>>> import zospy as zp
>>> zos = zp.ZOS()
>>> oss = zos.connect(mode="standalone")

__init__(*, preload: bool = False, zosapi_nethelper: str | None = None, opticstudio_directory: str | None = None)#

Initiate the OpticStudio API.

The ZOS instance can subsequently be used to connect to OpticStudio. See the examples in the class docstring for more information.

Parameters:

preloadbool: A boolean indicating if nested namespaces should be preloaded upon initiating ZOS. Defaults to False.
zosapi_nethelperstr, optional: Path to the ZOSAPI_NetHelper dll that is required to connect to OpticStudio. If None, the Windows registry will be used to find the ZOSAPI_NetHelper dll. Defaults to None.
opticstudio_directorystr, optional: Path to the directory containing the OpticStudio DLLs. If None, the directory will be acquired through the zosapi_nethelper. Note that either the zosapi_nethelper or the opticstudio_directory has to be specified, not both.

static __new__(cls, *args, **kwargs)#

Ensure that only one instance of ZOS exists at any time.

If a ZOS instance already exists, the existing instance is returned. If not, a new instance is created.

connect(mode: Literal['standalone', 'extension'] = 'standalone', instance_number: int | None = None, *, message_logging: bool = True) → OpticStudioSystem#

Connect to Zemax OpticStudio.

The application will be assigned to ZOS.Application.

Parameters:

modestr: Connection mode, either “standalone” or “extension”. Default is “standalone”. In standalone mode, ZOSPy initializes a new, invisible OpticStudio instance and connects to this instance. In extension mode, ZOSPy connects to an already open instance of OpticStudio in “Interactive Extension” mode.
instance_numberint, optional: An integer to specify the number of the instance used. Only applicable in extension mode.
message_loggingbool, optional: If True, OpticStudio’s message logging will be enabled after establishing a connection.

Returns:

OpticStudioSystem: The primary optical system of the connected OpticStudio instance.

create_new_system(system_mode: constants.SystemType | str = 'Sequential') → OpticStudioSystem#

Create a new OpticStudioSystem.

This works only if ZOSPy is connected to a standalone application.

Parameters:

system_modeconstants.SystemType | str: The mode of the new system, must be one of “Sequential”, “NonSequential”. Defaults to “Sequential”.

Returns:

OpticStudioSystem: The new OpticStudioSystem.

disconnect()#

Disconnect from the connected OpticStudio instance.

When connected in standalone mode, this closes the standalone OpticStudio instance. When connected in extension mode, this closes the connection but keeps the OpticStudio instance open.

classmethod get_instance() → ZOS | None#

Get the current instance of ZOS.

Unlike __new__, this method does not create a new instance if none exists.

Returns:

ZOS | None: The current instance of ZOS, or None if no instance exists.

get_primary_system() → OpticStudioSystem#

Get the primary optical system.

Returns:

OpticStudioSystem: Primary optical system.

get_system(pos: int = 0) → OpticStudioSystem#

Get the optical system at the specified position.

Parameters:

posint: Index of the optical system. If 0, the primary system is returned.

Returns:

OpticStudioSystem: Optical system at position pos.

get_txtfile_encoding() → str#

Determine the encoding used to write text files in OpticStudio.

Returns:

str: The encoding used for textfiles by OpticStudio

Raises:

RuntimeError: When ZOS does not have a connection to the OpticStudio application
NotImplementedError: When the ZOS.Application.Preferences.General.TXTFileEncoding is not one of [“Unicode”, “ANSI”]

retrieve_logs() → str#

Retrieve messages logged by OpticStudio.

Returns:

str: Messages logged by OpticStudio.

property version: Version#: Returns the OpticStudio version as Version object.

zospy.zpcore.ZOS

Contents

zospy.zpcore.ZOS#