ZEMAX | 了解 ZOS-API 的主要接口——MATLAB

本文对 ZOS-API 的主要接口 (Interfaces) 进行了介绍。它遵循编程(Programming)选项卡>关于 ZOS-API(About the ZOS-API) 下的帮助文件(Help File)中描述的内容。帮助文件中对每个接口都有对应的介绍，建议您阅读这些内容。本文将着重介绍其中重要的部分，您将有机会对照练习。本文是对应于 MATLAB 编写的。

简介

ZOS-API 是被作为 接口的层次结构建立的。通过这些 接口可以访问 OpticStudio 的不同功能。本文将介绍其中一些主要的部分。

IZOSAPI_Application TheApplication

定义

TheApplication 是一个变量，它是  IZOSAPI_Application 接口的实例。

正如 帮助文件中定义的那样， TheApplication（或者你选择其他任意方式调用这个变量）可以访问 ZOS (Zemax OpticStudio)已提供的所有地址。接下来，让我们来了解一下 TheApplication。

如何使用TheApplication

使用Matlab连接到OpticStudio交互扩展，请点击“ 编程 ( Programming )> Matlab> 交互扩展 ( Interactive Extension ) ”以生成模板代码。在这段代码中，app = TheConconnection.ConnectAsExtension（实例）用于连接OpticStudio 中的已有实例。

要使用Matlab连接到 OpticStudio  独立应用程序 (Standalone  Application )，单击“ 编程 ( Programming )> Matlab> 独立应用程序”生成模板代码。在这段代码中，app = TheConnection.CreateNewApplication()用于在“headless”模式下启动OpticStudio 的新实例。请注意，虽然 OpticStudio 窗口是不可见的，但它仍然需要有效的许可证才能使用。

如下为一些实用的命令：

• 关闭应用程序：

   TheApplication.CloseApplication();

• 检查您的授权版本：

   TheApplication.LicenseStatus;

• 检查您的授权模式：

   TheApplication.Mode;

• 将  OpticStudio 的语言切换为英语：TheApplication.Preferences.General.Language=ZOSAPI.Preferences.LanguageType.English;

• 获取示例文件夹 (Sample Files folder)的完整路径：

  sampleDir = TheApplication.SamplesDir

IOpticalSystem PrimarySystem

定义

帮助文件中的定义为： PrimarySystem 属性提供了对当前加载的. zmx文件的访问权限，并提供了若干操作和数据访问权限。
TheSystem = TheApplication.PrimarySystem;

如何使用PrimarySystem

TheSystem 提供对编辑器的访问权限：.LDE 用于 镜头数据编辑器 (Lens Data Editor )，.MCE 用于 多重结构编辑器 (Multi Configuration Editor )，.MFE 用于 评价函数编辑器 (Merit Function Editor )，.TDE 用于 公差数据编辑器 (Tolerance Data Editor )，.NCE 用于 非序列编辑器 (Non-Seqential Editor )。还可以使用  .Analysis  对分析进行访问和使用 .Tools  对工具进行访问。

一些关于 TheSystem 进行的实用操作如下所示：

• 转换至非序列模式(Non-sequential Mode)：

   TheSystem.MakeNonSequential();

• 转换至序列模式(Sequential Mode)：

   TheSystem.MakeSequential();

• 下载.ZMX文件：

   testFile = System.String.Concat(sampleDir, '\Sequential\Objectives\Double Gauss 28 degree field.zmx');TheSystem.LoadFile(testFile, false);

• 保存已存在的系统(.ZMX)：

   TheSystem.Save();

• 将当前系统保存为一个新的文件：

   TheSystem.SaveAs(copyFile);

• 创建新的（默认的）镜头数据文件(LENS.ZMX)：

  TheSystem.New(false);

• 关闭当前已打开的系统且不保存： 

  TheSystem.Close(false);

ISystemData SystemData

定义

在 帮助文件中的定义为： TheSystemData  包含系统所有的基本数据，可以对系统选项( System Explorer) 进行设置。
TheSystemData = TheSystem.SystemData;

如何使用TheSystemData

