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

宇熠科技

2022年2月14日 17:32

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

什么是 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 中看到結果。

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

疑難排解

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