asymptote: Options
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]
-aligndir pair Directional page alignment (overrides align) [(0,0)]
-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 text and noninteractive stdout [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
(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 (
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 1.5.3 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 pair 'aligndir' specifies an optional
direction on the boundary of the page (mapped to the rectangle
[-1,1]\times[-1,1]) to which the picture should be aligned; the default
value '(0,0)' species center alignment.
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.