288 TUGboat, Volume 29 (2008), No. 2

Software & Tools

Asymptote: A vector graphics language

John C. Bowman and Andy Hammerlindl

Abstract

Asymptote is a powerful descriptive vector graph-ics language inspired by METAPOST that featuresrobust floating-point numerics, automatic picture siz-ing, native three-dimensional graphics, and a C++/Java-like syntax enhanced with high-order functions.

1 Motivation

The descriptive vector graphics language Asymptote1

was developed to provide a standard for drawingmathematical figures, just as TEX and LATEX havebecome the standard for typesetting equations in themathematics, physics, and computer science commu-nities. Asymptote has been aptly described as “theruler and compass of typesetting” [1]. For profes-sional quality and portability, Asymptote nativelyproduces PostScript or PDF output. Graphics la-bels are typeset directly by TEX to achieve overalldocument consistency: identical fonts and equationsshould be used in graphics and text portions of adocument.

In this article we first highlight Asymptote’s ba-sic graphics capabilities with an example and thenproceed to review the origins and distinguishing fea-tures of this powerful vector graphics language. Fur-ther examples of Asymptote diagrams, graphs, andanimations are available in the Asymptote galleryand user-written wiki:http://asymptote.sourceforge.net/gallery/http://asymptote.sourceforge.net/links.html

2 An example

The following example illustrates the four Asymptotegraphics primitives (draw, fill, clip, and label):

size(0,100);pair z1=(-1,0);pair z2=(1,0);real r=1.5;path c1=circle(z1,r);path c2=circle(z2,r);

fill(c1,lightred);fill(c2,lightgreen);

1 Andy Hammerlindl, John Bowman, and Tom Prince,available under the GNU General Public License fromhttp://asymptote.sourceforge.net/

picture intersection;fill(intersection,c1,lightred+lightgreen);clip(intersection,c2);add(intersection);

draw(c1);draw(c2);

label("$A$",z1);label("$B$",z2);path g=(0,-2)--(0,-0.25);draw(Label("$A\cap B$",0),g,Arrow);

A B

A ∩ B

3 History

Asymptote began as a University of Alberta sum-mer undergraduate research project in 2002, afterlooking into the feasibility of overhauling Hobby’sMETAPOST

2 to use floating-point numerics. Manyof the current limitations of METAPOST derive fromMETAFONT: numbers are stored in a low-precisionfixed-point format that is adequate for representingpoints in a glyph but restrictive for diagrams and sci-entific computations. While the IEEE floating-pointnumeric format was not standardized until 1985,the initial development of TEX dates back to 1978.At that time, the decision to use only fixed-point(integer-based) arithmetic was perfectly reasonable:Knuth wanted to guarantee that TEX and META-FONT would produce exactly the same bit-mappedoutput on any existing hardware.

We quickly determined that a complete rewriteof the underlying graphics engine would be necessary.After six months of work, our compiler for a newgraphics language could finally draw a sine curve.One of the four Asymptote primitives had now beenimplemented!

From this very humble beginning, Asymptoteevolved rapidly. The basic fill operation was straight-forward to implement. The most crucial advance,

2METAPOST is a modified version of METAFONT, the

program that Knuth wrote to produce the Computer Modernfonts used with TEX.

TUGboat, Volume 29 (2008), No. 2 289

aligning TEX labels at the correct positions, was ac-complished three months later, using compass direc-tions or arbitrary angles to specify label alignments:

size(0,2cm);draw((0,0)--(1,0)--(1,1)--(0,1)--cycle);label("$A$",(0,0),SW);label("$B$",(1,0),SE);label("$C$",(1,1),NE);label("$D$",(0,1),NW);

A B

CD

The idea was to leave the entire label type-setting to LATEX, inserting PostScript layers with\includegraphics, and thereby avoid the complica-tions and kerning issues inherent in the METAPOST

approach of post-processing the DVI file. To accom-plish this, Asymptote communicates with TEX viaa bidirectional pipe in two passes: the first pass isused to obtain label sizing information, while thesecond pass performs the final typesetting directlyinto DVI/PostScript or PDF. Label clipping andtransforms are implemented with PostScript or PDF

specials.A third co-developer, Tom Prince, joined us

in 2004. He contributed a method for embeddingAsymptote code directly in LATEX source files. WithTom’s help, we ported more reliable versions of theMETAPOST algorithms for basic Bezier path oper-ations such as splitting into subpaths, computingpoints of tangency, determining path bounds, andfinding intersection points. Robust arc length andarc time computations were implemented with adap-tive Simpson integration, which was determined tobe more efficient than Bezier subdivision.

