在 MATLAB 或 Python 中使用 ZOS-API 进行光线追跡的批次处理

这篇文章会说明如何在 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 中看到结果。

疑难排解

若是使用了范例提供的 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