arrow

Contents

Syntax

davinci( 'arrow', 'X', [x1 x2], 'Y', [y1 y2] )
davinci( ___, <StyleParameterName>, styleparametervalue )
h = davinci( ___ )

Description

Draw an arrow between [x1 y1] and [x2 y2].

There are four categories of arrow to choose from, as shown in the table below. The categories are:

Shaft.Type == 'line' (default) Shaft.Type == 'rectangle'
ArrowType
==
'single'

(default)

  • The shaft is drawn as a Matlab line object. The graphics handle is returned as h.shaft.
  • The head is drawn as a Matlab patch object. The graphics handle is returned as h.head.
  • The arrow (including head and shaft) is drawn as a single Matlab patch object. The graphics handle is returned as h.
  • The code will throw an error (with a helpful message) if the combination of values for the parameters shown above is such that the lines between vertices on the patch object would cross over each other.
ArrowType
==
'double'
  • The shaft is drawn as a Matlab line object. The graphics handle is returned as h.shaft.
  • Each of the two heads is drawn as its own Matlab patch object. The graphics handles are returned as h.head_1 (for the head that touches [x1 y1]) and h.head_2.
  • The code will throw an error (with a helpful message) if the combination of values for the parameters shown above is such that the two patch objects would overlap each other.
  • The arrow (including the shaft and both heads) is drawn as a single Matlab patch object. The graphics handle is returned as h.
  • The code will throw an error (with a helpful message) if the combination of values for the parameters shown above is such that the lines between vertices on the patch object would cross over each other.

Style Parameters

The table below lists the available style parameters.

As indicated in the table, 'normalized' units can be used for some quantities. These normalizations are relative to NormalizationLength (see diagrams above) which is calculated internally and not specified by the user. NormalizationLength is always calculated as the distance between [x1 y1] and [x2 y2], even when the arrowhead has a large sweep that extends past the tail point [x1 y1].

'data' units are plot units.

Parameter Default Comments
ArrowType 'single' 'single' or 'double'. See diagrams above.
Color 'k' The Color property of the Matlab line object (if one is drawn). Also the FaceColor property of the Matlab patch object(s), unless the FaceColor property is specified explicitly (see below).
EdgeColor 'none' The EdgeColor property of the Matlab patch object(s).
FaceAlpha 1 The FaceAlpha property of the Matlab patch object(s).
FaceColor See "Comments". The FaceColor property of the Matlab patch object(s). If the FaceColor parameter/value pair is not specified in the call to davinci(), each 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(s).
FaceVertexCData [] The FaceVertexCData property of the Matlab patch object(s).
LineStyle '-' The LineStyle property of the Matlab line object (if one is drawn) and of the Matlab patch object(s).
LineWidth 0.5 The LineWidth property of the Matlab line object (if one is drawn) and of the Matlab patch object(s).
Head.Length See "Defaults" section below. See diagrams above.
Head.LengthUnits 'data' 'normalized' or 'data'. 'normalized' means relative to NormalizationLength (see diagrams above).
Head.Sweep See "Defaults" section below. See diagrams above.
Head.SweepUnits 'data' 'normalized' or 'data'. 'normalized' means relative to NormalizationLength (see diagrams above).
Head.Width See "Defaults" section below. See diagrams above.
Head.WidthUnits 'data' 'normalized' or 'data'. 'normalized' means relative to NormalizationLength (see diagrams above).
Shaft.Type See "Comments". 'line' or 'rectangle'. See diagrams above. Defaults to 'line' unless Shaft.Width is specified, in which case defaults to 'rectangle' (since a value for Shaft.Width implies Shaft.Type is 'rectangle').
Shaft.Width See "Defaults" section below. See diagram above. If specified, implies Shaft.Type is 'rectangle', but ignored with a warning if Shaft.Type is explicitly set to 'line'.
Shaft.WidthUnits 'data' 'normalized' or 'data'. 'normalized' means relative to NormalizationLength (see diagrams above). Ignored unless Shaft.Type is set to 'rectangle'.

Defaults

Default values for the following four parameters are computed with an algorithm that is copied here.

The algorithm is complicated in several places, due to the following constraint that may be violated if care is not taken when choosing parameter values. The lines between vertices on Matlab patch object(s) should not cross over each other. A proper combination of values for the four parameters listed above is required for a given arrow length and for a given arrow type (single or double). The algorithm allows the user significant flexibility to define as few or as many of the four parameter values as desired and still obtain sensible (when possible) default values for any remaining parameters. "Sensible" values are values that make the arrow look "normal."

Examples

EXAMPLE #1 -- DRAW A SIMPLE ARROW.

davinci( 'arrow', 'X', [0 10], 'Y', [0 0] );
daspect( [1 1 1] )   % Set the aspect ratio at 1:1.

EXAMPLE #2 -- DRAW A DOUBLE ARROW.

davinci( 'arrow', 'X', [0 10], 'Y', [0 0], 'ArrowType', 'double' );
daspect( [1 1 1] )   % Set the aspect ratio at 1:1.

EXAMPLE #3 -- MISCELLANEOUS ARROW SHAPES.

The code to draw arrows "A" thru "K" is here.

Arrows "A" thru "F" have miscellaneous general shapes.

Arrows "G" thru "K" are special cases.

Arrows "I", "J", and "K" have Head.Length equal to the arrow length (NormalizationLength in the diagram above).

EXAMPLE #4 -- CUSTOMIZE STYLE PARAMETER VALUES.

Draw a white double arrow with a medium-thick blue rim.

davinci( 'arrow', 'X',             [0 10], ...
                  'Y',             [0  0], ...
                  'ArrowType',   'double', ...
                  'Shaft.Width',       .5, ...
                  'Head.Length',      1.5, ...
                  'Head.Sweep',         1, ...
                  'Head.Width',         2, ...
                  'Color',            'w', ...
                  'EdgeColor',        'b', ...
                  'LineWidth',        2.5 );
daspect( [1 1 1] )

EXAMPLE #5 -- PATCH VERTEX INDICES.

It can be helpful to know the number of patch object vertices and their indices, as shown in subsequent examples. The diagram below illustrates all the possibilities. In each case [x1 y1] is on the left side of the arrow and [x2 y2] is on the right side. The top four arrows ("A" thru "D") are ArrowType 'single' ("single" arrows) and the bottom four are ArrowType 'double' ("double" arrows). Each vertex is marked with a circle, and a number shows the index. One way to determine the number of vertices on a given arrow is to examine the graphics handle(s) for the patch object(s) after the arrow is drawn.

The code to draw the eight arrows is here.

EXAMPLE #6 -- ARTISTIC USE OF TRANSPARENCY.

Below are examples that make artistic use of Matlab's patch object transparency ("alpha") settings.

The code to draw the arrows is here.

EXAMPLE #7 -- ARTISTIC USE OF INTERPOLATED FACE COLORS.

Below are examples that make artistic use of Matlab's patch object interpolated face color settings.

The code to draw the arrows is here.

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