optical_layout.absorber AND optical_layout.mirror

Contents

Syntax

ABSORBER:
absorber = davinci( 'optical_layout.absorber' )
absorber = davinci( ___, <GeneralParameterName>, generalparametervalue ... )
absorber = davinci( ___, <StyleParameterName>, styleparametervalue ... )
MIRROR: mirror = davinci( 'optical_layout.mirror' ) mirror = davinci( ___, <GeneralParameterName>, generalparametervalue ... ) mirror = davinci( ___, <StyleParameterName>, styleparametervalue ... )

Description

An absorber and a mirror have the same set of drawing parameters as each other, so we have combined the documentation for the two.

Assemble parameters to specify an optical [absorber/mirror], but do not draw anything. Return the assembled parameters as an object of class @davinci_optical_layout.

There are 3 ways to sketch an [absorber/mirror], as listed in the table below.

Option Illustrations (Normal and Non-Normal Beam Incidence)

OPTION #1 (default): Draw the [absorber/mirror] as a single line.

  • This is a Matlab line object with two vertices. The graphics handle is returned by davinci('optical_layout',...) as [h.absorber/h.mirror].

OPTION #2: Draw the [absorber/mirror] as a rectangle composed of four line segments.

  • This is a Matlab line object with five vertices (the last a repeat of the first). The graphics handle is returned by davinci('optical_layout',...) as [h.absorber/h.mirror].

  • Two ways to trigger this option are:

    1. Specify a value for Thickness (which causes the code to set LineOrRectangle to 'rectangle'), and set the value of DrawMethod to 'plot'.

    2. Set the value of LineOrRectangle to 'rectangle', and set the value of DrawMethod to 'plot'.

OPTION #3: Draw the [absorber/mirror] as a solid rectangle.

  • This is a Matlab patch object with four vertices. The graphics handle is returned by davinci('optical_layout',...) as [h.absorber/h.mirror]. The vertex indices are indicated in the figures to the right. To an observer riding on the beam and looking forward as the beam approaches the [absorber/mirror], the vertex on the left side of the front surface of the [absorber/mirror] always has index 1. The indices increase as one moves clockwise around the patch object, as shown.

  • Two ways to trigger this option are:

    1. Specify a value for Thickness (which causes the code to set LineOrRectangle to 'rectangle'). (Leave DrawMethod at its default value of 'patch'.)

    2. Set the value of LineOrRectangle to 'rectangle'. (Leave DrawMethod at its default value of 'patch'.)

General Parameters

Parameter Default Comments
DrawFlag true Logical true or false. If false the [absorber/mirror] is not drawn. Though not drawn, the [absorber/mirror] still performs its action on the beam rays - absorb or reflect.
DrawMethod See "Comments". Options are 'plot' and 'patch'. Indicates whether the [absorber/mirror] should be drawn with the plot() command (which generates a line object) or with the patch() command (which generates a patch object). See the comments for LineOrRectangle for more detail.
Height See "Comments". The height of the [absorber/mirror], in data units. See the illustrations above. When the [absorber/mirror] 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 [absorber/mirror] surface 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.
LineOrRectangle See "Comments". Options are 'line' and 'rectangle'. Indicates whether the [absorber/mirror] should be drawn as a line (a 2-vertex Matlab line object) or a rectangle (either a 5-vertex Matlab line object or a 4-vertex Matlab patch object, depending on the value of DrawMethod).

The values for the three parameters LineOrRectangle, DrawMethod, and Thickness are coupled together. The algorithm that determines the default values for LineOrRectangle and DrawMethod is here. Three common scenarios are:

  1. The user does not specify a value for any of the three parameters. Then LineOrRectangle is set to 'line' (and DrawMethod is automatically set to 'plot' since one uses plot() to draw a line, not patch()).
  2. The user specifies a value for Thickness but not the other two parameters. Then LineOrRectangle is set to 'rectangle' (since a value for Thickness implies a rectangle), and DrawMethod is set to 'patch'.
  3. The user sets the value of LineOrRectangle to 'rectangle' but does not set values for the other two parameters. Then DrawMethod is set to 'patch', and a value for Thickness is chosen as discussed in the comments for Thickness.
Name '' The name of the [absorber/mirror]. Must be a char vector or ''. See the documentation for optical_layout's overloaded ":" operator for more detail of how names work.
Thickness See "Comments". The thickness of the [absorber/mirror], in data units. See diagrams above. If specified, implies LineOrRectangle is 'rectangle'. When not specified, defaults to ThicknessFactor times Height. See also the comments for LineOrRectangle.
ThicknessFactor 0.1 See the comments for Thickness.

Style Parameters

The table below lists the parameters used to specify how the [absorber/mirror] should be drawn.

Parameter Default Comments
Color 'k' The Color property of the Matlab line object (when the [absorber/mirror] is drawn as a line object). Also the FaceColor property of the Matlab patch object (when the [absorber/mirror] 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 [absorber/mirror] is drawn as a patch object).
FaceAlpha 1 The FaceAlpha property of the Matlab patch object (when the [absorber/mirror] is drawn as a patch object).
FaceColor See "Comments". The FaceColor property of the Matlab patch object (when the [absorber/mirror] 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 [absorber/mirror] is drawn as a patch object).
FaceVertexCData [] The FaceVertexCData property of the Matlab patch object (when the [absorber/mirror] is drawn as a patch object).
LineStyle '-' The LineStyle property of the Matlab line or patch object, whichever the [absorber/mirror] is drawn as.
LineWidth 0.5 The LineWidth property of the Matlab line or patch object, whichever the [absorber/mirror] is drawn as.

AttachDataForRetrievalByOutsideCode

When the AttachDataForRetrievalByOutsideCode parameter for the optical_layout shape is set to true, the [absorber/mirror] data that is attached includes that listed in the table below.

Parameter Name Description
nameThe name, if any, assigned to the [absorber/mirror]. Stored as a char vector. Equal to '' (an empty char array) if no name is specified.
typeThe char vector 'absorber' or 'fold_mirror'.
positionThe position, in davinci()'s global x-y coordinate system, of the center of the front face of the [absorber/mirror]. This position corresponds to the origin of the b-c coordinate system illustrated in the figures above. A 1x2 vector of type double.
axis_bThe unit vector "b" parallel to the front face of the [absorber/mirror], as indicated in the figures above. To an observer riding on the beam and looking forward as the beam approaches the [absorber/mirror], the unit vector points toward the left side of the [absorber/mirror]. 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 front face of the [absorber/mirror], as indicated in the figures above. The unit vector points outward from the [absorber/mirror]. The vector is specified in davinci()'s global x-y coordinate system. A 1x2 vector of type double.
heightThe height of the [absorber/mirror], labeled Height in the figures 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.