On November 7, 2004, we posted our first pub-lic release, version 0.51, on sourceforge.net. Sincethen, the user base and the list of new features havegrown dramatically. The current version at the timeof this writing is 1.42. Like METAPOST, Asymptoteruns on GNU/Linux and other UNIX-like operatingsystems, Microsoft Windows, and Mac OSX. Pre-compiled Asymptote binaries are now included inseveral major Linux distributions.

4 Language features

Asymptote uses lexical analysis, parsing, and inter-mediate code generation to compile commands intovirtual machine code, optimizing speed without sac-rificing portability. Double-precision floating-pointnumbers and 64-bit integers make arithmetic over-

flow, underflow, and loss of precision issues muchless troublesome than they are in METAPOST pro-grams. Asymptote represents curves as cubic Beziersplines, but can easily handle large data values andthe pathological behaviour of functions like x sin(1/x)near the origin. It also supports new path operationslike computing the winding number of a path relativeto a given point, which is useful for identifying theregion bounded by a closed path.

Most users find the Asymptote language mucheasier to program in, with its C++/Java-like syn-tax (augmented to support high-order functions),than METAPOST, with its awkward and somewhatconfusing vardef macros. Asymptote also borrowsseveral ideas from Python, such as named functionarguments and array slices. High-level graphics com-mands are implemented in the Asymptote languageitself, allowing them to be easily tailored to specificuser applications.

Like METAPOST, Asymptote is mathematicallyoriented. For example, one can rotate vectors bycomplex multiplication and apply affine transforma-tions (shifts, rotations, reflections, and scalings) topairs, triples, paths, pens, strings, pictures, and othertransforms.

4.1 Functions

Asymptote is the only language we know of thattreats functions as variables, but allows overloadingby distinguishing variables based on their signatures.In fact, function definitions are just syntactic sugarfor assigning function objects to variables:

real square(real x) {return x^2;}

is equivalent to

real square(real x);square=new real(real x) {return x^2;};

Asymptote supports a more flexible mechanismfor default function arguments than C++: they mayappear anywhere in the function prototype. Thisfeature underlies Asymptote’s greatest strength: sen-sible default values for the basic graphical elementsallow beautiful graphs and drawings to be createdwith extremely short scripts, without sacrificing theflexibility for detailed customization. Default argu-ments are evaluated as Asymptote expressions in thescope where the function is defined.

Because certain data types are implicitly castto more sophisticated types, one can often avoidambiguities in function calls by ordering functionarguments from the simplest to the most complicated.For example, given

real f(int a=1, real b=0) {return a+b;}

290 TUGboat, Volume 29 (2008), No. 2

the call f(1) returns 1.0, but f(1.0) returns 2.0.It is sometimes difficult to remember the order inwhich arguments appear in a function declaration.Python-style named (keyword) arguments make call-ing functions with multiple arguments easier: theabove examples could respectively be written f(a=1)and f(b=1). An assignment of a function argumentis interpreted as an assignment to a parameter ofthe same name in the function signature, not in thelocal scope of the calling routine.

Rest arguments allow one to write functions thattake a variable number of arguments. For example,the following function sums its arguments:

real sum(... real[] nums) {real total=0;for(real x : nums)total += x;

return total;}

As in other modern languages, functions can callthemselves recursively. Operators, including all ofAsymptote’s built-in arithmetic and path operations,are just syntactic sugar for functions that can beaddressed and defined with the operator keyword.

Asymptote functions are first-class values, al-lowing them to be defined within, passed to, andreturned by other functions. This is convenient whenone wants to graph a sequence of functions such asfn(x) = n sin(x/n) for n = 1 to 5 from x = −10 to10:

import graph;typedef real function(real);

function f(int n) {real fn(real x) {return n*sin(x/n);

}return fn;

}

for(int n=1; n <= 5; ++n)draw(graph(f(n),-10,10));

Anonymous functions can be created with the key-word new, so that the function definition in the pre-vious example could be simplified to

function f(int n) {return new real(real x) {return n*sin(x/n);

};}

5 Modules

Function and structure definitions can be groupedinto modules:

// powers.asyreal square(real x) {return x^2;}real cube(real x) {return x^3;}

and imported:

import powers;path square(real x) {return scale(x)*unitsquare;

}real four=powers.square(2.0);real eight=cube(2.0);

For example, Asymptote ships with modules forFeynman diagrams:

k′

k

q

p′

p

e−

e+

µ+

µ−

data structures,

5

4 0

2

6 7

3

1

and algebraic knot theory:

0 1 2

Modules are written in high-level Asymptote code.Users have contributed modules tailored to manyother specialized applications (such as flowchartsand computer-aided design).

