ZEMAX | 在MATLAB或Python中使用ZOS-API进行光线追迹的批次处理
主题：Zemax 成像设计线上培训
时间：2022年4月14日-15日
这篇文章会说明如何在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
