zospy.zpcore.ZOS#

class zospy.zpcore.ZOS#

Bases: object

A Communication instance for Zemax OpticStudio.

This class can be used to establish a link between Python and Zemax OpticStudio through .NET, and subsequently control OpticStudio. Only one instance of ZOS can exist at any time.

The connection is established in two ways, the preferred method as wel as a legacy method for backwards compatability. See examples.

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.

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:

>>> import zospy as zp
>>> zos = zp.ZOS()
>>> oss = zos.connect_as_extension(return_primary_system=True)

Launching OpticStudio in standalone mode:

>>> import zospy as zp
>>> zos = zp.ZOS()
>>> oss = zos.create_new_application(return_primary_system=True)

Legacy methods:

Connecting as extension:

>>> import zospy as zp
>>> zos = zp.ZOS()
>>> zos.wakeup()
>>> zos.connect_as_extension()
>>> oss = zos.get_primary_system()

Launching OpticStudio in standalone mode:

>>> import zospy as zp
>>> zos = zp.ZOS()
>>> zos.wakeup()
>>> zos.create_new_application()
>>> oss = zos.get_primary_system()

Attributes:

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

Methods

`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.
`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.
`wakeup`([preload, zosapi_nethelper])	Wake the zosapi instance.

__init__(preload: bool = False, zosapi_nethelper: str = 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 | 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.

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

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

Connect to Zemax OpticStudio as extension.

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.

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.

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.

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”]

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

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

Wake the zosapi instance.

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.

Returns:

None

zospy.zpcore.ZOS

Contents

zospy.zpcore.ZOS#