traceAimedRay

R2026b

Trace ray aimed at specific point on target optical surface

Since R2026b

Syntax

rayBundle = traceAimedRay(opsys)

rayBundle = traceAimedRay(opsys,Name=Value)

Description

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

rayBundle = traceAimedRay(opsys) traces a single ray through the optical system opsys, starting at the first field point in the optical system, and passing through a default target point, which is the center of the aperture stop surface if a diaphragm is present, or the center of the first surface.

rayBundle = traceAimedRay(opsys,Name=Value) specifies options for tracing an aimed ray using one or more name-value arguments. For example, TargetSurfaceIndex=10 aims the ray at surface 10 in the optical system.

Examples

Trace Aimed Ray Through Optical System

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

opsys = zmximport("DoubleGaussLens.zmx");

Specify the field point from which to trace an aimed ray.

opsys.FieldPoints(1) = fieldPoint(Position=[0 -10 0]);

Trace an aimed ray from the field point.

rbt = traceAimedRay(opsys);

Display the optical system and the traced ray in 2-D.

hv = view2d(opsys);
addRays(hv,rbt);

Input Arguments

opsys — Optical system through which to trace aimed ray

opticalSystem object

Optical system through which to trace the aimed ray, specified as an 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: traceAimedRay(opsys,TargetSurfaceIndex=10,TargetSurfacePoint=[0 12]) aims the ray at the point (0, 12) on surface 10.

FieldPoint — Field point from which to start tracing ray

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

Field point from which to start tracing the ray, specified as one of these options:

FieldPoint 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 or at a finite distance from the first surface of the optical system.

To specify light source representations, create field points or arrays of field points using the fieldPoint function.

TargetSurfaceIndex — Index of surface containing target point

positive integer

Index of the surface containing the target point, specified as a positive integer. The value must be between 1 and the number of surfaces in the optical system.

The default is the index of the first diaphragm (aperture stop) surface. If the optical system does not have a physical diaphragm, the default is 1.

TargetSurfacePoint — Point on target surface at which ray is aimed

[0 0] (default) | two-element numeric vector

Point on the target surface at which the ray is aimed, specified as a two-element numeric vector of the form [x, y], where x and y are the local coordinates of the surface. Specifying the point in local coordinates enables you to define the target relative to the surface, independent of its global position or tilt.

Wavelength — Wavelength at which to trace ray

opsys.PrimaryWavelength (default) | positive scalar

Wavelength at which to trace the ray, specified as a positive scalar in nanometers.

RayProperties — Additional ray properties to compute

[] (default) | string scalar | string array | character vector | cell array of character vectors

Additional ray properties to compute, specified as a string scalar, string array, character vector, or cell array of character vectors with one or more of these values.

The traceAimedRay function returns the specified ray properties as additional fields in the RayData property of rayBundle. 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 an N-by-1 vector. Each element of the vector is the total transmission for a ray. N is the number of traced rays. rs — Reflection amplitude coefficient, or complex ratio, for s-polarized incident light, represented as an N-by-MaxRayLength complex-valued matrix. MaxRayLength is the maximum number of surfaces intersected by any ray. rp — Reflection amplitude coefficient, or complex ratio, for p-polarized incident light, represented as an N-by-MaxRayLength complex-valued matrix. ts — Transmission amplitude coefficient, or complex ratio, for s-polarized incident light, represented as an N-by-MaxRayLength complex-valued matrix. tp — Transmission amplitude coefficient, or complex ratio, for p-polarized incident light, represented as an N-by-MaxRayLength complex-valued matrix. Rs — Reflection power coefficient, which signifies the reflectance, for s-polarized incident light, represented as an N-by-MaxRayLength matrix. Rp — Reflection power coefficient, which signifies the reflectance, for p-polarized incident light, represented as an N-by-MaxRayLength matrix. Ts — Transmission power coefficient, which signifies the transmittance, for s-polarized incident light, represented as an N-by-MaxRayLength matrix. Tp — Transmission power coefficient, which signifies the transmittance, for p-polarized incident light, represented as an N-by-MaxRayLength matrix. BulkTransmission — Transmission coefficient for each ray as it propagates through the bulk medium before reaching the intersected surface, represented as an N-by-MaxRayLength matrix. Each element (i, j) represents the bulk transmission of ray i as it propagates to surface j. 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 an N-by-MaxRayLength matrix. Each element (i, j) represents the bulk phase shift angle, in degrees, of ray i as it propagates to surface j. 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 shift 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 an N-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 an N-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 at surface j. 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 an N-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.

Data Types: string | char | cell

Output Arguments

rayBundle — Traced ray result

RayBundle object

Traced ray result, returned as a RayBundle object.

Version History

Introduced in R2026b