Asymptote: the Vector Graphics Language

1 asymptote : the Vector GraphicsLanguageFor version file documentsAsymptote, version 2004-22 Andy Hammerlindl, John Bowman, and Tom is granted to copy, distribute and/or modify this document underthe terms of theGNUL esser General Public License (see the file LICENSE inthe top-level source directory).iTable of Contents1 UNIX binary distributions.. MacOS X binary distributions.. Microsoft Windows.. Configuring.. Search paths.. Compiling from UNIX source.. Editing modes.. Git.. Uninstall..83 Drawing in batch mode.. Drawing in interactive mode.. Figure size.. Labels.. Paths..114 Drawing draw.. fill.. clip.. label..185 Bezier Data types.. Paths and guides.. Pens.. Transforms.. Frames and pictures.. Files.. Variable initializers.. Structures.. Operators.. Arithmetic & logical operators.. Self & prefix operators.. User-defined operators.

2 Implicit scaling.. Functions.. Default arguments.. Named arguments.. Rest arguments.. Mathematical functions.. Arrays.. Slices.. Casts.. Import.. Static.. Base ..1659 Command-line Interactive Graphical User GUI installation.. GUI usage..17312 Command-Line Language server DescriptionAsymptoteis a powerful descriptive Vector Graphics Language that provides a mathematicalcoordinate-based framework for technical drawing. Labels and equations are typeset withLaTeX, for overall document consistency, yielding the same high-quality level of typesettingthatLaTeXprovides for scientific text. By default it producesPostScriptoutput, but itcan also generateOpenGL,PDF,SVG,WebGL,V3D, andPRCvector Graphics , along with anyformat that theImageMagickpackage can produce. You can even try it out in your Webbrowser without installing it, using theAsymptote Web is also possible to send remote commands to this server via the curl utility (seeChapter 12 [Command-Line Interface], page 174).

3 A major advantage ofAsymptoteover other Graphics packages is that it is a high-levelprogramming Language , as opposed to just a Graphics program: it can therefore exploit thebest features of the script (command-driven) and graphical-user-interface (GUI) methodsfor producing figures. The rudimentaryGUIxasyincluded with the package allows oneto move script-generated objects around. To makeAsymptoteaccessible to the averageuser, thisGUIis currently being developed into a full-fledged interface that can generateobjects directly. However, the script portion of the Language is now ready for general use byusers who are willing to learn a few simpleAsymptotegraphics commands (seeChapter 4[Drawing commands], page 14).Asymptoteis mathematically oriented ( one can use complex multiplication to rotatea Vector ) and usesLaTeXto do the typesetting of labels. This is an important feature forscientific applications. It was inspired by an earlier drawing program (with a weaker syntaxand capabilities) Graphics Language provides: a standard for typesetting mathematical figures, just as TEX/LaTeXis the de-factostandard for typesetting equations.

4 LaTeXtypesetting of labels, for overall document consistency; the ability to generate and embed 3D vectorWebGLgraphics withinHTML files; the ability to generate and embed 3D vectorPRCgraphics withinPDFfiles; a natural coordinate-based framework for technical drawing, inspired byMetaPost,with a much cleaner, powerful C++-like programming syntax; compilation of figures into virtual machine code for speed, without sacrificing portabil-ity; the power of a script-based Language coupled to the convenience of aGUI; customization using its own C++-like Graphics programming Language ; sensible defaults for graphical features, with the ability to override; a high-level mathematically oriented interface to thePostScriptlanguage for vectorgraphics, including affine transforms and complex variables; functions that can create new (anonymous) functions; deferred drawing that uses the simplex method to solve overall size constraint issuesbetween fixed-sized objects (labels and arrowheads) and objects that should scale withfigure size;Chapter 1: Description2 Many of the features ofAsymptoteare written in theAsymptotelanguage itself.

5 Whilethe stock version ofAsymptoteis designed for mathematics typesetting needs, one can writeAsymptotemodules that tailor it to specific applications; for example, a scientific graphingmodule is available (seeSection [graph], page 98). Examples ofAsymptotecode andoutput, including animations, are available on an example file name in this manual, likePythagoras, will display thePDFoutput, whereas clicking on will show the correspondingAsymptotecodein a separate to many external resources, including an excellent user-writtenAsymptotetutorialcan be found quick reference card forAsymptoteis available InstallationAfter following the instructions for your specific distribution, please see alsoSection [Configuring], page recommend subscribing to new release announcements may also wish to monitor theAsymptoteforum: UNIX binary distributionsWe release bothtgzandRPMbinary distributions ofAsymptote. The root user can installtheLinux x86_64 tgzdistribution of the commands:tar -C / -zxf , which installs LaTeX style files, is optional.