TUGboat, Volume 29 (2008), No. 2 291

6 Graphics features

METAPOST does not support many important fea-tures of PostScript. For example, only connectedPostScript subpaths are supported. Regions mustbe simply connected (have no holes) and can onlybe filled with uniform RGB colours. In addition tonative support for three-dimensional graphics, alsolacking in METAPOST, these missing features havebeen implemented in Asymptote.

6.1 Pens

Pens provide a context for the four primitive drawingcommands: they specify attributes such as color, linetype, line width, text alignment, font, font size, fillrule, and filling patterns. For non-solid line types,dash lengths are by default slightly adjusted to fit thepath arc length (for example, to allow publicationquality legend entries in graphs with multiple linetypes). Interesting calligraphic effects are possible byapplying transforms to the (normally circular) pennib or even using a polygonal pen nib (which neednot be convex):

The default pen, called currentpen, provides thesame functionality as the METAPOST pickup com-mand. Colors can be specified in any one of thePostScript colorspaces: grayscale, RGB, and CMYK.

6.2 Subpaths

An Asymptote path, being connected, is equivalent toa PostScript subpath. The binary operator ^^, whichrequests that the pen be moved (without drawing oraffecting endpoint curvatures) from the final pointof the left-hand path to the initial point of the right-hand path, may be used to group several Asymptoteconnected paths into a path[] array (equivalent toa PostScript path). While this facility is merelyconvenient for drawing an object like the skeleton ofa cube (without retracing), it is essential for fillingnonsimply-connected regions:path g=scale(2)*unitcircle;

filldraw(unitcircle^^g, evenodd+yellow, black);

The PostScript even-odd fill rule here specifies thatonly the region bounded between the two unit circles

is to be filled. In this example, the same effect can beachieved by using the default zero winding numberfill rule, if one is careful to alternate the orientationof the paths:

filldraw(unitcircle^^reverse(g), yellow,black);

6.3 Patterns

One can also construct custom pictures to be used astiling patterns for fill or draw operations. The tilingpattern can be assigned a name that can subsequentlybe used to construct a patterned pen. For example,a hatch pattern can be generated like this:

import patterns;add("hatch",hatch());filldraw(unitcircle,pattern("hatch"));

6.4 Shading

Asymptote supports axial and radial gradient shad-ing, lattice shading, Gouraud shading, and shading ofCoons and tensor product patches; the latter formsare essential for three-dimensional rendering in thepresence of a light source. Asymptote also supportsa true unfill operation implemented with clipping(the METAPOST unfill command simply fills with afixed background color).

6.5 Automatic picture sizing

A frame is a canvas for drawing in PostScript coordi-nates, much like a picture in METAPOST. However,working directly in PostScript coordinates is ofteninconvenient, requiring the tedious introduction ofmanual scaling factors.

Pictures are high-level structures that providecanvases for drawing in a user-specified Cartesiancoordinate system. Automatic sizing allows picturesto be constructed in user coordinates and then auto-matically scaled to the desired final size:

x

y

(a, 0) (2a, 0)

size(0,50);

x

y

(a, 0) (2a, 0)

size(0,100);

292 TUGboat, Volume 29 (2008), No. 2

Eventually, one must fit a picture to a Post-Script frame. This requires deferred drawing: agraphical object cannot be drawn until the actualscaling of the user coordinates (in terms of Post-Script coordinates) is known. One needs to queuea function that can draw the scaled object later,when this scaling is known. For example, the drawfunction for pictures in scalable user coordinates isimplemented in terms of the underlying PostScript-coordinate draw primitive for frames like this:

void draw(picture pic=currentpicture,path g, pen p=currentpen) {

pic.add(new void(frame f, transform t) {draw(f,t*g,p);

});pic.addPoint(min(g),min(p));pic.addPoint(max(g),max(p));

}

Here, the addPoint function stores bounding boxinformation as user (e.g. path) coordinates, whichscale linearly with the picture size, and true-size (e.g.pen) coordinates, which remain fixed.

The sizing constraints that arise between scal-able objects and fixed-sized attributes (typically la-bels, dots, linewidths, and arrowheads) reduce to alinear programming problem that is solved by the sim-plex method. However, a figure can easily producethousands of restrictions, making direct applicationof the simplex method time consuming. In practice,most of these restrictions are redundant: in the caseof concentric circles, only the largest circle needs tobe accounted for. When sizing a picture, Asymptotefirst determines which coordinates are maximal (orminimal) and sends only active constraints to thesimplex algorithm. The entire picture-sizing algo-rithm, including the simplex method, is implementedin high-level Asymptote code.