TheSystemData  可以对孔径 (Aperture ) 、视场 (Fields) 、波长 (Wavelengths) 、环境 (Environment) 、光线瞄准 (RayAiming) 、非序列数据 (NonSequentialData) 、偏振 (Polarization) 等特性 进行访问。

如下为一些可改变 TheSystemData 中设置的实用操作：

• 更改下拉菜单中的设置：OpticStudio 下拉菜单中的设置只能获取预设值的列表。在 ZOS-API 中，这些列表以枚举的形式公开。例如，要将系统孔径类型更改为入瞳直径(Entrance Pupil Diameter)，请选择 EntrancePupilDiameter  作为枚举类型，它是 ZemaxApertureType 的一种。
  TheSystemData.Aperture.ApertureType=ZOSAPI.SystemData.ZemaxApertureType.EntrancePupilDiameter;

• 更改数值设置：
  TheSystemData.Aperture.ApertureValue=20;

• 更改字符设置：

   sysTitleNotes = TheSystem.SystemData.TitleNotes;

• 设置膜层文件并重新载入：

   sysFiles = TheSystem.SystemData.Files; sysFiles.CoatingFile = 'COATING.DAT';TheSystem.SystemData.Files.ReloadFiles();

• 添加标题：

   sysTitleNotes.Title = 'Add here the title';

• 勾选或不勾选复选框。True 代表着勾选这个选项，False代表不勾选：TheSystemData.Aperture.AFocalImageSpace = true;

如下为一些可改变视场和波长的实用选项：

• 访问视场： 

  sysField = TheSystem.SystemData.Fields;

• 访问波长：

  sysWave= TheSystem.SystemData.Wavelengths;

• 添加新的视场

  X=0,Y=5.0，视场权重为1.0：NewField_2 = sysField.AddField(0,5.0,1.0);

• 添加新的波长0.6328mm，权重为1.0：

  NewWave_2 = sysWave.AddWavelength(0.6328,1.0);

• 将视场1 的值改为X=1,Y=2.0，视场权重为0.5：

  field1 = sysField.GetField(1); field1.X = 1.0; field1.Y = 2.0; field1.Weight = 0.5;

• 将波长1改为0.55mm：TheSystemData.Wavelengths.GetWavelength(1).Wavelength = 0.55;

• 设置波长1 为主波长：TheSystemData.Wavelengths.GetWavelength(1).MakePrimary();

• 将视场类型 (Field Type) 改为物高 (Object Height)：sysField.SetFieldType(ZOSAPI.SystemData.FieldType.ObjectHeight);

• 将归一化 (Normalization) 改为径向(Radial)：

   sysField.Normalization= ZOSAPI.SystemData.FieldNormalizationType.Radial;

• 使用视场向导 (Field Wizard) 从0到10添加3个等效的Y视场：sysField.ApplyFieldWizard(ZOSAPI.SystemData.FieldPattern.EqualAreaY,3,10,0,0,1,true,false);
  最后三个参数 (1,true, false)表示：从第1行开始，分别检查覆盖 (Overwrite) 是否选中和使用拾取 (Use pickups) 是否取消选中。

• 使用正交算法 (Quadrature) 从0.486mm到0.656mm范围内定义6个波长：TheSystemData.Wavelengths.GaussianQuadrature(0.486,0.656,ZOSAPI.SystemData.QuadratureSteps.S6);

• 使用预置 (Preset) 选项定义波长：TheSystemData.Wavelengths.SelectWavelengthPreset(ZOSAPI.SystemData.WavelengthPreset.FdC_Visible);

• 读取视场的数目： 

  num_fields=TheSystem.SystemData.Fields.NumberOfFields;

分析

定义

帮助文件中的定义为：the Analyses  包含访问 OpticStudio 中分析功能的所有信息的权限。

TheAnalyses = ThePrimarySystem.Analyses;

如何使用 TheAnalyses

TheAnalyses 可以访问所有的分析选项。

如下为一些运行分析选项卡的实用命令：

• 执行一次分析： 

  TheSystem.Analyses.New_Analysis(ZOSAPI.Analysis.AnalysisIDM AnalysisType)
