本文對 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

??點擊閱讀原文咨詢產品或技術支持。