This example illustrates how deferred drawingcan be used to draw paths around text labels andthen connect them (an object is a unifying structurethat a label or frame can be implicitly cast to):

size(0,100);pair A=(0,1);pair B=(0,0);

object small=draw("small",box,A,1mm);object big=draw("\huge BIG",ellipse,B,1mm);

add(new void(frame f, transform t) {draw(f,point(small,SW,t){SW}

..{SW}point(big,NE,t));});

small

BIG

6.6 Three-dimensional graphics

We now describe our three-dimensional generaliza-tion of Hobby’s prescription for drawing an aesthet-ically pleasing, numerically efficient, interpolatingspline through a set of nodes, given optional tangentdirections and endpoint curvatures [2, 3]. This gener-alization is shape invariant under three-dimensionalrotation, scaling, and translation. In the planar case,it reduces to the two-dimensional algorithms foundin METAFONT, METAPOST, and Asymptote.

In two dimensions, a tridiagonal system of linearequations is first solved to determine any unspecifieddirections θk and φk through each node zk:

θk−1 − 2φk

`k=

φk+1 − 2θk

`k+1.

ℓk

ℓk+1

θk

φk

zk−1

zk

zk+1

The resulting shape may be adjusted by modifyingthe default tension parameters and curl boundaryconditions (cf. [3]).

Having prescribed outgoing and incoming pathdirections eiθ at node z0 and eiφ at node z1 relativeto the vector z1 − z0, any unspecified control pointsare then determined by the equations

u = z0 + eiθ(z1 − z0)f(θ,−φ),

v = z1 − eiφ(z1 − z0)f(−φ, θ),where the relative distance function f(θ, φ) is givenin [2] and [3].

In three dimensions, it is natural to require thatour generalization reduce in the planar case to theusual two-dimensional algorithm. Therefore, anyunknown incoming or outgoing tangent directionsare first determined by applying Hobby’s direction

TUGboat, Volume 29 (2008), No. 2 293

algorithm in successive planes containing the threepoints zk−1, zk, and zk+1. The only ambiguity thatcan arise is in the overall sign of the angles, whichrelates to viewing each local two-dimensional planefrom opposing normal directions. A reference vectorconstructed from the mean unit normal of successivesegments is used to resolve such ambiguities.

A formula for the three-dimensional controlpoints u and v follows on expressing Hobby’s algo-rithm in terms of the absolute incoming and outgoingunit direction vectors ω0 and ω1, respectively:

u = z0 + ω0 |z1 − z0| f(θ,−φ),

v = z1 − ω1 |z1 − z0| f(−φ, θ),

ω0

ω1

θ

φ

z0

z1

where we interpret θ and φ as the angle between thecorresponding path direction vector and z1 − z0. Inthis case there is an unambiguous reference vector fordetermining the relative sign of the angles θ and φ.

Unfortunately, PostScript and PDF support onlyBezier splines, which are shape invariant under affine(orthographic) projections (parallel lines being pro-jected to parallel lines), but not perspective projec-tions. In any dimension, applying an affine trans-formation x′i = Aijxj + Ci to a cubic Bezier curvex(t) =

∑3k=0 Bk(t)Pk for t ∈ [0, 1], where Bk(t) is

the kth cubic Bernstein polynomial yields the Beziercurve

x′i(t) =3∑

k=0

Bk(t)Aij(Pk)j + Ci =3∑

k=0

Bk(t)P ′k

in terms of the transformed kth control points P ′k,

noting that∑3

k=0 Bk(t) = 1. Thus, for orthographicprojections, both the nodes and control points ofthree-dimensional Bezier curves can simply be pro-jected to obtain their two-dimensional counterparts.

Non-uniform rational B-splines have the advan-tage of being invariant even in the presence of per-spective distortion, since they are Bezier curves inthe projective space described by homogeneous coor-dinates, where (x, y, z, w) is considered as equivalentto ( x

w , yw , z

w , 1). For example, the Asymptote syntax

(1,0,0)..(0,1,1)..(-1,0,0)..(0,-1,1)..cycle

describes a saddle-like path in three dimensions. Theresult of simply projecting the nodes and controlpoints of this three-dimensional Bezier curve to atwo dimensional Bezier curve is indicated by thedashed path in the following perspective projection.The true projection, described by the two-dimension-al nonuniform rational B-spline represented by thesolid curve, can be efficiently approximated as a two-dimensional Bezier curve by introducing additionalnodes and control points. An algorithm for doing thisefficiently will be presented in a future publication.

