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.

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.

Raises:

ValueError: When it is attempted to initiate a second instance of ZOS. Only one instance can exist at any time.

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")

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.
`connect_as_extension`([instancenumber, ...])	Connect to Zemax OpticStudio as extension.
`connect_as_standalone`([return_primary_system])	Creates a standalone Zemax OpticStudio instance.
`create_new_application`([return_primary_system])	Create a standalone Zemax OpticStudio instance.
`create_new_system`([system_mode])	Creates a new OpticStudioSystem.
`disconnect`()	Disconnect from the connected OpticStudio instance.
`get_primary_system`()	Get the primary optical system.
`get_system`([pos])	Get the optical system at the specified position.
`get_txtfile_encoding`()	Determines the encoding used to write textfiles in OpticStudio.
`retrieve_logs`()	Retrieve messages logged by OpticStudio.
`wakeup`([preload, zosapi_nethelper])	Wake the ZOS-API.

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

Initiation of the ZOS instance.

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)#

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.

connect_as_extension(instancenumber: int = 0, return_primary_system: bool = False) → bool | OpticStudioSystem#

Connect to Zemax OpticStudio as extension.

Deprecated since version 1.2.0: This method is deprecated and will be removed in ZOSPy 2.0.0. Use ZOS.connect(“extension”) instead.

The application will be assigned to ZOS.Application.

Parameters:

instancenumberint, optional: An integer to specify the number of the instance used.
return_primary_system: bool, optional: A boolean indicating if the primary OpticStudioSystem should be returned. Defaults to False.

Returns:

bool | OpticStudioSystem: True if a valid connection is made, else False. If return_primary_system is True, the function returns the primary OpticStudioSystem.

connect_as_standalone(return_primary_system: bool = False) → bool | OpticStudioSystem#

Creates a standalone Zemax OpticStudio instance.

..deprecated:: 2.0.0: This method is deprecated and will be removed in ZOSPy 2.0.0. Use ZOS.connect() instead.

Equal to ZOS.create_new_application.

Parameters:

return_primary_systembool, optional: A boolean indicating if the primary OpticStudioSystem should be returned. Defaults to False.

Returns:

bool | OpticStudioSystem: True if a valid connection is made, else False. If return_primary_system is True, the function returns the primary OpticStudioSystem. runs ZOS.get_primary_system() and directly returns OpticStudioSystem.

create_new_application(return_primary_system: bool = False) → bool | OpticStudioSystem#

Create a standalone Zemax OpticStudio instance.

Deprecated since version 1.2.0: This method is deprecated and will be removed in ZOSPy 2.0.0. Use ZOS.connect() instead.

The application will be assigned to ZOS.Application.

Parameters:

return_primary_systembool, optional: A boolean indicating if the primary OpticStudioSystem should be returned. Defaults to False.

Returns:

bool | OpticStudioSystem: True if a valid connection is made, else False. If return_primary_system is True, the function returns the primary OpticStudioSystem.

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

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

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#

Determines the encoding used to write textfiles 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.

wakeup(preload: bool = False, zosapi_nethelper: str = None)#

Wake the ZOS-API.

Deprecated since version 1.1.0: wakeup will be removed in ZOSPy 2.0.0, as it is automatically called by __init__.

The parameters are passed to self._load_zos_dlls().

Parameters:

preloadbool: A boolean indicating if nested namespaces should be preloaded.
zosapi_nethelperstr, optional: File path to the ZOSAPI_NetHelper dll, if None, the Windows registry will be used to find ZOSAPI_NetHelper dll. Defaults to None.

zospy.zpcore.ZOS

Contents

zospy.zpcore.ZOS#