如何使用ZOS-API创建自定义操作数

Zemax OpticStudio Automation API

本文将使用ZOS-API创建自定义操作数 (User Operand) 来计算各表面之间距离的绝对值之和，该操作数与TTHI操作数的功能相同。可以使用UDOC操作数将该自定义操作数添加到评价函数 (Merit Function) 中，以控制参数并执行优化。

作者 Haosheng Hu

文章附件

引言

OpticStudio开发了一个应用程序接口(ZOS-API)，可以使用最新的软件技术连接和定制应用程序。虽然ZOS-API依赖于COM接口，但是它来源于.NET 库，并且通过使用C++或C# (.NET) 来实现API的编程，具体使用取决于用户对两种语言的熟练程度。

应用程序与OpticStudio之间的连接有四种程序模式。这些模式通常可以分为两个类别：

1) 完全控制（独立模式和自定义扩展模式），这种情况下，用户通常完全控制镜头设计和用户界面；

2) 有限访问（自定义操作数模式和自定义分析模式），这种情况下，用户使用现有镜头文件的副本进行处理和分析。

本文的主要目标是讨论自定义操作数模式。此模式几乎与自定义分析 (User Analysis) 模式相同，只是它常创建用户自定义操作数来进行自定义数据计算。通过在评价函数编辑器 (Merit Function Editor) 中使用UDOC操作数添加自定义操作数。与自定义分析模式一样，该模式不允许对当前镜头系统或用户界面进行更改（即：在这种模式下只允许对系统的副本进行更改）。自定义操作数可以使用C++(COM)或C# (.NET)编写——具体使用取决于用户对这两种语言的熟悉程度。

打开新的编程模板

单击C# >自定义操作数 (User Operand)，使用C#创建自定义操作数。

使用Windows资源管理器打开解决方案文件夹{Zemax}\ZOS-API Projects\CSharpUserOperandApplication1 。Visual Studio也会打开新的解决方案。该解决方案包含可以用作任何自定义操作数的基础模板代码。

读取镜头数据编辑器

在双高斯示例文件中使用此自定义操作数来计算定义范围内所有表面的总厚度。该示例文件位于: {Zemax}\Samples\Sequential\Objectives\Double Gauss 28 degree field.zmx 。
先使用自定义操作数读取位于物面与光阑面之间的表面的中心厚度值，然后将这些值相加来计算双高斯系统前组的总长度，也可以使用内置的操作数TTHI来完成。

代码顶部的两行列出了应用程序中经常使用的名称空间，然后可以在不指定完整路径的情况下使用名称空间中的接口。

using System; using ZOSAPI;

在模板中，有如下四个参数可用：

double Hx = TheApplication.OperandArgument1; double Hy = TheApplication.OperandArgument2; double Px = TheApplication.OperandArgument3; double Py = TheApplication.OperandArgument4;

参数的名称不能自定义。在计算中，将使用其中两个参数来定义表面范围。

在模板范本中找到"// Add your custom code here..." ，并开始编写代码。

通过定义surf1和surf2来定义表面范围，并链接到上述模板中的前两个参数。注意，在本例中未使用参数3和4。

int surf1 = (int)TheApplication.OperandArgument1; int surf2 = (int)TheApplication.OperandArgument2;

定义对象“surf”为接口ZOSAPI.Editors.LDE 的实例，用其读取镜头数据编辑器中的参数值。请记住，C# 是强类型语言，这意味着在声明变量时必须指定它的数据类型。

ZOSAPI.Editors.LDE.ILDERow surf; double thic = 0;

求厚度绝对值之和

使用“if”循环求取定义的表面范围内的所有表面中心厚度之和。如果表面范围输入是有效的，那么自定义操作数将返回厚度的总和。否则将返回无穷大的数，这意味着输入是无效的。

if (surf1 <= surf2) { for (int i = surf1; i <= surf2; i++) { surf = TheSystem.LDE.GetSurfaceAt(i); thic = thic + Math.Abs(surf.Thickness); } operandResults[0] = thic; } else { operandResults[0] = 1e9; }

现在，示例自定义操作数的编码已经完成。请注意，在本例中，使用operandResult[0] 将厚度值的和存入数据字段0。如果需要存放多个计算值，则可以将这些值存入不同的数据字段中，并使用UDOC操作数中的“Data”参数来控制确切的返回值。

保存、构建和移动可执行文件

将解决方案构建为发布版本。在调试时使用调试模式，但是在分配插件时，应该始终使用发布模式，因为调试库不是可以重新分配的。因此，切换到发布模式。

与作为控制台应用程序 (Console application) 编译的自定义分析不同，自定义操作数应该作为Windows应用程序编译。

否则，在使用用户自定义操作数进行优化时，控制台窗口将不断弹出，因为在优化期间会多次调用已编译的.exe文件。

在Visual Studio中，打开项目属性，并将自定义操作数应用程序的输出类型 (Output Type) 更改为Windows应用程序。注意，编译后的自定义操作数应用程序作为客户端程序，由评价函数操作数UDOC调用，由UDOC的prog#参数中的程序编号定义。因此，应用程序的程序集名称 (Assembly Name) 应该定义为UDOCXX，XX表示从00到99的数字。

然后，构建解决方案。

具有已定义程序集名称的Exe应用程序将存储在Visual Studio的项目属性中已选择的输出路径中：

找到已完成的应用程序的位置并将其复制到文件夹 {Zemax}\ZOS-API\Operands 中。

使用自定义操作数优化系统

为了检查新的自定义操作数，先打开OpticStudio，并打开镜头文件 {Zemax}\Samples\Sequential\Objectives\Double Gauss 28 degree field.zmx 。

打开评价函数编辑器，并在评价函数编辑器中插入操作数UDOC：

Prog# 用来指定客户端程序名称的编号，必须是整数值。
Data = 0 将执行客户端程序并返回当前值 (value) 列中的值。
超时(Timeout) 定义了OpticStudio等待UDOC计算所需数据并将控制权返回给OpticStudio的最长时间（以毫秒为单位），在本例中设置为50000。

然后，操作数UDOC就像任何内置的评价函数操作数一样工作。