例如，执行一次光线光扇图分析：
  TheRayFan = TheSystem.Analyses.New_Analysis(ZOSAPI.Analysis.AnalysisIDM.RayFan);
一些分析选项可以用它们自身的功能打开：
TheRayFan = TheSystem.Analyses.New_RayFan();

• 检查分析选项是否已有正在应用的设置：

   TheRayFan.HasAnalysisSpecificSettings;

• 获取设置： 

  TheRayFan_Settings = TheRayFan.GetSettings();

• 更改已经应用的设置。例如，更改光线数目： 

  TheRayFan_Settings.NumberOfRays = 100;
  改变波长：

   TheRayFan_Settings.Wavelength.SetWavelengthNumber(0);

• 使用 ModifySettings 更改还未应用的设置：
  analysisSettings.SaveTo(cfgFile);   
analysisSettings.ModifySettings(cfgFile, 'SHA_ROTX', '90');   
analysisSettings.LoadFrom(cfgFile);   
System.IO.File.Delete(cfgFile);       

• 应用设置：  

  TheRayFan.ApplyAndWaitForCompletion();

• 获取结果：

  TheRayFan_Results = TheRayFan.GetResults();

• 读取结果：得到的结果取决于已执行的分析。
例如：示例代码23使用 DataSeries 读取光线光扇图 (Ray Fan) 的分析结果。
  for field = 1:max_num_field
     x = ray_results.DataSeries(field * 2 - 1).XData.Data.double;
     y = ray_results.DataSeries(field * 2 - 1).YData.Data.double;
end;

编辑器

定义

编辑器是一组用于输入镜头数据、物体数据、操作数数据的电子表格。这些编辑器包括 镜头数据编辑器 (LDE) 、非序列元件编辑器 (NCE) 、评价函数编辑器 (MFE) 、多重结构编辑器 (MCE) 、公差数据编辑器 (TDE) 。

TheLDE = TheSystem.LDE;

如何使用编辑器

各编辑器之间的功能类似。LDE 中是关于 表面 (Surface)的信息，NCE 中是关于 物体 (Objects)的信息，MFE、MCE 和 TDE 中是关于 操作数 ( Operands )的信息，MCE 中是关于 多重结构 ( Configurations )的信息。

以下是 TheLDE一些最常见的功能:

• 添加新表面：

   TheLDE.AddSurface();

• 在特定的表面序号前插入新表面： 

  TheLDE.InsertNewSurfaceAt(1);

• 删除一个或多个指定序号的表面：

  TheLDE.RemoveSurfacesAt(1,3);

• 将指定数量的表面从一个位置复制粘贴到另一个位置：TheLDE.CopySurfaces(1,3,3);
  第一个参数是要复制的第一个表面，第二个参数是要复制的表面数目，最后一个参数是要粘贴到的表面序号。

• 访问特定的表面： 

  TheLDE.GetSurfaceAt(1);

• 更改表面类型：surf1_type=surf1.GetSurfaceTypeSettings(ZOSAPI.Editors.LDE.SurfaceType.EvenAspheric); surf1.ChangeType(surf1_type);

• 获取或设置半径(Radius)、厚度(Thickness)、半口径(SemiDiameter)、延伸区(ChipZone), 圆锥系数(Conic)、热膨胀系数(TCE)、标注(Comment)、材料(Material)、膜层(Coating)的值: 

  surf1.Comment=  'Add comment here';

• 添加求解(Solve):
solve_MarginalRayHeight= surf1.ThicknessCell.CreateSolveType(ZOSAPI.Editors.SolveType.MarginalRayHeight);  
solve_MarginalRayHeight.PupilZone=0.5;
surf1.ThicknessCell.SetSolveData(solve_MarginalRayHeight);
surf1.RadiusCell.MakeSolveVariable();

• 改变参数的值：

  par2= surf1.GetSurfaceCell(ZOSAPI.Editors.LDE.SurfaceColumn.Par2); par2.DoubleValue= 0.0005;

• 将孔径属性改为圆形孔径(Circular Aperture)：
aperdata=surf1.ApertureData;
circular_aper=aperdata.CreateApertureTypeSettings(ZOSAPI.Editors.LDE.SurfaceApertureTypes.CircularAperture);
circular_aper.MaximumRadius=0.5;
aperdata.ChangeApertureTypeSettings(circular_aper);

