Asymptote: Reference

Asymptote (Vector Graphics Language)

Getting Started - Basics - Drawing - Labeling - Filling - Useful functions - Examples - Macros and Packages Help - Reference - Advanced Asymptote - 3D Graphics - CSE5 Package - How to

Points

A point is associated with a cartesian coordinate pair in Asymptote. There are two useful functions that allow one to use polar coordinates as well:

 dir(theta)

returns the point (cos(theta),sin(theta)) where theta is in degrees, and

 expi(theta)

returns the complex number , i.e. (cos(theta),sin(theta)) where theta is measured in radians.

Paths

A path (or guide - see Variables and Data Types for the difference) in Asymptote is simply a cubic function of a parameter , parameterized as ranges from to the number of nodes (say ) that determine the path. The most basic way to make paths is by joining points (which can be thought of as paths with length 0) and paths together with the -- and .. operators. The former connects each pair of points or paths with a straight line, and the latter connects them with a Bezier cubic spline interpolation so that paths are joined smoothly. The symbol cycle connected to a path tells Asymptote to form a cyclic path by joining the endpoint with to that with . As an example, try both

 draw((0,0)--(1,0)--(1/2,sqrt(3)/2)--cycle); 

and

 draw((0,0)..(1,0)..(1/2,sqrt(3)/2)..cycle);  

Pens and Coloring

A pen is just that - the style with which Asymptote draws your paths or pictures. Pens can have various colors, dash patterns (linetypes), and linewidths. The following table gives a variety of examples of pen types and their output:

We can also add pens with the + operator. For example, the command

 draw((0,0)--(100,100),orange+dashed+linewidth(1));

will produce the image

  \includegraphics{Pen14.pdf}

The default pen has linetype solid="", linewidth .5, and color black.

Basic drawing commands

Asymptote has four basic drawing commands, draw, fill, clip, and label. The most important of these is draw.

Draw

The function draw can take many arguments. The following is the structure of a draw command, where anything with = denotes the default value:

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

So with draw, you can draw path g to the picture pic along with a string label L, with pen p, etc. Of course, most of this is unnecessary for a basic diagram. The most important thing to notice is that the only non-optional argument of draw is the path g. The command draw(g); where g is a path simply draws the path on top of your current picture.

Fill

The structure of fill is much simpler than that of draw:

  void fill(picture pic=currentpicture, path g,pen p=currentpen);

This fills a cyclic path g in picture pic (see the section on Paths above) with a specified pen p (most often a color - see Pens and Coloring above). For example, the command

fill((0,0)--(0,1)--(1,1)--(1,0)--cycle,red);

will fill the unit square with the color red.

Clip

The structure of clip is also simple:

 void clip(picture pic=currentpicture, path g, pen p=currentpen);

This crops a picture so that the boundary is the given path g, and the boundary is then drawn with pen p.

Label

Label is used for, well, labeling your diagram.

Structure:

void label(picture pic=currentpicture, Label L, pair position,
          align align=NoAlign, pen p=nullpen, filltype filltype=NoFill);

This places a label L (usually a string, which can include LaTeX code!) at the point position, aligned by default so that the center of the label is at the position, with optional pen and filltype for its bounding box. The alignment options, however, can be very useful; any pair can be given as a direction for alignment, and the built-in alignment directions are the compass directions N, E, S, W, NE, NW, SE, SW, ENE, etc. Thus if you wish to label the lower left hand vertex of the right triangle 2(0,0)--(100,0)--(0,100)--cycle with the letter , you can use the SW alignment so that the label does not overlap with the diagram:

 label("",(0,0),SW);

Try it!

Pictures

The basic drawing commands all draw onto pictures, the default picture being currentpicture, which is the one that you see when you build your image. However, you can define a new picture in order to treat several drawn parts as a single object, which can be shifted and transformed as a whole relative to currentpicture. One picture (pic1) can be added to another (pic2) with the command add(pic2,pic1), and by default add(pic) simply adds pic to currentpicture. For example:

 picture pic;
 size(3cm);
 draw(pic,unitsquare);
 draw(pic,unitcircle);
 add(shift(3*right)*pic);
 draw(unitsquare);
 draw(unitcircle);

will display:

Transforms

Transforms are objects that can be applied to pairs, paths, pictures, and other transforms by the * operator. The most commonly used transforms are: