# 连接到 OpticStudio

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

1. **独立模式**：脚本完成后，将启动一个新的、不可见的 OpticStudio 实例并关闭。这是 ZOSPy 使用的默认模式。这也是性能最高的选项，因为更新 GUI 似乎会显著减慢模拟速度。
2. **扩展模式**：脚本连接到已运行的 OpticStudio 实例。为了能够在扩展模式下连接，必须在 OpticStudio 中激活“交互式扩展”模式。这对于调试或当您想要在 GUI 中查看模拟进度时很有用。

## 以独立模式连接

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

```python
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 的“编程”>“交互式扩展”下启用“交互式扩展”模式。

![互动扩展](../images/opticstudio_extension.png)

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

```python
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 可执行文件的路径来连接到特定版本：

```python
import zospy as zp

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

:::{note} 您需要指定 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`实例将引发警告，并返回现有实例：

```pycon
>>> 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`对象，每个对象管理不同的光学系统：

```python
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>` ：

```python
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>` 。