当前位置：首页 > news >正文

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

news 来源：原创 2025/6/26 12:38:21

附件下载

联系工作人员获取附件

这篇文章会说明如何在 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)。

Basic example 1

MATLAB_BatchRayTrace_Normalized.m – (SEQ Norm).
这个范例使用了 IRayTraceNormUnpolData 界面，而该界面还包含了RayTrace.dll (NormUnpol.cs) 中的 ReadNormUnpolData 函数。范例中，系统以超过10,000条光线追迹一个方形图案投射至像面的结果。设定上只使用了单一视场，且整个过程耗时不到一秒。

Basic Example 2

MATLAB_ZRDLoaderFull.m or PythonNET_ZRDLoaderFull.py – (NSC ZRD)
这个范例使用了 IZRDReader 界面，且同时使用了RayTrace.dll (ZRDLoaderFull.cs)中的 ReadZRDData 函数。范例中，系统解析了 ZRD 档案并决定了特定探测器上接收到的总能量。

Basic Example 3

进阶范例

MATLAB_BatchRayTrace_Surface_AOI.m – (SEQ Direct).
这个范例使用了 IRayTraceDirectUnpolData 界面，且同时使用了RayTrace.dll (DirectUnpol.cs)的ReadDirectUnpolData 函数。范例中，系统追迹了光线网格投射至一个特定表面的结果。过程中使用了 LMN 方向的 cosine 向量和 Nxyz 法向量计算光线在表面上每个 XY 点的入射角。

Advanced Example 1

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倍。

Advanced Example 2

MATLAB_ZRD_Pixelated_Detector_xybin.m – (NSC ZRD).
这个范例使用了IZRDReader界面，同时也使用了RayTrace.dll (ZRDLoaderFull.cs)的 ReadZRDData 函数。范例中的系统有矩形光源、矩形探测器，以及一个由 “LETTERF.BMP”产生的幻燈片(Slide) 物件，最后在探测器上显现出图型 “F”。接着，我们使用 ZRD 档案中的“xybin”将每个像素的光通量加总，重新在 ZRD 档案中产生一个新的探测器结果。这样的做法可使我们免于使用探测器查看器(Detector Viewer)的分析功能，直接在 MATLAB 中看到结果。

Advanced Example 3

疑难排解

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