9 Command-line options

Type asy -h to see the full list of command-line options supported by Asymptote:

Usage: ../asy [options] [file ...]

Options (negate by replacing - with -no): 

-V,-View               View output; command-line only
-a,-align C|B|T|Z      Center, Bottom, Top, or Zero page alignment [C]
-antialias n           Antialiasing width for rasterized output [2]
-arcballradius pixels  Arcball radius [750]
-auto3D                Automatically activate 3D scene [true]
-autobillboard         3D labels always face viewer by default [true]
-autoimport string     Module to automatically import
-autoplain             Enable automatic importing of plain [true]
-autoplay              Autoplay 3D animations [false]
-autorotate            Enable automatic PDF page rotation [false]
-axes3                 Show 3D axes in PDF output [true]
-batchMask             Mask fpu exceptions in batch mode [false]
-batchView             View output in batch mode [false]
-bw                    Convert all colors to black and white [false]
-cd directory          Set current directory; command-line only
-cmyk                  Convert rgb colors to cmyk [false]
-c,-command string     Command to autoexecute
-compact               Conserve memory at the expense of speed [false]
-d,-debug              Enable debugging messages [false]
-divisor n             Garbage collect using purge(divisor=n) [2]
-doubleclick ms        Emulated double-click timeout [200]
-embed                 Embed rendered preview image [true]
-exitonEOF             Exit interactive mode on EOF [true]
-fitscreen             Fit rendered image to screen [true]
-framedelay ms         Additional frame delay [0]
-framerate frames/s    Animation speed [30]
-globalwrite           Allow write to other directory [false]
-gray                  Convert all colors to grayscale [false]
-h,-help               Show summary of options; command-line only
-historylines n        Retain n lines of history [1000]
-iconify               Iconify rendering window [false]
-inlineimage           Generate inline embedded image [false]
-inlinetex             Generate inline TeX code [false]
-interactiveMask       Mask fpu exceptions in interactive mode [true]
-interactiveView       View output in interactive mode [true]
-interactiveWrite      Write expressions entered at the prompt to stdout [true]
-k,-keep               Keep intermediate files [false]
-keepaux               Keep intermediate LaTeX .aux files [false]
-level n               Postscript level [3]
-l,-listvariables      List available global functions and variables [false]
-localhistory          Use a local interactive history file [false]
-loop                  Loop 3D animations [false]
-m,-mask               Mask fpu exceptions; command-line only
-maxtile pair          Maximum rendering tile size [(1024,768)]
-maxviewport pair      Maximum viewport size [(2048,2048)]
-multiline             Input code over multiple lines at the prompt [false]
-multipleView          View output from multiple batch-mode files [false]
-multisample n         Multisampling width for screen images [4]
-offscreen             Use offscreen rendering [false]
-O,-offset pair        PostScript offset [(0,0)]
-f,-outformat format   Convert each output file to specified format
-o,-outname name       Alternative output directory/filename
-p,-parseonly          Parse file [false]
-pdfreload             Automatically reload document in pdfviewer [false]
-pdfreloaddelay usec   Delay before attempting initial pdf reload [750000]
-position pair         Initial 3D rendering screen position [(0,0)]
-prc                   Embed 3D PRC graphics in PDF output [true]
-prompt string         Prompt [> ]
-prompt2 string        Continuation prompt for multiline input  [..]
-q,-quiet              Suppress welcome message [false]
-render n              Render 3D graphics using n pixels per bp (-1=auto) [-1]
-resizestep step       Resize step [1.2]
-reverse               reverse 3D animations [false]
-rgb                   Convert cmyk colors to rgb [false]
-safe                  Disable system call [true]
-scroll n              Scroll standard output n lines at a time [0]
-spinstep deg/s        Spin speed [60]
-svgemulation          Emulate unimplemented SVG shading [false]
-tabcompletion         Interactive prompt auto-completion [true]
-tex engine            latex|pdflatex|xelatex|lualatex|tex|pdftex|luatex|context|none [latex]
-thick                 Render thick 3D lines [true]
-thin                  Render thin 3D lines [true]
-threads               Use POSIX threads for 3D rendering [true]
-toolbar               Show 3D toolbar in PDF output [true]
-s,-translate          Show translated virtual machine code [false]
-twice                 Run LaTeX twice (to resolve references) [false]
-twosided              Use two-sided 3D lighting model for rendering [true]
-u,-user string        General purpose user string
-v,-verbose            Increase verbosity level (can specify multiple times) [0]
-version               Show version; command-line only
-wait                  Wait for child processes to finish before exiting [false]
-warn string           Enable warning; command-line only
-where                 Show where listed variables are declared [false]
-zoomfactor factor     Zoom step factor [1.05]
-zoomstep step         Mouse motion zoom step [0.1]

