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 on Windows:

1. Go to github.com/ArtifexSoftware/ghostpdl-downloads/releases and choose the version that fits your OS architecture (for 32-bit, choose gsNNNw32.exe; for 64-bit, gsNNNw64.exe, where NNN is version N.NN of Ghostscript).
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.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. When you have finished, click Install.

PDF output configuration

Although ghostview can be configured as the pdf viewer, we recommend using the default pdf viewer, Acrobat Reader.

Now 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 Interactive Mode section. In the Arguments line, put

 -batchView -tex "pdflatex" %tc-*.asy

Newer versions may require the following line

 -batchView -tex "pdflatex" %tc.asy

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 Alt+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 package asymptote.sty to your LaTeX package directory (this file can be found in your Asymptote directory, by default 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:

Note: This guide assumes you are using Windows Vista or later with MiKTeX 2.9 and GhostScript installed.

1. Browse to the folder C:\Program Files\MiKTeX 2.x\tex\latex\ (replace 2.x by the version on your machine).
2. Here, create a new folder and call it asymptote.
3. Open your new folder. For full functionality, copy the files asymptote.sty and asycolors.sty from C:\Program Files\Asymptote into this new asymptote folder.
4. Open Start Menu and search for MikTeX Options (Admin), then double-click to run. If you can't find the program there, go to C:\Program Files\MiKTeX 2.x\miktex\bin, navigate to the subfolder x64 or win32, and click on mo_admin.exe (replace 2.x with the version of MikTeX on your machine).
5. In the General tab, you will see a section labeled Maintenance with a button that says Refresh FNDB. 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 pics with Asymptote like this one:
\begin{figure}[h]
  \begin{asy}
    import 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: 
\(\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 Alt+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 pics 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.

Showing Asymptote error messages in TeXnicCenter

There are three methods:

(1) When running Asymptote from inside TexnicCenter, the DOS window closes too quickly to see any error messages. These messages may be crucial to correcting the code. TeXnicCenter can be persuaded to show the messages with a new tool, or, if you wish, overwriting the original Asymptote tool.

The following instructions assume that Asymptote and TeXnicCenter have been saved in the default directories C:\Program Files\Asymptote and C:\Program Files\TeXnicCenter; change them as necessary.

• In Notepad (or TeXnicCenter) create a new file called asymptote.bat and save it in C:\Program Files\Asymptote. Copy and paste the following into the file:

echo off 
echo Asymptote is working ... please wait 
"C:\Program Files\Asymptote\redir.exe" -e %1 "C:\progra~1\Asymptote\asy.exe" -batchView -tex "pdflatex" -align C -f "pdf" %2 
find /i ".asy" %3 >nul 
If errorlevel 1 goto end 
"C:\Program Files\TeXnicCenter\TEXCNTR.EXE" /ddecmd "[open('%3')]" 
:end

• Download [redir.zip], extract redir.exe, virus check it and save in C:\Program Files\Asymptote
• In TexnicCenter, Tools->Customise...->Tools put in either a new tool or change the current Asymptote tool:
  • Commands: "C:\Program Files\Asymptote\asymptote.bat"
  • Arguments: %tc_asy.log %tc "%dc\%tc_asy.log"
  • Initial directory: %dc

then press Close

Now when you run Asymptote on file.tex from inside TexnicCenter the error messages, if any, will be saved in file_asy.log. If there are any error messages then this file will open in TeXnicCenter showing you the messages. When you have eliminated all the errors nothing will show in TeXnicCenter.

(2) This method creates a new build environment so that you can compile .asy documents and have the messages sent through TeXnicCenter.

• Go to Build > Define Output Profiles...
• Click Add and name your new profile 'Asymptote'
• Your (La)TeX settings should be:
  • Run (La)TeX in this profile IS selected
  • Path to compiler should be wherever you asy.exe lives. Probably something like C:\Program Files (x86)\Asymptote\asy.exe
  • Command line arguments: -f "pdf" -vv -tex=pdflatex %pm
  • Do not use BibTeX or MakeIndex

(3) This method has more steps to implement, but is worth it. It is only applicable when you have Asymptote code inside the Asymptote Environment in LaTeX code. Simply implement the following steps to have it so that you can compile Asymptote images along with the LaTeX just by clicking 'Build.' It also displays error messages right on the TeXnicCenter output box. (It will appear at the very end.)

• Go to Build > Define Output Profiles... (or press Alt+F7).
• Select your current output profile (most likely it will be LaTeX => PDF).
• Click on 'Copy' at the bottom.
• Make the profile's name 'LaTeX => PDF(Asymptote)' (without the single quotes).
• Click on the 'Postprocessor' tab.
• Click on the button that looks like a dotted square (when you hover your mouse over it, the description should be 'New (Insert)').

• Type in 'Asymptote'.
  • Executable: C:\Program Files\Asymptote\asy.exe
  • Arguments: -batchView -tex "pdflatex" %tm-*.asy

• Click on the New button again.
• Type in 'LaTeXComp'.
  • Executable: C:\Program Files\MiKTeX 2.7\miktex\bin\pdflatex.exe
  • Arguments: -interaction=nonstopmode "%pm"

• Click on the New button again.
• Type in 'BibTex'.
  • Executable: C:\Program Files\MiKTeX 2.7\miktex\bin\bibtex.exe
  • Arguments: "%bm"

• Click on the New button again.
• Type in 'MakeIndex'.
  • Executable: C:\Program Files\MiKTeX 2.7\miktex\bin\makeindex.exe
  • Arguments: "%bm"

• Click 'Ok' at the bottom.
• Go to Tools > Select Output Profile...
• Select the profile you just created.

Now you're done. All you have to do is click on 'Build' to compile both your LaTeX and embedded Asymptote code. What I would suggest is to only use this profile whenever you start a new asymptote environment or you updated a previously existing environment. This way, the building process will occur faster. (When you use this profile, your LaTeX document is compiled, then your Asymptote code is compiled, then your LaTeX document is compiled once more. So this will cause your build time to be increased by around 5-10 seconds.)

Note that if you have any errors in the Asymptote code, they will appear at the very bottom in the output box in TeXnicCenter.