在MATLAB或Python中使用ZOS-API進行光線追跡的批次處理

2021年03月31日 07:55

這篇文章會說明如何在MATLAB或Python中以Zemax OpticStudio應用程式介面(ZOS-API)處理光線數據庫(Ray Database, ZRD)檔案，過程中我們將使用ZRDLoader.dll。本文提供了在Matlab中批次處理序列光線追跡(一般、歸一化、偏振或非偏振)，以及在Matlab和Python中使用方法ReadNextSegmentFull()批次處理非序列ZRD檔案的範例。

作者 Michael Humphreys

附件下载

範例檔案

什麼是RayTrace.dll?

RayTrace.dll結合了ZRDLoader.dll和ReadNextSegmentFull，並在序列模式中與4個IBatchRayTrace介面共同運作。此外，RayTrace.dll這個動態連結函式庫涵蓋了以下的介面，並且繼承了ZOSAPI.Tools.RayTrace的命名空間:

IRayTraceDirectPolData (sequential):
在這個介面中，我們可以直接在XYZ座標中完成批次的偏振光線追跡，而這也和DDE光線追跡指令(模式3)十分相似。此外，該介面屬於IBatchRayTrace介面的一種。
IRayTraceDirectUnpolData (sequential):
在這個介面中，我們可以在XYZ座標中完成批次的非偏振光線追跡，而這與DDE光線追跡指令(模式1)相似。此外，該介面也同樣屬於IBatchRayTrace介面的一種。

IRayTraceNormPolData (sequential):
在這個介面中，我們可以使用歸一化光瞳座標(normalized pupil coordinate)進行批次偏振光線追跡，這與DDE光線追跡指令(模式2)相似。此外，該介面也同樣屬於IBatchRayTrace介面的一種。

IRayTraceNormUnpolData (sequential):
在這個介面中，我們可以使用歸一化光瞳座標進行批次非偏振光線追跡，這與DDE光線追跡指令(模式0)相似。
IZRDReader (non-sequential):
我們使用這個介面在Matlab中設定RayDatabaseReader並使其運作，同時讀取C#dll中每一個區段(segment)的值。

這個DLL的設計是為了使光線或區段的原始值(raw value)可以作為宣告物件的屬性，而被傳遞到MATLAB或Python，因此DLL運作的過程中不會涉及任何的計算、合併和分析。這個DLL的主要目的是為了減少MATLAB或Python中十分耗時的for迴圈，將原先效率極低的程式轉為原生且編譯完成的C#程式碼。接著，當原始值經過所有迴圈後，C#程式碼會將數值回傳到MATLAB或Python進行最後的處理。

在序列模式的介面中有兩種情況會需要for迴圈的協助: AddRays()和ReadNextResults()，分別用來增加光線和讀取數據。為了提高效率，我們會以DLL達成這兩項任務。文章附檔的其中兩個範例示範了如何在序列模式中高效率的產生方形網格或低量化誤差的光線(dithered rays)。根據預期達成的光線模式(若與預設模式不同的話)，我們可以在MATLAB中使用原生陣列索引(native array indexing)的方式增加DLL中的光線，這與原本的方法是十分相似的。無論是在ReadNextResult()或ReadNextResultFull()，最終回傳到MATLAB或Python中的結果均會與該介面最複雜輸出(verbose output)有著相同的物件屬性，包含了正確的相位和相對應的案例。為了提高效率，我們會試著以MATLAB的陣列索引(array indexing)取代for或while迴圈的使用。

DLL使用範例

我們使用三個基礎和三個進階範例示範如何在一般序列模式(sequential direct)、歸一化序列模式(sequential normalized)和非序列ZRD光線追跡的情況下使用RayTrace.dll。這些範例檔案都可以直接下載並使用，不需要對程式碼進行任何更改。要注意的是，RayTrace.dll必須被存放在和其他MATLAB或Python腳本(script)相同的資料夾中，才能確保使用時能被順利的呼叫。產生每個DLL所使用的C#原始碼以及Visual Studio的解都可以在下方的文章中找到。

