Next: , Up: Drawing commands


5.1 draw

 
void draw(picture pic=currentpicture, Label L="", path g,
          align align=NoAlign, pen p=currentpen,
          arrowbar arrow=None, arrowbar bar=None, margin margin=NoMargin,
          string legend="", marker marker=nomarker);

Draw the path g on the picture pic using pen p for drawing, with optional drawing attributes (Label L, explicit label alignment align, arrows and bars arrow and bar, margins margin, legend, and markers marker). Only one parameter, the path, is required. For convenience, the arguments arrow and bar may be specified in either order. The argument legend is a string to use in constructing an optional legend entry.

Bars are useful for indicating dimensions. The possible values of bar are None, BeginBar, EndBar (or equivalently Bar), and Bars (which draws a bar at both ends of the path). Each of these bar specifiers (except for None) will accept an optional real argument that denotes the length of the bar in PostScript coordinates. The default bar length is barsize(p).

The possible values of arrow are None, Blank (which draws no arrows or path), BeginArrow, MidArrow, EndArrow (or equivalently Arrow), and Arrows (which draws an arrow at both ends of the path). These arrow specifiers (except for None and Blank) may be given the optional arguments real size (arrowhead size in PostScript coordinates), real angle (arrowhead angle in degrees), Fill or NoFill, and (except also for MidArrow and Arrows) a relative real position along the path (an arctime) where the tip of the arrow should be placed. The default arrowhead size is arrowheadsize(p). There are also arrow versions with slightly modified default values of size and angle suitable for curved arrows: BeginArcArrow, EndArcArrow (or equivalently ArcArrow), MidArcArrow, and ArcArrows.

Margins can be used to shrink the visible portion of a path by labelmargin(p) to avoid overlap with other drawn objects. Typical values of margin are NoMargin, BeginMargin, EndMargin (or equivalently Margin), and Margins (which leaves a margin at both ends of the path). One may use Margin(real begin, real end) to specify the size of the beginning and ending margin, respectively, in multiples of the units labelmargin(p) used for aligning labels. Alternatively, BeginPenMargin, EndPenMargin (or equivalently PenMargin), PenMargins, PenMargin(real begin, real end) specify a margin in units of the pen linewidth, taking account of the pen linewidth when drawing the path or arrow. For example, use DotMargin, an abbreviation for PenMargin(-0.5,0.5*dotfactor), to draw from the usual beginning point just up to the boundary of an end dot of width dotfactor*linewidth(p). The qualifiers BeginDotMargin, EndDotMargin, and DotMargins work similarly. The qualifier TrueMargin(real begin, real end) allows one to specify a margin directly in PostScript units, independent of the pen linewidth.

The use of arrows, bars, and margins is illustrated by the examples Pythagoras.asy, sqrtx01.asy, and triads.asy.

The legend for a picture pic can be fit and aligned to a frame with the routine (see filltype)

frame legend(picture pic=currentpicture, pair dir=0, 
             real xmargin=legendmargin, real ymargin=xmargin,
             pen p=currentpen);
this legend frame can then be added about the point origin to a picture dest using add or attach (see add about).

To draw a dot, simply draw a path containing a single point. The dot command defined in plain.asy draws a dot having a a diameter equal to an explicit pen linewidth or the default linewidth magnified by dotfactor (6 by default):

void dot(picture pic=currentpicture, pair z, pen p=currentpen);
void dot(picture pic=currentpicture, pair[] z, pen p=currentpen);
void dot(picture pic=currentpicture, Label L, pair z, align align=NoAlign,
         string format=defaultformat, pen p=currentpen)
void dot(picture pic=currentpicture, Label L, pen p=currentpen)

The third routine draws a dot at every point of a pair array z. If the special variable Label is given as the Label argument to the fourth routine, the format argument will be used to format a string based on the dot location (here defaultformat is "$%.4g$"). One can also draw a dot at every node of a path:

void dot(picture pic=currentpicture, guide g, pen p=currentpen);
See markers for a more general way of marking path nodes.

To draw a fixed-sized object (in PostScript coordinates) about the user coordinate origin, use the routine

void draw(pair origin, picture pic=currentpicture, Label L="", path g,
          align align=NoAlign, pen p=currentpen, arrowbar arrow=None,
          arrowbar bar=None, margin margin=NoMargin, string legend="",
          marker marker=nomarker);