# How DaVinci Works

## Contents

## Translate To Low-Level Commands

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 Matlab's built-in
`patch()`

and `plot()`

graphics
functions, unless stated otherwise. See the Matlab documentation
for an explanation of the syntax. DaVinci does not define the order in which
the `'PropertyName',propertyvalue`

pairs are included in DaVinci's
calls to `patch()`

and `plot()`

.

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...)`

## newplot()

DaVinci adheres to the standard Matlab behavior for creating and updating drawings.

- If
`davinci()`

is called when (a) a current Matlab`axes`

object exists and (b) the`hold`

state for said`axes`

object is`on`

, then`davinci()`

does not make any changes to the Matlab`figure`

or`axes`

objects before issuing its drawing commands. - In all other cases in which
`davinci()`

is called (except those special cases in which`davinci()`

does not draw anything),`davinci()`

calls the Matlab`newplot()`

function to prepare the Matlab`figure`

and`axes`

objects for drawing.

## appdata

DaVinci sometimes makes some of its data available to external Matlab
programs by attaching the data (via Matlab's `setappdata()`

command) to the relevant `axes`

object. (Currently this functionality is available only with DaVinci's
`optical_layout`

component.) This affects as follows how
DaVinci prepares the Matlab `axes`

object when a drawing is
going to be made.

- If
`davinci()`

is called when (a) a current Matlab`axes`

object exists and (b) the`hold`

state for said`axes`

object is`off`

, then as part of preparing the Matlab`axes`

object for drawing,`davinci()`

deletes any appdata attached to the`axes`

object. - If
`davinci()`

is called when (a) a current Matlab`axes`

object exists and (b) the`hold`

state for said`axes`

object is`on`

, then the call to`davinci()`

does not delete any appdata from the`axes`

object.

## 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 may happen 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.

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