How DaVinci Works
Contents
The Basics
DaVinci uses low-level Matlab graphics commands to draw mid-level shapes.
For example, to draw a double arrow a user might issue the following command:
h = davinci( 'arrow', 'X', [0 10], ... 'Y', [0 0], ... 'ArrowType', 'double', ... 'Head.Length', 3, ... 'Head.Width', 2, ... 'Head.Sweep', 1, ... 'EdgeColor', 'r', ... 'LineWidth', 2 );
Internally, DaVinci issues three low-level Matlab commands to draw the arrow (one for the shaft and one for each of the two arrow heads):
h.shaft = plot( [3 7], [0 0], 'Color', 'k', 'LineWidth', 2 ); h.head_1 = patch( 'XData', [3 4 0 4], 'YData', [0 -1 0 1], 'EdgeColor', 'r', 'FaceColor', 'k', 'LineWidth', 2 ); h.head_2 = patch( 'XData', [7 6 10 6], 'YData', [0 1 0 -1], 'EdgeColor', 'r', 'FaceColor', 'k', 'LineWidth', 2 );
Simple!!
Internal Syntax
DaVinci always uses the following syntax to call the built-in Matlab graphics functions, unless stated otherwise. See the Matlab documentation for an explanation of the syntax.
Matlab line objects are created with this command:
this_h = plot(X,Y,'PropertyName',propertyvalue...)
Matlab patch objects are created with this command:
this_h = patch('XData',X,'YData',Y,'PropertyName',propertyvalue...)
hold on / hold off
DaVinci provides sensible management of the hold state of the Matlab axes object.
- If the hold state of the current axes object is off when davinci() is called, the hold state will be off when davinci() finishes.
- If the hold state of the current axes object is on when davinci() is called, the hold state will be on when davinci() finishes.
- If calling davinci() creates a new axes object (such as happens if no Matlab figure exists when davinci() is called), the hold state of the new axes object will be off when davinci() finishes.
- davinci() may temporarily adjust the hold state during execution to draw a shape composed of more than one line or patch object.
"Pass Through" Arguments
Although DaVinci explicitly encodes a large number of style options (LineWidth, etc.), this is still only a fraction of the options generally available in Matlab.
To provide access to more of Matlab's functionality, one thing DaVinci does is provide a "pass through" mechanism. (Another is davinci() returns graphics handles that may be used to adjust a drawing after it is drawn.)
The "pass through" mechanism allows a user to specify extra parameter/value pairs for DaVinci to append to DaVinci's function calls to plot() and patch().
For example, to draw an arrow and specify settings for the AlignVertexCenters and DisplayName properties of the patch object drawn for the arrow head, use the following syntax:
davinci( 'arrow', 'X', [0 10], ... 'Y', [0 0], ... 'Patch.ExtraArgs', { 'AlignVertexCenters', 'on', ... 'DisplayName', 'My Patch' } )
Internally, DaVinci issues the following command to draw the arrow head, including the two extra parameter/value pairs:
patch( 'XData', [9 8 10 8], ... 'YData', [0 .5 0 -.5], ... 'EdgeColor', 'none', ... 'FaceColor', 'k', ... 'AlignVertexCenters', 'on', ... 'DisplayName', 'My Patch' )
DaVinci does not define the order in which parameter/value pairs are included in DaVinci's calls to patch() and plot(). However, ExtraArgs parameter/value pairs are included together as a group, maintaining order relative to each other.
Copyright 2015, Leonard R. Wayne, Washington, District of Columbia, United States of America.