6 The executablefile will be/usr/local/bin/asy) and example code will be installed by default in/usr/local/share/doc/ users can easily install a recent version ofAsymptotewith the commanddnf --enablerepo=rawhide install asymptoteTo install the latest version ofAsymptoteon a Debian-based distribution ( Ubuntu,Mepis, Linspire) follow the instructions for compiling fromUNIX source (seeSection [Compiling from UNIX source], page 6). Alternatively, Debian users can install one ofHubert Chan s prebuiltAsymptotebinaries MacOS X binary distributionsMacOS Xusers can either compile theUNIX source code (seeSection [Compiling fromUNIX source], page 6) or install theAsymptotebinary available that manyMacOS X(and FreeBSD) systems lack theGNUreadlinelibrary. For fullinteractive functionality,GNUreadlineversion or later must be Microsoft WindowsUsers of theMicrosoft Windowsoperating system can install the , the latest working TEX implementation (we ) will be required to typeset labels.

7 You will also need to in-stallGPL Ghostscriptversion or later 2: Installation4To viewPostScriptoutput, you can install the programSumatra PDFavailable required to support output formats other thanHTML,PDF,SVG, andPNG(see[convert],page 169). ThePython 3interpreter only required if youwish to try out the graphical user interface (seeChapter 11 [GUI], page 173).Example code will be installed by default in theexamplessubdirectory of the installationdirectory (by default,C:\Program Files\ asymptote ). ConfiguringIn interactive mode, or when given the-Voption (the default when runningAsymptoteona single file underMSDOS),Asymptotewill automatically invoke thePostScriptviewergv(underUNIX) orgsview(underMSDOSto display graphical output. ThePostScriptviewershould be capable of automatically redrawing whenever the output file is updated. ThedefaultUNIX PostScriptviewergvsupports this (via aSIGHUP signal). later ( ) is required for interactive mode to workproperly.)

8 Users ofggvwill need to enableWatch fileunderEdit/PostScript ViewerPreferences. Users ofgsviewwill need to enableOptions/Auto Redisplay(however, un-derMSDOSit is still necessary to click on thegsviewwindow; underUNIXone must manuallyredisplay by pressing therkey).Configuration variables are most easily set asAsymptotevariables in an optional con-figuration [configuration file], page 168). For example, the settingpdfviewerspecifies the location of thePDFviewer. Here are the default values of severalimportant configuration variables underUNIX:import settings;pdfviewer="acroread";htmlviewer ="google-chrome";psviewer="gv";display=" display";animate="animate";gs="gs";libgs ="";UnderMSDOS, the viewer settingshtmlviewer,pdfviewer,psviewer,di splay, andanimatedefault to the stringcmd, requesting the application normally associated witheach file type. The (installation-dependent) default values ofgsandlibgsare determinedautomatically from theMicrosoft Windowsregistry.

9 Thegssetting specifies the locationof thePostScriptprocessorGhostscript, available configuration variablehtmlviewerspecifies the browser to use to display 3 DWebGLout-put. The default setting isgoogle-chromeunderUNIX andcmdunderMicrosoft thatInternet Explorerdoes not supportWebGL;Microsoft Windowsusers shouldset their default html browser tochromeormicrosoft-edge. By default, 2D and 3 DHTML images expand to the enclosing canvas; this can be disabled by setting the 2: Installation5 OnUNIX systems, to support automatic document reloading ofPDFfiles inAdobe Reader,we recommend copying the theAsymptotesystem directory (by default,/usr/local/share/asymptoteunderU NIXto~/.adobe/ , the appropriateAdobe Readerversion automaticdocument reload feature must then be explicitly enabled by puttingimport settings;pdfreload=true;pdfreloadOptions ="-tempFile";in theAsymptoteconfiguration file. This reload feature is not useful underMSDOS since thedocument cannot be updated anyway on that operating system until it is first closed byAdobe configuration variabledircan be used to adjust the search path (seeSection [Search paths], page 6).)

10 By default,Asymptoteattempts to center the figure on the page, assuming that the papertype isletter. The default paper type may be changed toa4with the configuration variablepapertype. Alignment to other paper sizes can be obtained by setting the additional configuration variables normally do not require adjustment:configtexpathtexcommanddvipsd visvgmconvertasyglWarnings (such as"unbounded"and"offaxis") may be enabled or disabled with thefunctionswarn(string s);nowarn(string s);or by directly modifying the string , which lists all disabled variables may also be set or overwritten with a command-line option:asy -psviewer=gsview -V vennAlternatively, system environment versions of the above configuration variables may beset in the conventional way. The corresponding environment variable name is obtained byconverting the configuration variable name to upper case and prependingASYMPTOTE_: forexample, to set the environment variableASYMPTOTE_PSVIEWER="C:\Program Files\Ghostgum\gsview\ ";underMicrosoft Windows XP:1.