• 访问编辑器工具栏的工具： 

   RunTool_ConvertLocalToGlobalCoordinates(int, int, int)

IOpticalSystemTools ThePrimarySystem.Tools

定义

在 帮助文件中的定义：每个光学系统提供对 系统工具 ( System Tools)的访问权限。在指定的光学系统中，用户一次只能运行一个工具。

TheSystem.Tools

如何使用Tools

所有工具之间的语句相似。若要运行 工具 (Tool)，请打开工具，定义设置，然后运行它。

testFile = System.String.Concat(sampleDir, '\Sequential\Objectives\Cooke 40 degree field.zar');
testFolder = System.String.Concat(sampleDir, '\test\');
loadZAR=TheSystem.Tools.OpenRestoreZAR();
loadZAR.SetFileName(testFile);
loadZAR.SetOutputFolder(testFolder);
loadZAR.SetFilesAllOverwrite();
loadZAR.RunAndWaitForCompletion();
loadZAR.Close();

如下为TheSystem.Tools.中常用的一些工具：

• 创建存档文件(Create Archive)：createZAR=TheSystem.Tools.OpenCreateZAR();

• 将当前透镜数据输出为 CAD 文件：

   ToolExportCAD = TheSystem.Tools.OpenExportCAD();

• 将文件转换为非序列文件：

   convertNSmode = TheSystem.Tools.OpenConvertToNSCGroup();

• 执行快速聚焦( Quick Focus)：

   quickFocus = TheSystem.Tools.OpenQuickFocus();

• 移除所有变量：

   TheSystem.Tools.RemoveAllVariables();

• 执行一次局部优化：

   LocalOpt = TheSystem.Tools.OpenLocalOptimization();

• 运行一次批量光线追迹(Batch ray trace)：

   raytrace = TheSystem.Tools.OpenBatchRayTrace(); 

• 打开公差分析 (Tolerancing)：

   tol = TheSystem.Tools.OpenTolerancing();

• 计算评价函数 (Merit Function)：MFcalculator=TheSystem.Tools.OpenMeritFunctionCalculator();

• 计算光斑半径 (Spot Radius)：

   SpotCalculator= TheSystem.Tools.OpenRMSSpotRadiusCalculator();

• 在表面3 处插入镜头库中的镜头：Lenscat=TheSystem.Tools.OpenLensCatalogs();

如下为 TheSystem.Tools 中非序列模式下可用的最常用的工具：

• 执行光线追迹(RayTrace)： 

  NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace();

• 从光线数据库(RayDataBase) 中读取数据：

   OpenRayDatabaseReader()。

下期我们将会为大家介绍《在 MATLAB 中使用 ZOS-API 批量处理光线追迹数据》

---

相关阅读 - 编程

ZEMAX | 使用 ZPL 宏进行优化：ZPLM 操作数

ZEMAX | 如何编写 ZPL 宏：计算环带垂轴色差

ZEMAX | ZOS-API、ZPL 和 DLL 之间的区别

ZEMAX  | 如何使用 ZOS-API 创建飞行时间自定义分析

ZEMAX | 如何使用 ZPL 创建用户自定义求解

欢迎扫码添加宇熠工作人员微信，

进入 zemax 微信交流群。

一起来学习光学设计吧！

扫码邀您入群

如果您对产品感兴趣，或需要技术支持，欢迎致电垂询！

电话：027-87878386

邮箱：market@ueotek.com

关注武汉宇熠视频号 查看更多精彩视频 

武汉宇熠科技是  ZEMAX 中国区官方指定代理商 ，提供 ZEMAX 光学设计软件的培训、销售、技术支持、二次开发、解决方案及 ZEMAX 软件相关全方位定制服务。有关 ZEMAX ，您可以点击文末“阅读原文”了解更多信息，或致电垂询武汉宇熠工作人员：

销售热线：027-87878386

咨询邮箱：sales@ueotek.com

👇点击阅读原文咨询产品或技术支持。