This is asymptote.info, produced by makeinfo version 4.13 from
../asymptote.texi.
This file documents `Asymptote', version 1.76.
`http://asymptote.sourceforge.net'
Copyright (C) 2004-9 Andy Hammerlindl, John Bowman, and Tom Prince.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Lesser General Public License
(see the file LICENSE in the top-level source directory).
INFO-DIR-SECTION Languages
START-INFO-DIR-ENTRY
* asymptote: (asymptote). Vector graphics language.
END-INFO-DIR-ENTRY
File: asymptote.info, Node: Top, Next: Description, Up: (dir)
Asymptote
*********
This file documents `Asymptote', version 1.76.
`http://asymptote.sourceforge.net'
Copyright (C) 2004-9 Andy Hammerlindl, John Bowman, and Tom Prince.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Lesser General Public License
(see the file LICENSE in the top-level source directory).
* Menu:
* Description:: What is `Asymptote'?
* Installation:: Downloading and installing
* Tutorial:: Getting started
* Drawing commands:: Four primitive graphics commands
* Programming:: The `Asymptote' vector graphics language
* LaTeX usage:: Embedding `Asymptote' commands within `LaTeX'
* Base modules:: Base modules shipped with `Asymptote'
* Options:: Command-line options
* Interactive mode:: Typing `Asymptote' commands interactively
* GUI:: Graphical user interface
* PostScript to Asymptote:: `Asymptote' backend to `pstoedit'
* Help:: Where to get help and submit bug reports
* Debugger:: Squish those bugs!
* Credits:: Contributions and acknowledgments
* Index:: General index
--- The Detailed Node Listing ---
Installation
* UNIX binary distributions:: Prebuilt `UNIX' binaries
* MacOS X binary distributions:: Prebuilt `MacOS X' binaries
* Microsoft Windows:: Prebuilt `Microsoft Windows' binary
* Configuring:: Configuring `Asymptote' for your system
* Search paths:: Where `Asymptote' looks for your files
* Compiling from UNIX source:: Building `Asymptote' from scratch
* Editing modes:: Convenient `emacs' and `vim' modes
* Subversion:: Getting the latest development source
* Uninstall:: Goodbye, `Asymptote'!
Drawing commands
* draw:: Draw a path on a picture or frame
* fill:: Fill a cyclic path on a picture or frame
* clip:: Clip a picture or frame to a cyclic path
* label:: Label a point on a picture
Programming
* Data types:: void, bool, int, real, pair, triple, string
* Paths and guides::
* Pens:: Colors, line types, line widths, font sizes
* Transforms:: Affine transforms
* Frames and pictures:: Canvases for immediate and deferred drawing
* Files:: Reading and writing your data
* Variable initializers:: Initialize your variables
* Structures:: Organize your data
* Operators:: Arithmetic and logical operators
* Implicit scaling:: Avoiding those ugly *s
* Functions:: Traditional and high-order functions
* Arrays:: Dynamic vectors
* Casts:: Implicit and explicit casts
* Import:: Importing external `Asymptote' packages
* Static:: Where to allocate your variable?
Operators
* Arithmetic & logical:: Basic mathematical operators
* Self & prefix operators:: Increment and decrement
* User-defined operators:: Overloading operators
Functions
* Default arguments:: Default values can appear anywhere
* Named arguments:: Assigning function arguments by keyword
* Rest arguments:: Functions with a variable number of arguments
* Mathematical functions:: Standard libm functions
Arrays
* Slices:: Python-style array slices
Base modules
* plain:: Default `Asymptote' base file
* simplex:: Linear programming: simplex method
* math:: Extend `Asymptote''s math capabilities
* interpolate:: Interpolation routines
* geometry:: Geometry routines
* trembling:: Wavy lines
* stats:: Statistics routines and histograms
* patterns:: Custom fill and draw patterns
* markers:: Custom path marker routines
* tree:: Dynamic binary search tree
* binarytree:: Binary tree drawing module
* drawtree:: Tree drawing module
* syzygy:: Syzygy and braid drawing module
* feynman:: Feynman diagrams
* roundedpath:: Round the sharp corners of paths
* animation:: Embedded PDF and MPEG movies
* embed:: Embedding movies, sounds, and 3D objects
* slide:: Making presentations with `Asymptote'
* MetaPost:: `MetaPost' compatibility routines
* unicode:: Accept `unicode' (UTF-8) characters
* latin1:: Accept `ISO 8859-1' characters
* babel:: Interface to `LaTeX' `babel' package
* labelpath:: Drawing curved labels
* labelpath3:: Drawing curved labels in 3D
* annotate:: Annotate your PDF files
* CAD:: 2D CAD pen and measurement functions (DIN 15)
* graph:: 2D linear & logarithmic graphs
* palette:: Color density images and palettes
* three:: 3D vector graphics
* obj:: 3D obj files
* graph3:: 3D linear & logarithmic graphs
* grid3:: 3D grids
* solids:: 3D solid geometry
* tube:: 3D rotation minimizing tubes
* flowchart:: Flowchart drawing routines
* contour:: Contour lines
* contour3:: Contour surfaces
* slopefield:: Slope fields
Graphical User Interface
* GUI Installation:: Installing `xasy'
* GUI Usage::
File: asymptote.info, Node: Description, Next: Installation, Prev: Top, Up: Top
1 Description
*************
`Asymptote' is a powerful descriptive vector graphics language that
provides a mathematical coordinate-based framework for technical
drawings. Labels and equations are typeset with `LaTeX', for overall
document consistency, yielding the same high-quality level of
typesetting that `LaTeX' provides for scientific text. By default it
produces `PostScript' output, but it can also generate any format that
the `ImageMagick' package can produce.
A major advantage of `Asymptote' over other graphics packages is
that it is a high-level programming language, as opposed to just a
graphics program: it can therefore exploit the best features of the
script (command-driven) and graphical-user-interface (GUI) methods for
producing figures. The rudimentary GUI `xasy' included with the package
allows one to move script-generated objects around. To make `Asymptote'
accessible to the average user, this GUI is currently being developed
into a full-fledged interface that can generate objects directly.
However, the script portion of the language is now ready for general
use by users who are willing to learn a few simple `Asymptote' graphics
commands (*note Drawing commands::).
`Asymptote' is mathematically oriented (e.g. one can use complex
multiplication to rotate a vector) and uses `LaTeX' to do the
typesetting of labels. This is an important feature for scientific
applications. It was inspired by an earlier drawing program (with a
weaker syntax and capabilities) called `MetaPost'.
The `Asymptote' vector graphics language provides:
* a standard for typesetting mathematical figures, just as
TeX/`LaTeX' is the de-facto standard for typesetting equations.
* `LaTeX' typesetting of labels, for overall document consistency;
* a natural coordinate-based framework for technical drawings,
inspired by `MetaPost', with a much cleaner, powerful C++-like
programming syntax;
* compilation of figures into virtual machine code for speed, without
sacrificing portability;
* the power of a script-based language coupled to the convenience of
a GUI;
* 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 the `PostScript'
language for vector graphics, 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 issues between fixed-sized objects (labels and
arrowheads) and objects that should scale with figure size;
Many of the features of `Asymptote' are written in the `Asymptote'
language itself. While the stock version of `Asymptote' is designed for
mathematics typesetting needs, one can write `Asymptote' modules that
tailor it to specific applications. A scientific graphing module has
already been written (*note graph::). Examples of `Asymptote' code and
output, including animations, are available at
`http://asymptote.sourceforge.net/gallery/'.
Links to many external resources, including an excellent user-written
`Asymptote' tutorial can be found at
`http://asymptote.sourceforge.net/links.html'.
File: asymptote.info, Node: Installation, Next: Tutorial, Prev: Description, Up: Top
2 Installation
**************
* Menu:
* UNIX binary distributions:: Prebuilt `UNIX' binaries
* MacOS X binary distributions:: Prebuilt `MacOS X' binaries
* Microsoft Windows:: Prebuilt `Microsoft Windows' binary
* Configuring:: Configuring `Asymptote' for your system
* Search paths:: Where `Asymptote' looks for your files
* Compiling from UNIX source:: Building `Asymptote' from scratch
* Editing modes:: Convenient `emacs' and `vim' modes
* Subversion:: Getting the latest development source
* Uninstall:: Goodbye, `Asymptote'!
After following the instructions for your specific distribution,
please see also *note Configuring::.
We recommend subscribing to new release announcements at
`http://freshmeat.net/projects/asy'
Users may also wish to monitor the `Asymptote' forum:
`http://sourceforge.net/forum/monitor.php?forum_id=409349'
File: asymptote.info, Node: UNIX binary distributions, Next: MacOS X binary distributions, Up: Installation
2.1 UNIX binary distributions
=============================
We release both `tgz' and RPM binary distributions of `Asymptote'. The
root user can install the `Linux i386' `tgz' distribution of version
`x.xx' of `Asymptote' with the commands:
tar -C / -zxf asymptote-x.xx.i386.tgz
texhash
The `texhash' command, which installs LaTeX style files, is optional.
The executable file will be `/usr/local/bin/asy') and example code will
be installed by default in `/usr/local/share/doc/asymptote/examples'.
Fedora users can easily install the most recent version of `Asymptote'
with the command
yum --enablerepo=rawhide install asymptote
To install the latest version of `Asymptote' on a Debian-based
distribution (e.g. Ubuntu, Mepis, Linspire) follow the instructions for
compiling from `UNIX' source (*note Compiling from UNIX source::).
Alternatively, Debian users can install one of Hubert Chan's prebuilt
`Asymptote' binaries from
`http://ftp.debian.org/debian/pool/main/a/asymptote'
File: asymptote.info, Node: MacOS X binary distributions, Next: Microsoft Windows, Prev: UNIX binary distributions, Up: Installation
2.2 MacOS X binary distributions
================================
`MacOS X' users can either compile the `UNIX' source code (*note
Compiling from UNIX source::) or install the contributed `Asymptote'
binary available at
`http://www.hmug.org/pub/MacOS_X/X/Applications/Publishing/asymptote/'
Because these preconfigured binary distributions have strict
architecture and library dependencies that many installations do not
satisfy, we recommend installing `Asymptote' directly from the official
source:
`http://sourceforge.net/project/showfiles.php?group_id=120000'
Note that many `MacOS X' (and FreeBSD) systems inexplicably ship with
an extremely old GNU `readline' version (4.1, dated 21 March 2000). For
full interactive functionality, `readline' version 4.2 or later (16
April 2001) is required.
File: asymptote.info, Node: Microsoft Windows, Next: Configuring, Prev: MacOS X binary distributions, Up: Installation
2.3 Microsoft Windows
=====================
Users of the `Microsoft Windows' operating system can install the
self-extracting `Asymptote' executable `asymptote-x.xx-setup.exe',
where `x.xx' denotes the latest version.
A working TeX implementation (such as the one available at
`http://www.miktex.org') will be required to typeset labels. You will
also need to install `GPL Ghostscript' from
`http://sourceforge.net/projects/ghostscript/'. To view the default
`PostScript' output, you can install the program `gsview' available from
`http://www.cs.wisc.edu/~ghost/gsview/'.
The `ImageMagick' package from
`http://www.imagemagick.org/script/binary-releases.php'
is required to support output formats other than EPS and PDF (*note
convert::). The `Python' interpreter from `http://www.python.org' is
only required if you wish to try out the graphical user interface
(*note GUI::).
Example code will be installed by default in the `examples'
subdirectory of the installation directory (by default, `C:\Program
Files\Asymptote').
File: asymptote.info, Node: Configuring, Next: Search paths, Prev: Microsoft Windows, Up: Installation
2.4 Configuring
===============
In interactive mode, or when given the `-V' option (the default when
running `Asymptote' on a single file under `MSDOS'), `Asymptote' will
automatically invoke the `PostScript' viewer `gv' (under `UNIX') or
`gsview' (under `MSDOS' to display graphical output. These defaults may
be overridden with the configuration variable `psviewer'. The
`PostScript' viewer should be capable of automatically redrawing
whenever the output file is updated. The default `UNIX' `PostScript'
viewer `gv' supports this (via a `SIGHUP' signal). Version `gv-3.6.3'
or later (from `http://ftp.gnu.org/gnu/gv/') is required for
interactive mode to work properly. Users of `ggv' will need to enable
`Watch file' under `Edit/Postscript Viewer Preferences'. Users of
`gsview' will need to enable `Options/Auto Redisplay' (however, under
`MSDOS' it is still necessary to click on the `gsview' window; under
`UNIX' one must manually redisplay by pressing the `r' key).
Configuration variables are most easily set as `Asymptote' variables
in the configuration file (by default, `.asy/config.asy' in the user's
home directory or `%USERPROFILE%\.asy\config.asy' under `MSDOS'); *note
configuration file::. Here are the default values of several important
configuration variables under `UNIX':
import settings;
psviewer="gv";
pdfviewer="acroread";
gs="gs";
python="";
The (installation-dependent) default values of these configuration
variables under `MSDOS' are determined automatically from the
`Microsoft Windows' registry.
For PDF format output, the `gs' setting specifies the location of
the `PostScript'-to-PDF processor `Ghostscript', available from
`http://sourceforge.net/projects/ghostscript/'.
The setting `pdfviewer' specifies the location of the PDF viewer. On
`UNIX' systems, to support automatic document reloading in `Adobe
Reader', we recommend copying the file `reload.js' from the `Asymptote'
system directory (by default, `/usr/local/share/asymptote' under `UNIX'
to `~/.adobe/Acrobat/x.x/JavaScripts/', where `x.x' represents the
appropriate `Adobe Reader' version number. The automatic document
reload feature must then be explicitly enabled by putting
import settings;
pdfreload=true;
pdfreloadOptions="-tempFile";
in the `Asymptote' configuration file. This reload feature is not
useful under `MSDOS' since the document cannot be updated anyway on
that operating system until it is first closed by `Adobe Reader'.
The graphical user interface may also require setting the variable
`python' if `Python' is installed in a nonstandard location.
The configuration variable `dir' can be used to adjust the search
path (*note Search paths::).
By default, `Asymptote' attempts to center the figure on the page,
assuming that the paper type is `letter'. The default paper type may be
changed to `a4' with the configuration variable `papertype'. Alignment
to other paper sizes can be obtained by setting the configuration
variables `paperwidth' and `paperheight'.
The following configuration variables normally do not require
adjustment:
texpath
texcommand
texdvicommand
dvips
convert
display
animate
xasy
The `texdvicommand' is used for `3D' label typesetting, which requires
`dvips' output. An empty string indicates the default setting of
`latex'/`tex', depending on the setting of `texengine'.
Configuration variables may also be set or overwritten with a
command-line option:
asy -psviewer=gsview -V venn
Alternatively, system environment versions of the above configuration
variables may be set in the conventional way. The corresponding
environment variable name is obtained by converting the configuration
variable name to upper case and prepending `ASYMPTOTE_': for example,
to set the environment variable
ASYMPTOTE_PSVIEWER="C:\Program Files\Ghostgum\gsview\gsview32.exe";
under `Microsoft Windows XP':
1. Click on the `Start' button;
2. Right-click on `My Computer';
3. Choose `Properties' from the popup menu;
4. Click the `Advanced' tab;
5. Click the `Environment Variables' button.
File: asymptote.info, Node: Search paths, Next: Compiling from UNIX source, Prev: Configuring, Up: Installation
2.5 Search paths
================
In looking for `Asymptote' system files, `asy' will search the
following paths, in the order listed:
1. The current directory;
2. A list of one or more directories specified by the configuration
variable `dir' (separated by `:' under UNIX and `;' under `MSDOS');
3. The directory `.asy' in the user's home directory
(`%USERPROFILE%\.asy' under `MSDOS');
4. The `Asymptote' system directory (by default,
`/usr/local/share/asymptote' under `UNIX' and `C:\Program
Files\Asymptote' under `MSDOS').
File: asymptote.info, Node: Compiling from UNIX source, Next: Editing modes, Prev: Search paths, Up: Installation
2.6 Compiling from UNIX source
==============================
To compile and install a `UNIX' executable from a source release
`x.xx', first execute the commands:
gunzip asymptote-x.xx.src.tgz
tar -xf asymptote-x.xx.src.tar
cd asymptote-x.xx
By default the system version of the Boehm garbage collector will be
used; if it is old we recommend first putting
`http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gc-7.1.tar.gz'
in the `Asymptote' source directory.
If your graphics card supports multisampling, we recommend using SVN
revision 761 (or later) of `freeglut' to support antialiasing in
`Asymptote''s adaptive `OpenGL' 3D renderer (`MacOS X' users can skip
this step since `Asymptote' is configured to use the native glut
library on that platform). Download
`http://freeglut.svn.sourceforge.net/viewvc/freeglut/trunk/freeglut/freeglut.tar.gz'
and type (as the root user):
tar -zxf freeglut.tar.gz
cd freeglut
sh autogen.sh
./configure --prefix=/usr
make install
cd ..
Then compile `Asymptote' with the commands
./configure
make all
make install
Be sure to use GNU `make' (on non-GNU systems this command may be
called `gmake'). To build the documentation, you may need to install
the `texinfo-tex' package. If you get errors from a broken `texinfo' or
`pdftex' installation, simply put
`http://asymptote.sourceforge.net/asymptote.pdf'
in the directory `doc' and repeat the command `make all'.
For a (default) system-wide installation, the last command should be
done as the root user. To install without root privileges, change the
`./configure' command to
./configure --prefix=$HOME/asymptote
One can disable use of the Boehm garbage collector by configuring with
`./configure --disable-gc'. For a list of other configuration options,
say `./configure --help'. For example, one can tell configure to look
for header files and libraries in nonstandard locations:
./configure CFLAGS=-I/opt/usr/include LDFLAGS=-L/opt/usr/lib
If you are compiling `Asymptote' with `gcc', you will need a
relatively recent version (e.g. 3.4.4 or later). For full interactive
functionality, you will need version 4.2 or later of the GNU `readline'
library. The file `gcc3.3.2curses.patch' in the `patches' directory can
be used to patch the broken curses.h header file (or a local copy
thereof in the current directory) on some `AIX' and `IRIX' systems.
The `FFTW' library is only required if you want `Asymptote' to be
able to take Fourier transforms of data (say, to compute an audio power
spectrum). The `GSL' library is only required if you require the
special functions that it supports.
If you don't want to install `Asymptote' system wide, just make sure
the compiled binary `asy' and GUI script `xasy' are in your path and
set the configuration variable `dir' to point to the directory `base'
(in the top level directory of the `Asymptote' source code).
File: asymptote.info, Node: Editing modes, Next: Subversion, Prev: Compiling from UNIX source, Up: Installation
2.7 Editing modes
=================
Users of `emacs' can edit `Asymptote' code with the mode `asy-mode',
after enabling it by putting the following lines in their `.emacs'
initialization file, replacing `ASYDIR' with the location of the
`Asymptote' system directory (by default, `/usr/local/share/asymptote'
or `C:\Program Files\Asymptote' under `MSDOS'):
(add-to-list 'load-path "ASYDIR")
(autoload 'asy-mode "asy-mode.el" "Asymptote major mode." t)
(autoload 'lasy-mode "asy-mode.el" "hybrid Asymptote/Latex major mode." t)
(autoload 'asy-insinuate-latex "asy-mode.el" "Asymptote insinuate LaTeX." t)
(add-to-list 'auto-mode-alist '("\\.asy$" . asy-mode))
Particularly useful key bindings in this mode are `C-c C-c', which
compiles and displays the current buffer, and the key binding `C-c ?',
which shows the available function prototypes for the command at the
cursor. For full functionality you should also install the Apache
Software Foundation package `two-mode-mode':
`http://www.dedasys.com/freesoftware/files/two-mode-mode.el'
Once installed, you can use the hybrid mode `lasy-mode' to edit a
LaTeX file containing embedded `Asymptote' code (*note LaTeX usage::).
This mode can be enabled within `latex-mode' with the key sequence `M-x
lasy-mode <RET>'. On `UNIX' systems, additional keywords will be
generated from all `asy' files in the space-separated list of
directories specified by the environment variable `ASYMPTOTE_SITEDIR'.
Further documentation of `asy-mode' is available within `emacs' by
pressing the sequence keys `C-h f asy-mode <RET>'.
Fans of `vim' can customize `vim' for `Asymptote' with
`cp /usr/local/share/asymptote/asy.vim ~/.vim/syntax/asy.vim'
and add the following to their `~/.vimrc' file:
augroup filetypedetect
au BufNewFile,BufRead *.asy setf asy
augroup END
filetype plugin on
If any of these directories or files don't exist, just create them.
To set `vim' up to run the current asymptote script using `:make' just
add to `~/.vim/ftplugin/asy.vim':
setlocal makeprg=asy\ %
setlocal errorformat=%f:\ %l.%c:\ %m
File: asymptote.info, Node: Subversion, Next: Uninstall, Prev: Editing modes, Up: Installation
2.8 Subversion (SVN)
====================
The following commands are needed to install the latest development
version of `Asymptote' using Subversion:
svn co http://asymptote.svn.sourceforge.net/svnroot/asymptote/trunk/asymptote
cd asymptote
./autogen.sh
./configure
make all
make install
To compile without optimization, use the command `make CFLAGS=-g'.
File: asymptote.info, Node: Uninstall, Prev: Subversion, Up: Installation
2.9 Uninstall
=============
To uninstall an `Linux i386' binary distribution, use the commands
tar -zxvf asymptote-x.xx.i386.tgz | xargs --replace=% rm /%
texhash
To uninstall all `Asymptote' files installed from a source
distribution, use the command
make uninstall
File: asymptote.info, Node: Tutorial, Next: Drawing commands, Prev: Installation, Up: Top
3 Tutorial
**********
_An excellent user-written `Asymptote' tutorial is also available from_
`http://www.artofproblemsolving.com/Wiki/index.php/Asymptote:_Basics'
To draw a line from coordinate (0,0) to coordinate (100,100) using
`Asymptote''s interactive mode, type at the command prompt:
asy
draw((0,0)--(100,100));
|