All boolean options can be negated by prepending no to the option name.

If no arguments are given, Asymptote runs in interactive mode (see section Interactive mode). In this case, the default output file is out.eps.

If - is given as the file argument, Asymptote reads from standard input.

If multiple files are specified, they are treated as separate Asymptote runs.

If the string autoimport is nonempty, a module with this name is automatically imported for each run as the final step in loading module plain.

Default option values may be entered as Asymptote code in a configuration file named config.asy (or the file specified by the environment variable ASYMPTOTE_CONFIG or -config option). Asymptote will look for this file in its usual search path (see section Search paths). Typically the configuration file is placed in the .asy directory in the user’s home directory (%USERPROFILE%\.asy under MSDOS). Configuration variables are accessed using the long form of the option names:

import settings;
outformat="pdf";
batchView=false;
interactiveView=true;
batchMask=false;
interactiveMask=true;

Command-line options override these defaults. Most configuration variables may also be changed at runtime. The advanced configuration variables dvipsOptions, hyperrefOptions, convertOptions, gsOptions, psviewerOptions, pdfviewerOptions, pdfreloadOptions, glOptions, and dvisvgmOptions allow specialized options to be passed as a string to the respective applications or libraries. The default value of hyperrefOptions is setpagesize=false,unicode,pdfborder=0 0 0.

If you insert

import plain;
settings.autoplain=true;

at the beginning of the configuration file, it can contain arbitrary Asymptote code.

The default output format is EPS for the (default) latex and tex tex engine and PDF for the pdflatex, xelatex, context, luatex, and lualatex tex engines. Alternative output formats may be produced using the -f option (or outformat setting).

To produce SVG output, you will need dvisvgm (version 0.8.7 or later) from http://dvisvgm.sourceforge.net and must use the latex or tex tex engine. You might need to adjust the configuration variable libgs to point to the location of your Ghostscript library libgs.so (or to an empty string, depending on how dvisvgm was configured).

Asymptote can also produce any output format supported by the ImageMagick convert program (version 6.3.5 or later recommended; an Invalid Parameter error message indicates that the MSDOS utility convert is being used instead of the one that comes with ImageMagick). The optional setting -render n requests an output resolution of n pixels per bp. Antialiasing is controlled by the parameter antialias, which by default specifies a sampling width of 2 pixels. To give other options to convert, use the convertOptions setting or call convert manually. This example emulates how Asymptote produces antialiased tiff output at one pixel per bp:

asy -o - venn | convert -alpha Off -density 144x144 -geometry 50%x eps:- venn.tiff

If the option -nosafe is given, Asymptote runs in unsafe mode. This enables the int system(string s) and int system(string[] s) calls, allowing one to execute arbitrary shell commands. The default mode, -safe, disables this call.

A PostScript offset may be specified as a pair (in bp units) with the -O option:

asy -O 0,0 file

The default offset is zero. The default value of the page alignment setting align is Center.

The -c (command) option may be used to execute arbitrary Asymptote code on the command line as a string. It is not necessary to terminate the string with a semicolon. Multiple -c options are executed in the order they are given. For example

asy -c 2+2 -c "sin(1)" -c "size(100); draw(unitsquare)"

produces the output

4
0.841470984807897

and draws a unitsquare of size 100.

The -u (user) option may be used to specify arbitrary Asymptote settings on the command line as a string. It is not necessary to terminate the string with a semicolon. Multiple -u options are executed in the order they are given. Command-line code like -u x=sqrt(2) can be executed within a module like this:

real x;
usersetting();
write(x);

When the -l (listvariables) option is used with file arguments, only global functions and variables defined in the specified file(s) are listed.

Additional debugging output is produced with each additional -v option:

-v: Display top-level module and final output file names.
-vv: Also display imported and included module names and final LaTeX and dvips processing information.
-vvv: Also output LaTeX bidirectional pipe diagnostics.
-vvvv: Also output knot guide solver diagnostics.
-vvvvv: Also output Asymptote traceback diagnostics.

This document was generated on May 24, 2014 using texi2html 5.0.