這篇文章會說明如何在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這個動態(tài)連接函式庫涵蓋了以下的界面，并且繼承了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中每一個區(qū)段（segment）的值。

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

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

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函數。示例中，系統(tǒng)追跡了特定透鏡表面的光跡圖（footprint diagram），同時繪出系統(tǒng)的凈口徑（Clear Semi-Diameter）和機械半直徑（Mechanical Semi-Diameter）。

MATLAB_BatchRayTrace_Normalized.m–（SEQ Norm）.這個示例使用了IRayTraceNormUnpolData界面，而該界面還包含了RayTrace.dll （NormUnpol.cs）中的ReadNormUnpolData函數。示例中，系統(tǒng)以超過10,000條光線追跡一個方形圖案投射至像面的結果。設定上只使用了單一視場，且整個過程耗時不到一秒。

MATLAB_ZRDLoaderFull.m or PythonNET_ZRDLoaderFull.py–（NSC ZRD）這個示例使用了IZRDReader界面，且同時使用了RayTrace.dll （ZRDLoaderFull.cs）中的ReadZRDData函數。示例中，系統(tǒng)解析了ZRD檔案并決定了特定探測器上接收到的總能量。

進階范例

MATLAB_BatchRayTrace_Surface_AOI.m–（SEQ Direct）.這個示例使用了IRayTraceDirectUnpolData界面，且同時使用了RayTrace.dll （DirectUnpol.cs）的ReadDirectUnpolData函數。示例中，系統(tǒng)追跡了光線網格投射至一個特定表面的結果。過程中使用了LMN方向的cosine向量和Nxyz法向量計算光線在表面上每個XY點的入射角。

MATLAB_BatchRayTrace_Ex22_Performance_Comparison.m–（SEQ Norm）.這個示例使用了IRayTraceNormUnpolData界面，同時還使用了RayTrace.dll （NormUnpol.cs）的ReadNormUnpolData函數。示例中，系統(tǒng)使用低量化誤差光線圖型（dithered ray pattern）繪制了整個視場的點列圖（spot diagram）。模擬過程中，系統(tǒng)可以在一秒內追跡10,000條光線。相同情況下，若使用原生MATLAB的for循環(huán)，繪制961條光線將耗時超過4秒。根據電腦的性能差異，使用DLL最高可將運算過程加速為原先的40倍。

MATLAB_ZRD_Pixelated_Detector_xybin.m–（NSC ZRD）.這個示例使用了IZRDReader界面，同時也使用了RayTrace.dll （ZRDLoaderFull.cs）的ReadZRDData函數。示例中的系統(tǒng)有矩形光源、矩形探測器，以及一個由“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