traceChiefRay

Trace chief ray through optical system

Since R2026a

collapse all in page

Syntax

chiefRay = traceChiefRay(opsys)
chiefRay = traceChiefRay(opsys,Name=Value)

Description

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

chiefRay = traceChiefRay(opsys) traces a chief ray through the optical system opsys. The chief ray is a ray that originates from the field point and passes through the center of the entrance pupil halfway between the upper and lower marginal rays of the optical system.

example

chiefRay = traceChiefRay(opsys,Name=Value) specifies options for tracing a chief ray using one or more name-value arguments. For example, FieldPoints=fieldPoint(Position=[1 0 1]) specifies to trace the chief ray from a light source at the position (1,0,1) in the global reference frame.

Examples

collapse all

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 a chief ray, specified as an opticalSystem object.

By default, the traceChiefRay function traces the chief ray 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: traceChiefRay(FieldPoints=fieldPoint(Position=[1 0 1])) specifies to trace the chief ray from a light source at the position (1,0,1) in the global reference frame.

Field point representation of a light source, 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.

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

The traceChiefRay function returns the specified ray properties as additional fields in the RayData property of the RayBundle object in chiefRay. 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.

"All"

Adds all additional ray properties to RayData.

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

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

collapse all

Chief ray 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 that represents the chief ray originating from the corresponding field point.

The chief ray is a ray that originates from the field point and passes through the center of the entrance pupil halfway between the upper and lower marginal rays of the optical system. The intersection of the chief ray with the image plane determines the image position for a particular field point.

Version History

Introduced in R2026a

See Also

| | | |

Topics