traceRays

Perform ray tracing through optical system

Since R2026a

collapse all in page

Syntax

rb = traceRays(opsys)
rb = traceRays(opsys,Name=Value)

Description

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

rb = traceRays(opsys) performs ray tracing through the optical system opsys.

example

rb = traceRays(opsys,Name=Value) specifies options for ray tracing using one or more name-value arguments. For example, FieldPoints=fieldPoint(Angle=[15 0]) specifies to trace rays from light source in the yz-plane at 15 degrees below the optical axis, located at an infinite distance away from the first surface in the optical system.

Examples

collapse all

This example uses:

Open Live Script

Create an optical system that contains a double Gauss lens using the createDoubleGauss helper function. The function is attached to this example as a supporting file.

opsys = createDoubleGauss;

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")

Figure contains an object of type optics.ui.opticalsystemviewer2d. The chart of type optics.ui.opticalsystemviewer2d has title 55-mm F/1.2 for 35-mm SLR.

This example uses:

Open Live Script

Create an optical system that contains a fisheye lens using the createWideAngle helper function. The function is attached to this example as a supporting file. 

opsys = createWideAngle;

Define a field angle representation of a light source at infinity, with a field angle of 20 degrees from the z-axis, using the fieldPoint function. 

fp = fieldPoint(Angles=[20 0]);

Trace a chief ray through the optical system using the traceChiefRay object function.

cr = traceChiefRay(opsys,FieldPoints=fp,Wavelengths=587);

Define a hexapolar sampling grid of coordinate points, through which to sample traced rays, using the samplingGrid function.

sg = samplingGrid("Hexapolar",6);

Trace rays through the optical system using the traceRays object function. Specify the defined hexapolar sampling grid using the SamplingGrid name-value argument.

rb = traceRays(opsys,FieldPoints=fp,Wavelength=587,SamplingGrid=sg);

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

hv = view2d(opsys);
addRays(hv,rb,Color="r")
addRays(hv,cr,Color="b")

Figure contains an object of type optics.ui.opticalsystemviewer2d. The chart of type optics.ui.opticalsystemviewer2d has title 15-mm F/2.8 for 35-mm SLR.

Input Arguments

collapse all

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

By default, the traceRays function traces the 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

collapse all

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: traceRays(FieldPoints=fieldPoint(Angle=[15 0])) specifies to trace rays from a light source in the yz-plane at 15 degrees below the optical axis, located at an infinite distance away from the first component in the optical system.

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

FieldPoints valueLight 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 objectsField 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.

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.

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

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

RayProperties ValueField Value in RayData

"HitNormal"

Surface normal vectors at ray intersection points, represented as a NumRays-by-MaxRayLength-by-3 array. NumRays is the number of traced rays, and MaxRayLength is the maximum number of straight-line ray segments that any single ray can have as it passes through the optical system.

The normal vector is oriented such that it points toward the incident ray direction.

"IncidentAngle"

Angle of incidence between the incoming ray and the surface normal at each intersection, represented as a NumRays-by-MaxRayLength matrix. Angles are in degrees.

"OpticalPathLength"

Optical path length (OPL), represented as a NumRays-by-MaxRayLength matrix. Each element of the matrix is the cumulative OPL from the ray origin to a specific surface for a specific ray. Units are in millimeters.

"LocalHitPoints"

Coordinates of the intersection point between a ray and a surface in the local surface coordinate system, represented as a NumRays-by-MaxRayLength-by-3 array.

"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 Optical Design.

Sampling grid of the normalized coordinates at which to sample the entrance pupil or surface, specified as a samplingGrid object. The traceRays function adds a ray at each coordinate to the ray bundle.

Surface that contains sampling grid, specified as one of these options.

  • "auto" — Trace rays from the field points through the entrance pupil, using coordinates defined in the plane of the entrance pupil for each combination of field point and wavelength. If the function cannot trace any rays through the entry pupil to the image plane, it samples the first surface instead.

  • "first-surface" — Trace rays from the field points through the grid of coordinates sampled on the first surface for each combination of field point and wavelength.

  • "entrance-pupil" — Trace rays from the field points through the entrance pupil, using coordinates defined in the plane of the entrance pupil for each combination of field point and wavelength.

Output Arguments

collapse all

Ray bundle traced through 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.

Version History

Introduced in R2026a

See Also

| | | | | | |

Topics