traceMarginalRays

R2026b

Trace marginal rays through optical system

Since R2026a

Syntax

marginalRays = traceMarginalRays(opsys)

marginalRays = traceMarginalRays(opsys,Name=Value)

Description

Add-On Required: This feature requires the Optical Design and Simulation Library for Image Processing Toolbox add-on.

marginalRays = traceMarginalRays(opsys) traces marginal rays through the optical system opsys. Marginal rays are rays that pass through the edge of the entrance pupil of an optical system.

marginalRays = traceMarginalRays(opsys,Name=Value) specifies options for tracing marginal rays using one or more name-value arguments in addition to the argument from the previous syntax. For example, FieldPoints=fieldPoint(Position=[1 0 1]) traces marginal rays from a light source at the position (1,0,1) in the global reference frame.

Examples

Simulate Ray Tracing Through Double Gauss Lens

Load a double Gauss lens from a ZMX file into the workspace.

opsys = zmximport("DoubleGaussLens.zmx");

Define a field point representation of two light sources using the fieldPoint function. The light sources are located at an infinite distance away from the first surface of the optical system, at 10 and 15 degrees below the optical axis in the *yz-*plane.

fp = fieldPoint(Angles=[10 0; 15 0]);

Trace rays through the optical system using the traceRays object function. Specify the ray wavelength as the Fraunhofer d line using the Wavelength name-value argument, and the sampling surface as the entrance pupil using the SamplingSurface name-value argument.

rb = traceRays(opsys,FieldPoints=fp,Wavelength=587.5618,SamplingSurface="entrance-pupil");

Trace marginal rays through the optical system using the traceMarginalRays object function.

mr = traceMarginalRays(opsys,FieldPoints=fp,Wavelength=587.5618);

Display the optical system using the view2d object function, and visualize the traced rays through the system using the addRays object function. The marginal and sample rays are visualized in green and red, respectively.

hv = view2d(opsys);
addRays(hv,rb,Color="r")
addRays(hv,mr,Color="g")

Input Arguments

opsys — Optical system

opticalSystem object

Optical system for which to trace marginal rays, specified as an opticalSystem object.

By default, the traceMarginalRays function traces the marginal rays from the field points specified by the FieldPoints property of the opticalSystem object, at the operational wavelengths specified by the Wavelengths property of the opticalSystem object.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: traceMarginalRays(FieldPoints=fieldPoint(Position=[1 0 1])) traces marginal rays from a light source at the position (1,0,1) in the global reference frame.

FieldPoints — Field point representation of light source

opsys.FieldPoints (default) | array of FieldPosition and FieldAngle objects | array of FieldPosition objects | array of FieldAngle objects

Field point representation of a light source or light sources, specified as one of these options:

FieldPoints value	Light Source Type
Array of FieldAngle objects	Field points represent light sources that are at an infinite distance from the first surface of the optical system.
Array of FieldPosition objects	Field points represent light sources that are at a finite distance from the first surface of the optical system.
Array of FieldPosition and FieldAngle objects	Field points represent two types of light sources, either at an infinite distance and at a finite distance from the first surface of the optical system.

By default, the value of FieldPoints is set by the FieldPoints property of the optical system opsys.

RayProperties — Additional ray properties to compute

[] (default) | "PolarizationMatrices" | "FresnelTerms" | "All" | string array | cell array of character vectors

Additional ray properties to compute, specified as one or more of these values.

The traceMarginalRays function returns the specified ray properties as additional fields in the RayData property of each RayBundle object in marginalRays. Each value of RayProperties, except "All", creates a field of the same name in RayData.

