摘要：此系列文章共有三篇。

第一篇中，我們會示範如何利用MATLAB連結ZOS-API，並說明相關操作重點。

第二篇中，我們會重點提示撰寫時，幾個常見語法問題。

第三篇中，我們提供幾個有用的範例檔，說明幾個常見應用如何撰寫。

作者：Michael Cheng
發布時間：March 13, 2017
簡介
關於ZOS-API本身，請參考知識庫內另一篇「簡介」。

MATLAB在透過ZOS-API連結OpticStudio時，主要有兩種模式：Standalone (獨立運作) 以及Interactive Extension (互動擴展)。

使用Standalone模式運作時，MATLAB會以背景模式連結到OpticStudio，然後所有動作都在Windows背後進行，過程中不會看到OpticStudio主視窗開啟。

反之，使用Interactive Extension模式運作時，必須先開啟OpticStudio，然後使用者需要先在OpticStudio開放連結，讓MATLAB能夠順利接入並控制，控制過程中OpticStudio不能手動操作，直到使用者手動在OpticStudio取消互動模式，取回控制權。

以下將分別說明如何用兩種不同模式連線。

使用Standalone模式連線
首先是到OpticStudio中點選Programming > MATLAB > Standalone Application，以產生樣板程式碼。

Click To Enlarge
點擊後，可以看到系統會自動建立一個範例的.m檔，並且打開存放的資料夾，如果電腦中有安裝MATLAB，則會自動被開啟，並顯示範例的.m檔。

Click To Enlarge
這個.m檔可以直接被執行，他的設計是讓使用者直接把需要執行的動作的語言，加到以下截圖中的“% Add your custom code here...” 這行下面的部分中。

而不需要去管與OpticStudio連結的語法。

讓使用者可以專心執行工作。

我們可以看到在“%Add your…” 這行前一句是
TheSystem = TheApplication.PrimarySystem;
這行需要這樣解讀：我們呼叫TheApplication這個物件的一個叫做PrimarySystem的屬性，然後把結果交給一個叫做TheSystem的變數中。

以下是幾個基本說明，請注意這部分與ZOS-API並不直接相關，主要是關於MATLAB，或是大部分程式語言所共通的語法：
1. TheSystem僅為物件變數，可以是任何名稱，例如你也可以寫ABC = TheApplication.PrimarySystem;。

這只是
一個存放物件資料的變數名稱。

此為重要觀念之一。

2. 這些TheSystem或TheApplication都對應到一個“介面(i nterface)”。

介面就像方向盤或遙控器，你可以利用他的方法(method) 或是屬性(properties) 來下指令，執行各種動作。

3. 這些介面通常實際對應到OpticStudio中的某個工具或編輯器，例如ILensDataEditor就是鏡頭數據編輯器。

有些介面代表比較模糊的概念，例如IOpticalSystem代表整個你正在操作的系統。

這裡的IOpticalSystem指的是介面的名稱(type name)，你不能直接使用IOpticalSystem這樣的介面名稱，我們必須建立一個變數來代表他才能使用，前面提到的TheSystem就是一個代表IOpticalSystem介面的變數。

4. 介面可以呼叫介面，他們的關係通常在OpticStudio中也看的到，例如IOpticalSystem可以呼叫ILensDataEditor。

通常我們會寫為
TheLDE = TheSystem.LDE;
注意TheSystem與TheLDE都是變數名稱，可以隨意更改。

LDE則是IOpticalSystem的一個屬性，名字是固定，無法隨意更改。

另外前面提到的這段語法也是介面呼叫介面。

TheSystem = TheApplication.PrimarySystem;
就是我們呼叫TheApplication這個物件中的PrimarySystem，而此物件會回傳IOpticalSystem介面，最後我們用一個等號“指定” 給TheSystem這個變數來代表這個介面的實體。

5. 每個介面有哪些屬性以及方法，這些屬性以及方法分別有什麼功能，會回傳什麼物件，都可以在我們的Interface Document中找到詳細說明，開啟位置如下圖：
下圖是一個很好的例子，可以看到在IOpticalSystem的Properties (屬性) 列表中，就有一個LDE。

只要存在，就可以呼叫，因此我們當然也可以撰寫如下：
TheMCE = TheSystem.MCE;
TheAnalyses = TheSystem.Analyses;
Click To Enlarge
至於上面令好的TheAnalyses變數可以做什麼，則可以點擊上圖中的Analyses連結，就可以看到如下的畫面：
Click To Enlarge
可以看到原來IOpticalSystem的Analyses屬性會回傳I_Analyses介面。

讓我們再點一下I_Analyses的連結，然後可以看到如下：
Click To Enlarge
因此在這裡我們可以知道I_Analyses有哪些屬性、方法可以使用。

例如我可以用TheAnalyses.NumberOfAnalyses得知目前系統中開啟了幾個分析視窗。

我也可以用FFTMTF = TheAnalyses.FftMtf()來開啟一個FFT MTF分析視窗的控制介面，並指定給FFTMTF這個變數。

或用TheAnalyses.CloseAnalysis(3)來關閉編號3的分析視窗。

依此類推。

請注意技術支援服務能協助你瞭解這些物件如何被設計，預期要如何操作，但是並不能協助你從最基本的程式語言操作開始。

使用Interactive Extension模式運作
此部分將僅說明跟Standalone模式不同的部分，關於語法的操作上，前面關於Standalone的說明都適用，因此建議讀者仍然閱讀前面的說明。

跟Standalone的模板代碼不同，Interactive Extension的模板程式碼幾乎只需要建立一個，之後就可以一值沿用，建立方法跟Standalone一樣，都是到Programming > MATLAB > Interactive Extension開啟。

Click To Enlarge
下圖中可以看到因為我已經是第三次按這個按鈕產生，因此產生的.m檔後面有後綴一個編號2，名字叫做MATLABZOSConnection2。

Click To Enlarge
在執行這段程式碼之前，我們需要先到OpticStudio中開放接口，如下圖：
Click To Enlarge
然後我們就可以執行這個.m檔，你會看到如下圖，MATLAB會自動用ans這個變數名稱來承接產生出來的物件，而這個物件就是ZOSAPI_Application介面。

也就是我們習慣用命名為TheApplication的變數來承接的介面。

Click To Enlarge
並且可以看到OpticStudio中介面顯示為Connected，表示已經正確連結：
由於ans這個變數名稱是MATLAB預設的結果儲存區，因此任何沒有變數承接的數值或物件，都會預設儲存到ans 之中。

這會造成問題，如果ans被儲存的其他內容，則我們就再也沒辦法呼叫ZOSPI_Application了！你可以試著在執行這個.m檔之後，隨意在計算須中輸入任一數字看看，例如123，我們會發現現在ans是一個整數變數，內容存放的是123：
Click To Enlarge
解決這個問題的方法很簡單：首先我們要把該.m的資料夾加入到MATLAB的“Path” 中，然後直接在呼叫這個.m 檔的時候，指定把產生的結果儲存到變數之中。

聽起來很複雜，其實很容易，首先加入Path的方法如下。

1. 來到MATLAB主畫面，選擇Set Path：
Click To Enlarge
2. 然後選擇你的Interactive Extension的.m檔資料夾加入，並按OK，如下：
Click To Enlarge
然後你就可以直接輸入如下，把ZOSAPI_Application介面設定給TheApplication這個變數存放。

TheApplication = MATLABZOSConnection2();
Click To Enlarge
接著你就可以呼叫IOpticalSystem、ILensDataEditor、I_Analyses等等，如下：
Click To Enlarge
你也可以把這些計算等語法寫入另一個.m檔之中，進行一些更複雜的工作，如下： Click To Enlarge。