连接到 OpticStudio

连接到 OpticStudio#

要使用 ZOSPy，您需要连接到 OpticStudio。这可以通过两种方式完成：

  1. 独立模式：脚本完成后，将启动一个新的、不可见的 OpticStudio 实例并关闭。这是 ZOSPy 使用的默认模式。这也是性能最高的选项，因为更新 GUI 似乎会显著减慢模拟速度。

  2. 扩展模式：脚本连接到已运行的 OpticStudio 实例。为了能够在扩展模式下连接，必须在 OpticStudio 中激活“交互式扩展”模式。这对于调试或当您想要在 GUI 中查看模拟进度时很有用。

以独立模式连接#

要以独立模式连接 OpticStudio，请使用以下代码：

import zospy as zp

# Initialize the ZOS-API connection
zos = zp.ZOS()

# Connect the ZOS-API to OpticStudio in standalone mode
oss = zos.connect()

# Alternatively, the standalone mode can be explicitly specified:
oss = zos.connect("standalone")

以扩展模式连接#

要以扩展模式连接到 OpticStudio，首先在 OpticStudio 的“编程”>“交互式扩展”下启用“交互式扩展”模式。

互动扩展

然后，使用以下代码以扩展模式连接到 OpticStudio：

import zospy as zp

# Initialize the ZOS-API connection
zos = zp.ZOS()

# Connect the ZOS-API to OpticStudio in standalone mode
oss = zos.connect("extension")

连接到特定版本的 OpticStudio#

默认情况下，ZOSPy 从 Windows 注册表中检索 OpticStudio 安装目录的路径。如果您安装了多个版本的 OpticStudio，则可以通过指定 OpticStudio 可执行文件的路径来连接到特定版本：

import zospy as zp

zos = zp.ZOS(opticstudio_directory="path/to/opticstudio")

备注

您需要指定 OpticStudio 目录的路径，而不是可执行文件本身的路径。ZOSPy 使用此路径来加载 ZOS-API 程序集。:::

{py:class} ZOS <zospy.zpcore.ZOS>和 {py:class} OpticStudioSystem <zospy.zpcore.OpticStudioSystem>之间的区别

如上所示，与 OpticStudio 的连接通过两个对象进行管理：

  • zos ，类型为 {py:class} ZOS <zospy.zpcore.ZOS> ；

  • oss ，类型为{py:class} OpticStudioSystem <zospy.zpcore.OpticStudioSystem> 。

这两个类之间的差异常常会让人产生混淆。虽然理论上可以将这两个类合并起来，但这会对用户体验产生负面影响，并使一些更高级的用例变得不可能。

ZOS 管理与 ZOS-API 的连接

ZOS-API 可以被视为提供对 OpticStudio 功能的访问的库。加载此库本身并不会建立与 OpticStudio 的连接。ZOS ZOS负责加载允许与 OpticStudio 通信的 ZOS-API 程序集。由于您只能加载一次 ZOS-API，因此ZOS类是一个只能实例化一次的单例类。创建第二个ZOS实例将引发警告，并返回现有实例：

>>> import zospy as zp
>>> zos = zp.ZOS()
>>> zos2 = zp.ZOS()
UserWarning: Only a single instance of ZOS can exist at any time. Returning existing instance.
>>> zos is zos2
True

此行为与 ZOS-API 本身的行为类似，即在创建新连接时返回现有的ZOSAPI_Connection实例。不过，ZOS-API 会默默执行此操作，而 ZOSPy 会发出警告。

OpticStudioSystem 管理光学系统

使用 {py:meth} OpticStudioSystem zos.connect <zospy.zpcore.ZOS.connect>连接到 OpticStudio 返回一个OpticStudioSystem对象。OpticStudioSystem 类负责管理 OpticStudio 中的光学系统。虽然您一次只能连接到一个 OpticStudio 实例，但您可以在同一个实例中创建多个光学系统。因此，可以有多个OpticStudioSystem对象，每个对象管理不同的光学系统：

import zospy as zp

zos = zp.ZOS()
oss_1 = zos.connect()  # Returns the primary system
oss_2 = zos.create_new_system()  # Creates a new system and returns it

重新连接到 OpticStudio

如上所述，您只需实例化一次 {py:class} ZOS <zospy.zpcore.ZOS>类。要重新连接到 OpticStudio，您只需再次调用 {py:meth} zos.connect <zospy.zpcore.ZOS.connect> ：

import zospy as zp

zos = zp.ZOS()

# Connect to OpticStudio
oss = zos.connect()

# Do work ...

# Disconnect
zos.disconnect()

# Reconnect
oss = zos.connect()

请注意，只有在正确关闭连接的情况下才能重新连接到 OpticStudio。当已经存在活动连接时，{py:meth} zos.connect <zospy.zpcore.ZOS.connect>将引发异常。如果您想访问现有 OpticStudio 实例中的光学系统，可以使用 {py:meth} zos.get_primary_system <zospy.zpcore.ZOS.get_primary_system>和 {py:meth} zos.get_system <zospy.zpcore.ZOS.get_system> 。

目录