optical_layout.lens

Contents

Syntax

lens = davinci( 'optical_layout.lens' )
lens = davinci( ___, <GeneralParameterName>, generalparametervalue )
lens = davinci( ___, <StyleParameterName>, styleparametervalue )

Description

Assemble parameters to specify a lens, but do not draw anything. Return the assembled parameters as an object of class @davinci_optical_layout.

The figure above illustrates the lens shape parameters.

In an optical model, one usually specifies a focal length for each lens. But for a sketch it is often easier to instead specify the distance to focus for the rays that leave the lens. The latter is what DaVinci does. The associated parameter is DistanceToFocus.

The figure above shows two examples of the beam's two "edge rays" passing through a lens. In both cases, light travels left to right.

When a lens is drawn as a patch object (i.e., when DrawMethod == 'patch'), it is sometimes helpful to know which patch object index corresponds to which point on the lens. (An example where this knowledge is helpful is in the artistic use of interpolated colors and/or interpolated transparency settings across the face of the patch object, such as is documented in conjunction with DaVinci's arrow component.) The figure above illustrates the correspondence. For the case of a positive lens, there are a total of 2*NPoints-2 vertices. See the table below for the definition of NPoints. The vertex with index 1 is the top tip of the lens. The indices increase in the direction of the arrows. The vertex with index NPoints is the bottom tip of the lens. The last vertex, which has index 2*NPoints-2, is just down and to the left of the vertex with index 1. The right side of the figure illustrates the correspondence for the case of a negative lens.

The graphics handle for the lens is returned by davinci('optical_layout',...) as h.lens. The handle points to either a Matlab line object or a Matlab patch object, depending on the value of DrawMethod.

General Parameters

Parameter Default Comments
DistanceToFocus Inf

The distance, in data units, along the optical axis from the line that bisects the lens to the point where the "edge rays" focus. See the illustrations above. Must be non-zero. To specify a collimated beam, set to Inf. The value of DistanceToFocus is ignored in the special case where the lens is located at a beam focus, as explained above.

Instead of a numeric value, DistanceToFocus alternatively can be set equal to the handle of a function that, when called, returns a numeric value to use for DistanceToFocus. The function must accept a single input parameter, supplied by davinci() at runtime. The parameter is the always-positive distance from the center of the lens to the point where either edge ray strikes the line that bisects the lens. In other words, referring to the figures above, the parameter is ReferenceDistance/2. The name/value pair might look like: 'DistanceToFocus', @(hgt)10-10*5/(5-hgt).
DrawFlag true Logical true or false. If false the lens is not drawn. Though not drawn, the lens still performs its focusing action on the beam rays.
DrawMethod 'plot' Options are 'plot' and 'patch'. Indicates whether the lens should be drawn with the plot() command (which generates a line object) or with the patch() command (which generates a patch object).
Height See "Comments". The height of the lens, in data units. See the illustrations above. When the lens is at a beam focus, the user must specify a value for Height. In all other cases specifying a value for Height is optional. When not specified, Height defaults to HeightOversizeFactor times the ReferenceDistance, where ReferenceDistance is the distance between the two points on the lens bisector where the rays strike (see diagrams above). The ReferenceDistance is not specified by the user, but rather is calculated internally by davinci().
HeightOversizeFactor 2.0 See the comments for the Height parameter.
LensType 'positive' Options are 'positive' (for a positive lens) and 'negative' (for a negative lens).
Name '' The name of the lens. Must be a char vector or '' (an empty char array). See the documentation for optical_layout's overloaded ":" operator for more detail of how names work.
NPoints 50 The number of vertices for each of the two arcs that make up the lens. A larger number makes for a smoother drawing. Redundant vertices at the ends of the two arcs, when not required, are not included in the call to the Matlab drawing function. Thus the total number of vertices that make up the lens object as drawn is 2*NPoints-2 (positive lens) or 2*NPoints (negative lens) when the lens is drawn as a Matlab patch object, and 2*NPoints-1 (positive lens) or 2*NPoints+1 (negative lens) when the lens is drawn as a Matlab line object. NPoints must be greater than or equal to 3.
Thickness See "Comments". The thickness of the lens, in data units. See diagrams above. When not specified, defaults to ThicknessFactor times Height.
ThicknessFactor 0.1 See the comments for the Thickness parameter.

Style Parameters

The table below lists the parameters used to specify how the lens should be drawn.

Parameter Default Comments
Color 'k' The Color property of the Matlab line object (when the lens is drawn as a line object). Also the FaceColor property of the Matlab patch object (when the lens is drawn as a patch object), unless the FaceColor property is specified explicitly (see below).
EdgeColor 'none' The EdgeColor property of the Matlab patch object (when the lens is drawn as a patch object).
FaceAlpha 1 The FaceAlpha property of the Matlab patch object (when the lens is drawn as a patch object).
FaceColor See "Comments". The FaceColor property of the Matlab patch object (when the lens is drawn as a patch object). If the FaceColor parameter/value pair is not specified in the call to davinci(), the patch object's FaceColor property is set to the value of the Color parameter/value pair, which as shown above defaults to 'k'.
FaceVertexAlphaData [] The FaceVertexAlphaData property of the Matlab patch object (when the lens is drawn as a patch object).
FaceVertexCData [] The FaceVertexCData property of the Matlab patch object (when the lens is drawn as a patch object).
LineStyle '-' The LineStyle property of the Matlab line or patch object, whichever the lens is drawn as.
LineWidth 0.5 The LineWidth property of the Matlab line or patch object, whichever the lens is drawn as.

AttachDataForRetrievalByOutsideCode

When the AttachDataForRetrievalByOutsideCode parameter for the optical_layout shape is set to true, the lens data that is attached includes that listed in the table below.

Parameter Name Description
nameThe name, if any, assigned to the lens. Stored as a char vector. Equal to '' (an empty char array) if no name is specified.
typeThe char vector 'thin_lens'.
positionThe position, in davinci()'s global x-y coordinate system, of the center point inside the lens. This position corresponds to the origin of the b-c coordinate system illustrated in the figure above. A 1x2 vector of type double.
axis_bThe unit vector "b" parallel to the line that bisects the lens, as indicated in the figure above. To an observer riding on the beam and looking forward as the beam approaches the lens, the unit vector points toward the left side of the lens. The vector is specified in davinci()'s global x-y coordinate system. A 1x2 vector of type double.
axis_cThe unit vector "c" normal to the line that bisects the lens, as indicated in the figure above. The unit vector points into the half-space from which the beam approaches the lens. The vector is specified in davinci()'s global x-y coordinate system. A 1x2 vector of type double.
heightThe height of the lens, labeled Height in the figure above. A scalar of type double.

Examples

Examples are given in the documentation for the optical_layout component.

Copyright 2016-2017, Leonard R. Wayne, Washington, District of Columbia, United States of America. ALL RIGHTS RESERVED.