8. 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 [Center]
-antialias n          Antialiasing width for rasterized output [2]
-autoimport string    Module to automatically import
-autoplain            Enable automatic importing of plain [true]
-autorotate           Enable automatic PDF page rotation [false]
-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            Free space divisor for garbage collection [2]
-embed                Embed rendered preview image [true]
-exitonEOF            Exit interactive mode on EOF [true]
-fitscreen            Fit rendered image to screen [true]
-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]
-m,-mask              Mask fpu exceptions; command-line only
-maxtile pair         Maximum rendering tile size [(0,0)]
-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]
-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  [..]
-render n             Render 3D graphics using n pixels per bp (-1=auto) [-1]
-rgb                  Convert cmyk colors to rgb [false]
-safe                 Disable system call [true]
-scroll n             Scroll standard output n lines at a time [0]
-tabcompletion        Interactive prompt auto-completion [true]
-tex engine           TeX engine ("latex|pdflatex|tex|pdftex|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 [0]
-version              Show version; command-line only
-wait                 Wait for child processes to finish before exiting [false]
-where                Show where listed variables are declared [false]
-xformat format       GUI deconstruction format [png]

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. 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, convertOptions, gsOptions, psviewerOptions, pdfviewerOptions, and glOptions allow specialized options to be passed as a string to the respective applications or libraries.

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 tex engine and PDF for the pdflatex tex engine. Alternative output formats may be produced using the -f option (or outformat setting). 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. Asymptote can 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). To give specific 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) call, 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]