用 MATLAB 連結 Zemax OpticStudio 之二：常見語法問題

993499139

摘要：此系列文章共有三篇。
第一篇中，我們會示範如何利用MATLAB連結ZOS-API，並說明相關操作重點。
第二篇中，我們會重點提示撰寫時，幾個常見語法問題。
第三篇中，我們提供幾個有用的範例碼，說明幾個常見應用如何撰寫。


簡介
關於ZOS-API本身，請參考知識庫內另一篇「ZOS-API.NET簡介」。
MATLAB在透過ZOS-API連結OpticStudio時，主要有兩種模式：Standalone (獨立運作) 以及Interactive Extension (互動擴展)。
使用Standalone模式運作時，MATLAB會以背景模式連結到OpticStudio，然後所有動作都在Windows背後進行，過程中不會看到OpticStudio主視窗開啟。
反之，使用Interactive Extension模式運作時，必須先開啟OpticStudio，然後使用者需要先在OpticStudio開放連結，讓MATLAB能夠順利接入並控制，控制過程中OpticStudio不能手動操作，直到使用者手動在OpticStudio取消互動模式，取回控制權。
此文章為第二篇，說明一些語法要點。
關於連線的方法，請看第一篇。

變數宣告
在MATLAB中，不需要宣告變數，因此語法很簡潔，可以像下面這樣寫。
lde1 = TheSystem.LDE;

列舉型態
在OpticStudio中設定資料時，有些是純數值，像是LDE中的半徑、厚度等。有一些則是有限選項，例如視場型態 (Field Type) 或是系統孔徑 (System Aperture)，這選項在UI中大部分都是以下拉式選單方式存在。這種有限選項的參數設定，一般我們採用列舉來設定，比起用0、1、2、3… 來代表很一個選項，然後查表撰寫程式碼。以下是一個設定系統孔徑 (System Aperture) 的範例：
TheSystem.SystemData.Aperture.ApertureType = ZOSAPI.SystemData.ZemaxApertureType.EntrancePupilDiameter;
上面範例中的ZemaxApertureType即可以在Interface Document中找到定義，這種列舉的表示更直觀，撰寫時不易出錯，也讓程式碼更有可讀性。


屬性
在MATLAB中，屬性的使用跟C#差不多，讀取跟寫入時的語法都很直接。
% Retrieve a property value:
ap = TheSystem.SystemData.Aperture.ApertureValue;
% Set a property value:
TheSystem.SystemData.Aperture.ApertureValue = ap;
但須要注意，如果你在文件中看到該屬性的說明中，只有{get;}或是{set;}的話，這代表這個屬性只能用來讀取，或是只能用來設定。
例如下圖中，可以看到I_Analyses.NubmerOfAnalyses這個屬性只能讀取，他代表目前軟體中開啟了幾個分析視窗，這個數值只能取得，而不可能設定，是不是很合理？


回傳多個數值
有一些方法會回傳超過一個數值，此時MATALB的語法範例如下：
brt = TheSystem.Tools.OpenBatchRayTrace();
polData = brt.CreateDirectPol(5, RaysType.Paraxial, 1.0, 0.0, 0.0, 0.0, 0, 6);
% Values are returned in the same order as the out parameters in the interface, with the return value first:
[success, rayNumber, errorCode, vignetteCode, exr, exi, eyr, eyi, ezr, ezi, intensity] = polData.ReadNextResult();
brt.Close();
這個範例中，系統追跡一批光線，然後用ReadNextResult()方法讀取一條光線一條光線的追跡結果，每條光線都有各自的光線編號 (rayNumber)、錯誤碼 (errorCode)、漸暈 (vignetteCode)、XYZ電場複數振福 (exr, exi, eyr, eyi, ezr, ezi)、強度 (intensity)。
這類方法在文件中都顯示為如下：

畫面中的out是C#的語法，代表你可以把變數名稱放在該位置，然後此方法會自動填入資料，類似C++的指標。
請注意這個方法定義中，最前面還有一個bool布林值，用來代表執行此方法是否成功。這表示這個方法本身也會回傳資料，而在前述MATLAB語法回傳資料中，最前面的success就是用來承接這個布林值的，所以你一共會看到MATLAB用14個變數來承接，比裡面out的數量多一個。

使用父介面 (derived/base interface) 的方法或屬性
關於什麼是父介面，這邊跟物件導向語言有關，詳情請看任何一個物件導向語言，我建議C#，因為ZOS-API本身是用.NET撰寫，而C#本身就是一個針對.NET開發的語言，因此可以最沒有障礙的理解這裡的介面 (interface) 概念。
長話短說，使用ZOS-API時，有時候你會看到一些方法或屬性的說明旁邊有一個Inherited from的字樣，如下圖：

這些方法在MATLAB中是可以直接存取的，因此您可以放心的直接忽略這些Inherited的字眼。
以下是一個優化的範例。
localOpt = TheSystem.Tools.OpenLocalOptimization();
% Access a property of the current ILocalOptimization interface:
localOpt.Algorithm = OptimizationAlgorithm.DampedLeastSquares;
% Access a property of base interface ISystemTool (all base interfaces are directly accessible):
canCancel = localOpt.CanCancel;
localOpt.Close();
% No need to type cast in MATLAB - all derived and base properties are available:
obj1 = TheSystem.NCE.GetObjectAt(1);
bbData = obj1.SourcesData.SourceColorSettings;
bbData.TemperatureK = 3500;
MATLAB的使用者在這裡不需要額外的注意，但是如果您之後可能會在Python或C++上面改寫的時候，注意你會需要額外的語法，才能使用這個方法。

擷取矩陣資料
有些方法預設會回傳矩陣資料，但是回傳的格式跟MATLAB會不太一樣，以下用非序列中的Detector Viewer舉例，提供兩種方法快速取得矩陣資料。
% Method 1 - pre-create the array to retrieve:
detSize = TheSystem.NCE.GetDetectorSize(2);
dd1 = NET.createArray('System.Double', detSize);
TheSystem.NCE.GetAllDetectorData(2, 0, detSize, dd1);
% Method 2 - retrieve the full array directly:
dd2 = TheSystem.NCE.GetAllDetectorDataSafe(2, 0);
% easiest to access data by converting to native MATLAB matrix:
dd2 = double(dd2);

命名空間
上面的使用列舉型態說明中，我們使用完整個路徑來呼叫列舉資料，但是這會讓程式碼變得很長，不好閱讀，如下面的方法1。
但是我們可以透過把命名空間直接讀入MATLAB的手法解決這個問題，如下面的方法2。
% Method 1 - use full .NET namespace:
TheSystem.SystemData.Aperture.ApertureType = ZOSAPI.SystemData.ZemaxApertureType.EntrancePupilDiameter;
% Method 2 - import the namespace (anywhere in the code):
import ZOSAPI.SystemData.*;
TheSystem.SystemData.Aperture.ApertureType = ZemaxApertureType.EntrancePupilDiameter;