RayProperties Value	Field Value in RayData
"FresnelTerms"	Fresnel reflection and transmission coefficients at each interface, bulk transmission and phase shift, and the total transmittance through the optical system, represented as a structure with these fields. SystemTransmittance — Total transmission through the entire optical system, represented as a NumRays-by-1 vector. Each element of the vector is the total transmission for each ray. NumRays is the number of traced rays. rs — Reflection amplitude coefficient, or complex ratio, for s-polarized incident light, represented as a NumRays-by-MaxRayLength complex-valued matrix. rp — Reflection amplitude coefficient, or complex ratio, for p-polarized incident light, represented as a NumRays-by-MaxRayLength complex-valued matrix. ts — Transmission amplitude coefficient, or complex ratio, for s-polarized incident light, represented as a NumRays-by-MaxRayLength complex-valued matrix. tp — Transmission amplitude coefficient, or complex ratio, for p-polarized incident light, represented as a NumRays-by-MaxRayLength complex-valued matrix. Rs — Reflection power coefficient, which signifies the reflectance, for s-polarized incident light, represented as a NumRays-by-MaxRayLength matrix. Rp — Reflection power coefficient, which signifies the reflectance, for p-polarized incident light, represented as a NumRays-by-MaxRayLength matrix. Ts — Transmission power coefficient, which signifies the transmittance, for s-polarized incident light, represented as a NumRays-by-MaxRayLength matrix. Tp — Transmission power coefficient, which signifies the transmittance, for p-polarized incident light, represented as a NumRays-by-MaxRayLength matrix. BulkTransmission — Transmission coefficient for each ray as it propagates through the bulk medium before reaching the intersected surface, represented as a NumRays-by-MaxRayLength matrix. Each element of the matrix represents the bulk transmission. This value accounts for any absorption or attenuation that occurs along the ray's path before it interacts with a boundary or interface. For example, a value of 1 indicates perfect transmission, or zero loss. Values between 0 and 1 represent partial transmission due to absorption or scattering in the bulk material. BulkPhaseshift — Accumulated phase shift experienced by each ray as it traverses the bulk medium before reaching the intersected surface, represented as a NumRays-by-MaxRayLength matrix. Each element of the matrix represents a bulk phase shift angle, in degrees, due to the optical path length and the refractive index of the medium. This value accounts for any absorption or attenuation that occurs along the ray's path before it interacts with a boundary or interface. For example, a value of 0 means no phase shift occurs, or the ray has not traveled any distance. Positive values indicate accumulated phase due to propagation.
"PolarizationMatrices"	Polarization transformation matrices for each ray and surface intersection, represented as a structure with these fields. BulkMatrix — Polarization change matrix for propagation within each segment as the ray travels through a bulk medium between two surfaces, represented as a NumRays-by-MaxRayLength-by-3-by-3 complex array. For any given index in the first dimension i and second dimension j, BulkMatrix(i,j,:,:) is a 3-by-3 complex matrix that represents the polarization transformation experienced by ray i as it propagates through the medium between surfaces j and j – 1. This matrix describes the effect of the bulk material on the polarization state along each segment of the ray path. SurfaceMatrix — Polarization change matrix at each ray-surface intersection, represented as a NumRays-by-MaxRayLength-by-3-by-3 complex array. For any given index in the first dimension i and second dimension j, SurfaceMatrix(i,j,:,:) is a 3-by-3 complex matrix that represents the polarization transformation experienced by ray i as it propagates through the medium between surfaces j and j – 1. This matrix describes how the polarization state changes due to the reflection, refraction, or transmission at each surface that a ray encounters along its path. SystemMatrix — Overall polarization change matrix for each ray, represented as a NumRays-by-3-by-3 complex array. Each slice SystemMatrix(i,:,:) is a 3-by-3 complex matrix that represents the cumulative polarization change for the ray i.
"All"	Adds all additional ray properties to RayData.

For more information about the global and local coordinate systems, see Coordinate Systems in Optics.

Wavelengths — Wavelengths

opsys.Wavelengths (default) | M-element numeric vector

Wavelengths for which to trace rays, specified as an M-element numeric vector. M is the number of wavelengths. Each element of the vector is a wavelength, in nanometers, specified as a positive scalar.

Output Arguments

marginalRays — Marginal rays

N-by-M matrix of RayBundle objects

Marginal rays traced through the optical system, returned as an N-by-M matrix of RayBundle objects. N is the number of field points, and M is the number of wavelengths for which the chief ray is traced. Each element of the matrix is a RayBundle object.

Marginal rays are the outermost rays that can pass through the system to the image plane, and define the boundary of the light cone entering the system as they pass through the edges of the major and minor axes of the entrance pupil ellipse.

Note

The traceMarginalRays function attempts to trace rays for each specified field point at the entrance pupil. If rays cannot be traced for a particular field point, the function skips tracing for that field point and continues tracing rays for the remaining field points.

Limitations

The traceMarginalRays function determines the marginal rays by locating the entrance pupil. For optical systems with surface discontinuities or non‑convex apertures, the entrance pupil and corresponding marginal rays can be ill‑defined. In these cases, traceMarginalRaysmight be unable to identify unique marginal rays for a specific field point and wavelength combination.

To visualize the actual ray paths through such systems, use traceRays and specify an explicit sampling surface using the SamplingSurface argument, such as "first-surface".

Version History

Introduced in R2026a

R2026b: Compute Fresnel terms and polarization matrices for traced rays

Using the traceMarginalRays function, you can now compute Fresnel terms and polarization matrices by specifying the RayProperties name-value argument.