The ZRD Uncompressed Full Data Format (UFD)
The first record in the file is a single 32-bit integer indicating the version and format number of the ZRD file. The second record in the file is a single 32-bit integer indicating the maximum possible number of segments in the remaining records. The actual number of segments will always be less than or equal to this number.
The remainder of the file consists of a 32-bit integer indicating the number of segments that follows, then that many segments, then another 32-bit integer indicating the number of segments in the next record, and so on until the end of the file. A single ray segment is described by a "C" structure with the following format:
typedef struct
{
unsigned int status;
int level;
int hit_object;
int hit_face;
int unused;
int in_object;
int parent;
int storage;
int xybin, lmbin;
double index, starting_phase;
double x, y, z;
double l, m, n;
double nx, ny, nz;
double path_to, intensity;
double phase_of, phase_at;
double exr, exi, eyr, eyi, ezr, ezi;
double optical_path_w, optical_path_lu;
int order_x, order_y;
} RAYPATH;
See "Comments on Data Structure Memory Packing" for more details.
Each data item is described below.
status: bitwise flags indicating the status of the ray. The flags (in integer notation) are: terminated: 1, reflected: 2, refracted: 4, scattered: 8, diffracted: 16, ghost: 32, diffracted from previous object: 64, scattered from previous object: 128, ray segment had fatal error: 256, bulk scattered: 512.
level: The number of ray segments between the ray segment and the original source. This is the number of ray-object intercepts the ray has accumulated.
hit_object: The object number the ray intercepted. If zero, the ray did not hit anything. For the zero segment, this value will be the source segment object number.
hit_face: The face number the ray intercepted. Valid only if hit_object is not zero.
in_object: The object number the ray is propagating inside of. This generally determines the index of refraction the ray is traveling through. A value of zero means inside the "background media".
parent: The (prior) ray segment from which the ray originated. If zero, the ray came from the original source point. Note more than 1 child ray may have the same parent; but each ray has only one parent. The parent segment number will always be less than the child rays segment number.
storage: A temporary buffer used by OpticStudio for indexing. For segment 0 only, this integer is the ray wavelength number. See nx below for the actual wavelength value. Other segments may contain meaningless data.
xybin, lmbin: The pixel number on a detector object which the ray struck. The xybin is for spatial data, the lmbin is for angular (intensity) data.
index: the index of refraction of the media. Not an adequate description for gradient index media. starting_phase: the initial optical path length the ray starts with. This is usually the contribution from diffraction ratings when rays are split off.
x, y, z: the global coordinates of the ray intercept.
l, m, n: the global direction cosines of the ray. Not an adequate description for gradient index media.
nx, ny, nz: the global normal vector of the object at the intercept point. For segment 0 only, the nx value stores the wavelength of the ray being launched.
path_to:e physical (not optical) path length of the ray segment. Note this value is sometimes different to the "Path To" shown in the Ray Database Viewer. The Path To in Ray Database Viewer is always the physical path length of the ray segment. The path_to data in ZRD file is not the physical path length when the segment is generated from bulk scattering and does not hit any object at its end, where both "Hit" and "Face" of the segment are 0. If the physical path length of the segment is desired in this case, users can either check it in the Ray Database Viewer or directly calculate it from the (x,y,z) position data of the segment and its parent segment.
intensity: the intensity of the ray segment.
phase_of: the phase of the object. This is the optical phase path length equivalent in lens units added by gratings, holograms, and other phase modifying surfaces.
phase_at: the accumulated total phase of the ray (modulo 2*pi). This value includes accumulated phase due to propagation as well as phase introduced by objects that impart phase (i.e. gratings, etc.). The phase introduced by coatings is not included in this value and is generally considered a "phase aberration". This value is only computed at detector surfaces. Note the phase reported here is adjusted to account for offset from the center of the pixel where the ray lands. In some cases the plane wave, namely the ray, needs to propagate forward a bit to hit the pixel center, in others it needs to propagate backward a bit to hit the pixel center.
exr, exi, eyr, eyi, ezr, ezi: the electric field in the global x, y, and z coordinates, real and imaginary parts. These values will all be zero if the ray trace did not use polarization.
The ZRD UFD format is subject to change, however, OpticStudio will automatically convert older formats to the current format. Note the structure size is 232 bytes for each ray segment. If 100,000 rays are traced with an average of 50 segments each, the resulting file will be about 100,000 x 50 x 208 bytes = 1Gb in size. The file sizes can quickly become enormous, so great care must be taken to limit the number of segments before deciding to save the ray data to a file. Use of a filter string to limit the saved data to the rays of interest may substantially reduce the amount of data written to the file.
The ZRD file consists of alternating blocks of data. For example, if three rays are traced, with 5, 7, and 9 segments each, then the ZRD file will be formatted as follows:
4 bytes: version 4 bytes: maximum number of segments possible, will be 9 or larger in this example 4 bytes: 5 (the number of segments in ray 1) 208 bytes x 5 (the segment data for ray 1) 4 bytes: 7 (the number of segments in ray 2) 208 bytes x 7 (the segment data for ray 2) 4 bytes: 9 (the number of segments in ray 3) 208 bytes x 9 (the segment data for ray 3)
For information on what OpticStudio can do with ZRD files, see "The Ray Database Viewer".
Comments on Data Structure Memory Packing
Note that typical "C" structures in Windows are packed on 8 byte boundaries. This packing means that 2-byte members are aligned on a memory address that is an integer multiple of 2, 4-byte members are aligned on multiples of 4, and 8-byte members are aligned on multiples of 8. This packing speeds memory access but can create some small gaps in the structures. That is why structure sizes can be slightly larger than the sum of the byte sizes of all the members.
Next: