RayBundle

Ray information for rays traced through optical system

Since R2026a

Description

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

A RayBundle object stores information on the rays traced through the optical system from a single field point at a specific wavelength.

Creation

Create a RayBundle object by using the traceRays, traceChiefRay, or traceMarginalRays function to trace rays through an optical system.

Properties

FieldPoint — Field point representation of light source

Read-only: FieldAngle object | FieldPosition object

This property is read-only.

Field point representation of the light source, represented as one of these values.

FieldPoint Value	Field Point Type
FieldAngle object	Field point represents a light source that is at an infinite distance.
FieldPosition object	Field point represents a light source that is at a finite distance.

Wavelength — Wavelength for which rays are traced

Read-only: positive numeric scalar

This property is read-only.

Wavelength for which the rays are traced, represented as a positive numeric scalar. Units are in nanometers.

Sampling — Sampling configuration

Read-only: structure

This property is read-only.

Sampling configuration, represented as a structure with these fields.

Field	Value
Grid	Sampling grid, represented as a samplingGrid object.
Type	Sampling surface, represented as one of these options. "first-surface" — The sampling surface is the first surface in the optical system. "entrance-pupil" — The sampling surface is the entrance pupil of the optical system.

RayData — Ray data

Read-only: structure

This property is read-only.

Ray data from rays traced through the optical system, represented as a structure with these fields, which correspond to ray properties.

Field	Value
NumRays	Number of traced rays, represented as a nonnegative integer.
MaxRayLength	Maximum number of straight-line ray segments that any single ray can have as it passes through the optical system, represented as a nonnegative integer.
RayLength	Length of each ray, represented as a NumRays-by-1 vector. NumRays is the number of rays traced through the optical system. Rays can terminate before reaching the final surface if they exit the optical system or undergo total internal reflection.
Origin	Origin of the ray in the global coordinate system, represented as a NumRays-by-3 matrix, where each row is a 3-element row vector specifying the [x y z] coordinates of the ray's origin.
HitPoints	Ray intersection coordinates in the global coordinate system, represented as a NumRays-by-MaxRayLength-by-3 array. Each row along the first dimension corresponds to a ray. The second dimension indexes the sequence of hit points, such as entry, reflection, refraction, or exit points, along the ray’s path. The third dimension contains the [x y z] coordinates of each hit point. Note If a ray terminates before reaching MaxRayLength intersection points, the RayBundle object sets the corresponding trailing entries along the second dimension for that ray to NaN.
Direction	Ray direction vectors at each segment, represented as a NumRays-by-MaxRayLength-by-3 array. Each row along the first dimension corresponds to a ray. The second dimension indexes the sequence of hit points along the ray’s path. The third dimension contains the components of the direction unit vector [dX dY dZ] for the ray as it travels between each pair of hit points in the global coordinate system. Note If a ray terminates before reaching MaxRayLength intersection points, the RayBundle object sets the corresponding trailing entries along the second dimension for that ray to NaN.
TerminationMode	Ray termination, represented as a NumRays-by-1 vector. Each element represents the termination mode for the corresponding ray as one of these values. HitLastSurface — Ray exited the optical system through the last surface. SurfaceMiss — Ray exited the optical system before reaching the last surface. TotalInternalReflection — Ray was totally internally reflected and did not reach the last surface.
LastRayDirection	Final direction vector of each ray, represented as a NumRays-by-3 matrix. Each row contains the components of the final direction vector [dX dY dZ] for the corresponding ray after its last interaction within the optical system, expressed in the global coordinates.
OrientedGrid	Grid coordinates of each ray, represented as a NumRays-by-2 matrix. Each row of the matrix contains the grid coordinates [x y] of a ray, oriented such that the first column aligns with the global x-axis and the second column aligns with the global y-axis. Because these coordinates reflect the orientation of the pupil grid in the global coordinate system, you can use them to plot the ray positions at the pupil plane, oriented relative to the global axes.

To return one or more of these additional ray properties, specify the RayProperties name-value argument of the traceRays, traceChiefRay, or traceMarginalRays function.

Field	Value
HitNormal	Surface normal vectors at ray intersection points, represented as a NumRays-by-MaxRayLength-by-3 array. Each row along the first dimension corresponds to a ray. The second dimension indexes the sequence of hit points along the ray’s path. The third dimension contains the components of the surface normal vector [nX nY nZ] at each hit point in the global coordinate system. Note If a ray terminates before reaching MaxRayLength intersection points, the RayBundle object sets the corresponding trailing entries along the second dimension for that ray to NaN.
IncidentAngle	Angle of incidence at each ray-surface intersection, represented as a NumRays-by-MaxRayLength matrix. Each row along the first dimension corresponds to a ray. The second dimension indexes the sequence of hit points along the ray’s path. Each element contains the angle of incidence between the incoming ray direction and the surface normal at the corresponding intersection point. Angles are in degrees. Note If a ray terminates before reaching MaxRayLength intersection points, the RayBundle object sets the trailing columns for that ray to NaN.
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, computed as the sum of each segment’s geometric distance multiplied by the refractive index of its medium. Units are in millimeters. Note If a ray terminates before reaching MaxRayLength intersection points, the RayBundle object sets the corresponding trailing entries along the second dimension for that ray to NaN.
LocalHitPoints	Ray intersection coordinates in the local reference frame, represented as a NumRays-by-MaxRayLength-by-3 array. Each row along the first dimension corresponds to a ray. The second dimension indexes the sequence of hit points along the ray’s path. The third dimension contains the [xL yL zL] coordinates of each hit point, expressed in the local coordinate system of the corresponding optical surface. Note If a ray terminates before reaching MaxRayLength intersection points, the RayBundle object sets the corresponding trailing entries along the second dimension for that ray to NaN.
Fresnel	traceMarginalRays and traceChiefRays: This is an empty field. traceRays: 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. The s-polarized and p-polarized incident electric field vectors are perpendicular and parallel to the plane of incidence, respectively. Note For the rs, rp, ts, tp, Rs, Rp, Ts, Tp, BulkTransmission, and BulkPhaseshift fields, if a ray terminates before reaching MaxRayLength intersection points, the RayBundle object sets the corresponding trailing columns for that ray to NaN.
PolarizationMatrices	traceMarginalRays and traceChiefRays: This is an empty field. traceRays: 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. Note For the BulkMatrix SurfaceMatrix fields, if a ray terminates before reaching MaxRayLength intersection points, the RayBundle object sets the corresponding trailing entries along the second dimension (segment index) for that ray to NaN + 1i*NaN in all elements of the 3-by-3 matrix.

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

Version History

Introduced in R2026a