The three-dimensional graph of the sinc functionbelow illustrates Gouraud shading, advanced contourpath computations, and PDF transparency:

−2−1

01

2x −

2

2

y

0

0.5

1

z

6.7 Scientific graphs

Asymptote ships with a sophisticated graph modulethat quickly allows one to draw publication-qualityscientific and textbook-style graphs, such as the two-dimensional polar coordinate graph of the cardioidshown in Section 6.5 and the three-dimensional sur-face plot shown in Section 6.6. It supports featuressuch as legends, custom graph markers, secondaryaxes, custom (e.g. base 2) axes scalings, broken axes,and custom tick label formats and locations.

7 Graphical user interface

Recent versions of Asymptote include an innovativegraphical user interface, written in Python/TK, thatallows one to modify existing graphical objects and

294 TUGboat, Volume 29 (2008), No. 2

draw new ones. The modified figure can then besaved and processed as a normal Asymptote file.This allows the user to exploit the best features ofthe script (command-driven) and graphical-interfacemethods for producing figures.

8 Slide presentations

Asymptote also includes a convenient slide modulefor preparing slide presentations, including embeddedclickable high-resolution PDF movies (with optionalcontrol panels). This module has the advantage overexisting LATEX presentation packages of providingbuilt-in graphics support, including object alignment,in addition to the full power of TEX.

9 Animations

While Asymptote can create MPEG and animatedGIF movies, the lossless inline PDF movies it cangenerate with the help of the LATEX animate.stypackage are of a much higher quality. Sample anima-tions can be found in the Asymptote gallery.

10 Equation solving

Unlike METAFONT and METAPOST, Asymptote isnot built on top of an implicit linear equation solverand therefore does not automatically have the no-tion of a whatever unknown. Although such animplicit equation facility could certainly be added(perhaps using the notation ?= since = denotes as-signment in Asymptote), we have noticed that themost common uses of whatever in METAPOST arecovered by explicit functions like extension in themath module (which returns the intersection pointof the extensions of two line segments). We find theuse of routines like extension to be more explicitand less confusing, particularly to new users. But wecould be persuaded to add implicit equation solvingif someone can justify the need (so far no one hasprovided us with an example that cannot alreadybe done elegantly in Asymptote). In the meantime,one can always use the explicit built-in linear solversolve (based on LU decomposition) or one of thenumerically robust specialized solvers tridiagonal,quadraticroots, cubicroots, and quarticroots.

11 Future plans

Thanks to the LATEX movie15 package, Asymptotecan embed three-dimensional U3D files into PDF

files. In the near future, we plan to generate U3D

data (or possibly the more advanced PRC format)directly from Asymptote’s internal three-dimensionalrepresentations. This will provide the scientific com-munity with a self-contained and powerful facility forgenerating interactive three-dimensional PDF files.

12 Credits

Financial support for the development of Asymptotewas generously provided by the Natural Sciencesand Engineering Research Council of Canada, thePacific Institute for Mathematical Sciences, and theUniversity of Alberta Faculty of Science.

We would like to acknowledge enthusiasticallythe previous work of John D. Hobby, which inspiredthe development of Asymptote, and Donald E. Knuth,for his exceptionally high quality TEX typesetting sys-tem, without which none of these later developmentswould have been possible. We also thank L. Nobreand Troy Henderson for suggesting techniques forapproximating nonuniform rational B-splines.

The authors of Asymptote are Andy Hammer-lindl, John Bowman, and Tom Prince. Sean Healydesigned the Asymptote logo (below). Other con-tributors include Radoslav Marinov, Orest Shardt,Chris Savage, Philippe Ivaldi, Olivier Guibe, JacquesPienaar, Mark Henning, Steve Melenchuk, MartinWiebusch, and Stefan Knorr.

symptotesymptotesymptotesymptotesymptotesymptotesymptotesymptotesymptotesymptotesymptote

References

[1] The Art of Problem Solving: Asymptote(Vector Graphics Language). Available online athttp://www.artofproblemsolving.com, 2007.

[2] John D. Hobby. Smooth, easy to computeinterpolating splines. Discrete Comput. Geom.,1:123–140, 1986.

[3] Donald E. Knuth. The METAFONTbook.Addison-Wesley, Reading, Massachusetts, 1986.

� John C. BowmanDept. of Mathematical and Statistical SciencesUniversity of AlbertaEdmonton, AlbertaCanada T6G 2G1bowman (at) math dot ualberta dot ca

http://www.math.ualberta.ca/~bowman/

� Andy HammerlindlUniversity of TorontoDept. of MathematicsToronto, OntarioCanada M5S 2E4andy (at) math dot toronto dot edu