Asymptote: Advanced Configuration

Asymptote (Vector Graphics Language)

Getting Started - Basics - Drawing - Labeling - Filling - Useful functions - Examples - Macros and Packages Help - Reference - Advanced Asymptote - 3D Graphics - CSE5 Package - How to

There are two things that Asymptote users commonly would like to do with their figures: make the images output in a different format, and include Asymptote code directly into LaTeX files.

PDF format and beyond

Asymptote can easily make your images in pdf format rather than eps format, with the help of a program called GhostScript.

GhostScript

To download and install GhostScript:

1. Go to [sourceforge.net/projects/ghostscript] and click Download GhostScript. This should bring you to a box containing several formats of the latest release. Click on the link to download GPL Ghostscript, and the next page should have an option to download an file ending in .exe (for version 8.54, the file is gs854w32-gpl.exe).
2. Click on the link for the .exe file, and a download window will pop up in your browser. Choose to save the file, and take note of where on your hard drive you saved it to. Let's say you saved it to the folder D:\downloads\Ghostscript.
3. When the download is complete, browse to D:\downloads\Ghostscript in your files and double-click on the .exe file (gs854w32-gpl.exe). This will bring you to an installation window. Click Setup.
4. After the installer extracts the required files, you will see a new window with the option to change the installation folder (the default will be C:\Program Files\gs) and an option to select the folder in the start menu to which a shortcut will be added. It is optional to change these, but be sure to remember your chosen location if you decide to install Ghostscript in a different directory. When you have finished, click Install.

PDF output configuration

Now that GhostScript is installed, you must configure Asymptote to see it. Open the file config.asy and add the following lines to the bottom:

gs="C:\Program Files\gs\gs8.54\bin\gswin32c.exe"; 
pdfviewer="C:\Program Files\Ghostgum\gsview\gsview32.exe";

(IMPORTANT: If you installed GhostScript or GSview to a different directory, or have a newer version, you must change the path names above so that they point Asymptote to the correct executable files. You can also use a more common pdf viewer such as Acrobat Reader for your pdfviewer; this may display some of your images better.)

Now, save the file config.asy, and open TeXnicCenter. Go to the Tools menu and click Customize, then go to the Tools tab. Click to modify your Asymptote tool that you made in the Basic Configuration section. Add the argument -f "pdf" to the Arguments line and change latex to pdflatex. Your Arguments block should now look like:

 -batchView -tex "pdflatex" -align C -f "pdf" %tc

Now if you open the file test.asy in TeXnicCenter again, which contains the code

draw((0,0)--(100,100));
draw((0,100)--(100,0));
dot((50,50));
label("P",(50,50),S);

and press Ctrl+A (or your corresponding hotkey), voila! You have made a pdf document with your image.

In order to make Asymptote output files in .jpg or other formats, you must use a program such as ImageMagick that is capable of converting .eps files to many other image formats. If you have ImageMagick installed (you can obtain it [here] and install it from the download), you can simply type at an MSDOS command prompt:

convert test.eps test.jpg

and the file test.jpg will be produced. See [the ImageMagick home page] for more information on converting images between file formats.

Using Asymptote in LaTeX

One of Asymptote's main advantages as a graphics language is its incredible compatibility with LaTeX.  Once you have it configured correctly, you can simply type a \begin{asy} ... \end{asy} block in a figure environment in your LaTeX file, and an image will be produced in your document! 

First you need to get LaTeX to see Asymptote. In order to do this, you must add the packages asymptote.sty, asycolors.sty, and pdfanim_temp.sty to your LaTeX package directory (these can be found in your Asymptote directory, default being C:\Program Files\Asymptote). For example, if you are using MikTeX (recommended) and MikTeX is installed to C:\Program Files on your computer, you can use the following steps to get MikTeX to see Asymptote:

1. Browse to the folder C:\Program Files\texmf\tex\latex\.
2. Here, create a new folder and call it asymptote.
3. Open your new folder, and now copy the three files asymptote.sty, asycolors.sty, and pdfanim_temp.sty from C:\Program Files\Asymptote and paste them into this new asymptote folder.
4. Open MikTeX Options. This is most likely a shortcut in your Start Menu along with MikTeX; if it is not here, go to C:\Program Files\texmf\miktex\bin and click on mo.exe.
5. In the General tab, you will see a section labeled File Name Database with a button that says Refresh Now. Click it to refresh your file name database. MikTeX should now see your Asymptote style files.

Now, you should be ready to include your figures in your LaTeX document. Create a test file called example.tex, and copy-and-paste the following code into the document:

\documentclass{article}
\usepackage[pdftex]{graphicx}
\usepackage{asymptote}
\begin{document}
Hello.  I like to make pictures with Asymptote like this one:
\begin{figure}[h]
 \begin{asy}
  include graph;
  size(1inch);
  filldraw(Circle((0,0),1),yellow,black);
  fill(Circle((-.3,.4),.1),black);
  fill(Circle((.3,.4),.1),black);
  draw(Arc((0,0),.5,-140,-40));
\end{asy}
\end{figure}
\par It makes me happy, since I can still type my normal LaTeX stuff around it: 
\(\displaystyle\int_0^{\pi}{\sin{x}}dx=2\)
\end{document}

Notice that the \end{asy} line is justified all the way to the left, on a line by itself. This is VERY IMPORTANT for the asymptote.sty package to find the end of the Asymptote code; there can be no whitespaces or other characters on the line containing \end{asy}.

You are not quite done yet - LaTeX will not output the image the first time it compiles the document. To compile this file, you must:

1. Pass it once through LaTeX without viewing the output (click Build in TeXnicCenter; this extracts your asy code into a .asy file.)
2. Run Asymptote on the new file example.asy (pressing Ctrl+A as normal in TeXnicCenter will work, since it only looks at the title example.)
3. Finally, run it again through LaTeX (click Build and View Current File in TeXnicCenter). Your output should look like:

---

Hello. I like to make pictures with Asymptote like this one:

It makes me happy, since I can still type my normal LaTeX stuff around it:

---

If you do not want to have to go through all 3 steps above every time you want to compile your LaTeX document, you have several options: (1) You can create your Asymptote files separately in eps format, and include them into your LaTeX document with the \includegraphics command. (2) You can create a DOS batch file to run the three commands in order, and call this batch file using a TeXnicCenter tool on your current file. The advantage of the former is that your LaTeX document will take less time to compile since the images are already made, and the advantage of the latter is the clean, readable format of the \begin{asy} ... \end{asy} blocks in your code. This guide does not provide detail on implementing such methods. See [here] for a good reference on DOS batch files and Windows batch commands.