基本範例

MATLAB_BatchRayTrace_Direct.m – (SEQ Direct).
這個範例使用了IRayTraceDirectUnpolData介面。此外，它還同時使用了RayTrace.dll (DirectUnpol.cs)中的ReadDirectUnpolData函數。範例中，系統追跡了特定透鏡表面的光跡圖(footprint diagram)，同時繪出系統的淨口徑(Clear Semi-Diameter)和機械半直徑(Mechanical Semi-Diameter)。
MATLAB_BatchRayTrace_Normalized.m – (SEQ Norm).
這個範例使用了IRayTraceNormUnpolData介面，而該介面還包含了RayTrace.dll (NormUnpol.cs)中的ReadNormUnpolData函數。範例中，系統以超過10,000條光線追跡一個方形圖案投射至像面的結果。設定上只使用了單一視場，且整個過程耗時不到一秒。
MATLAB_ZRDLoaderFull.m or PythonNET_ZRDLoaderFull.py – (NSC ZRD)
這個範例使用了IZRDReader介面，且同時使用了RayTrace.dll (ZRDLoaderFull.cs)中的ReadZRDData函數。範例中，系統解析了ZRD檔案並決定了特定探測器上接收到的總能量。

進階範例

MATLAB_BatchRayTrace_Surface_AOI.m – (SEQ Direct).
這個範例使用了IRayTraceDirectUnpolData介面，且同時使用了RayTrace.dll (DirectUnpol.cs)的ReadDirectUnpolData函數。範例中，系統追跡了光線網格投射至一個特定表面的結果。過程中使用了LMN方向的cosine向量和Nxyz法向量計算光線在表面上每個XY點的入射角。
MATLAB_BatchRayTrace_Ex22_Performance_Comparison.m – (SEQ Norm).
這個範例使用了IRayTraceNormUnpolData介面，同時還使用了RayTrace.dll (NormUnpol.cs)的ReadNormUnpolData函數。範例中，系統使用低量化誤差光線圖型(dithered ray pattern)繪製了整個視場的點列圖(spot diagram)。模擬過程中，系統可以在一秒內追跡10,000條光線。相同情況下，若使用原生MATLAB的for迴圈，繪製961條光線將耗時超過4秒。根據電腦的性能差異，使用DLL最高可將運算過程加速為原先的40倍。
MATLAB_ZRD_Pixelated_Detector_xybin.m – (NSC ZRD).
這個範例使用了IZRDReader介面，同時也使用了RayTrace.dll (ZRDLoaderFull.cs)的ReadZRDData函數。範例中的系統有矩形光源、矩形探測器，以及一個由“LETTERF.BMP”產生的幻燈片(Slide) 物件，最後在探測器上顯現出圖型“F”。接著，我們使用ZRD檔案中的“xybin”將每個像素的光通量加總，重新在ZRD檔案中產生一個新的探測器結果。這樣的做法可使我們免於使用探測器查看器(Detector Viewer)的分析功能，直接在MATLAB中看到結果。

疑難排解

若是使用了範例提供的Visual Studio解，但卻在編譯的過程中出現錯誤的話，請先照著以下步驟操作以確保ZOSAPI 和ZOSAPI_Interfaces的來源(Reference)是正確的。我們可以打開Solution Explorer，並點選References。假如這時ZOSAPI 和ZOSAPI_Interfaces旁邊出現黃色的警示標語，你將會需要進行以下操作:

移除現有的references (滑鼠右鍵>移除(Remove))
右鍵選取Reference並選擇Add References
點選Browse並找到OpticStudio的安裝資料夾
以快捷鍵Shift+Click選擇ZOSAPI和ZOSAPI_Interfaces，接著點選Add
點選OK加入新的解
選取所有的references，打開Properties接著將 Copy Local 由True 改為 False

KA-01651