Incorrect coordinates in `WavefrontMap` analysis

[crnh]

Problem

OpticStudio's wavefront map analysis exhibits some counterintuitive behavior that is not handled correctly by ZOSPy.
For an N x N sampling, it traces an odd number of rays ((N - 1) x (N - 1)) through the pupil to make sure the pupil center is sampled. An empty row and column are then added at the bottom and left of the wavefront map, to adhere to the requested sampling.
The ZOS-API returns a N x N datagrid with MinX = -1 and Dx = 2 / (N - 1).
ZOSPy assumes the left column is located at X = MinX + 0.5 and the right column at X = MinX + 63 * Dx (similar for the bottom column).
It then discards the empty left and bottom column and row of the ZOS-API output and the right and top coordinates of the dataframe.
For a sampling of 64x64, this results in columns and indices with 63 elements ranging from -0.98413 to +0.98413. The center column and index are located at (0, 0).

I made a user-defined surface that logs all locations at which rays are traced to a file. This surface was used as the stop surface in a system consisting of a stop surface immediately followed by a convex thick lens (radii 10 and -10 mm, thickness 10 mm, $n = 1.5$) with 10 mm between the lens back and image surface. In this system, the stop surface and entrance pupil coincide. I used an entrance pupil diameter of 2 mm, so normalized pupil coordinates are equal to physical coordinates on the stop surface. The values logged by this surface show that OpticStudio samples the pupil at 63 locations from ${x, y} = -1$ to ${x, y} = 1$.

Based on these results, I would say OpticStudio samples the pupil at N - 1 equispaced points on the interval [-1, 1]. The points are spaced 2 / (N - 2) apart (so not the 2 / (N - 1) reported by the ZOS-API).

The output currently returned by ZOSPy is misleading. I see two ways to fix this:

• Return the OpticStudio output as is without discarding the empty row and column, and raise a warning;
• Change the columns and indices to linspace(-1, 1, N - 1). Or actually linspace(-1 - (2 / N - 2), 1, N - 1) because the of the empty row and column.

In any case, I propose to not discard the empty row and column and return a N x N grid. Getting a different output shape than requested is confusing.

What version of ZOSPy are you running?

2.1.2

What version of OpticStudio are you running?

25R1

Which operating system do you use?

Windows

In which environment do you use ZOSPy?

• Plain Pythons scripts (not in Spyder)
• Jupyter notebooks
• Spyder

In which connection modes does the problem occur?

• Extension mode
• Standalone mode

Example code

Output

Additional information

File written by the user-defined pupil surface:

uds_raytrace_coordinates.txt