Including DOT Graphs as PostScript or PDF files in LaTeX documents

Graphviz is a great open source graph visualization software. In this post I’ll demonstrate how to include DOT graphs in PDF documents using LaTeX.

The most convenient way to insert graphics into PDF documents is to use vector graphics. In contrast to raster graphics (which are pixel-based) vector graphics can be scaled arbitrarily without getting “pixelated”.

From DOT the graphics can be exported in vector graphics as Portable Document Format (PDF) or Encapsulated Post Script (EPS) files. The file type you need depends on the LaTeX compiler you are using. The standard latex compiler can handle EPS files, whereas pdflatex supports PDF graphics.

Option 1: Using latex and EPS graphics

Assuming you have persisted your graph in a dot file, say myGraph.dot, you can convert it to an Encapsulated Post Script (EPS) file by using the dot tool from the command line:

1
dot -Tps2 myGraph.dot -o myGraph.eps

Here is a nice shell script which converts all dot files in the current directory to eps files:

1
2
3
4
5
6
7
8
#!/bin/bash
for f in *.dot; do
  basename=$(basename "$f")
  filename=${basename%.*}
  command="dot -Tps2 $f -o ${filename}.eps";
  echo $command;
  $command;
done

To use it, simply save it as an .sh file, execute chmod 755 on it and execute it in the terminal (works for unix-based systems only).

Having done that, we try to insert that image in our pdf file:

1
2
3
4
5
6
7
\begin{figure}[htp]
\begin{center}
  \includegraphics[width=0.9\textwidth]{myGraph}
  \caption{My Caption}
  \label{fig:myGraph}
\end{center}
\end{figure}

Note that the file extension is ommited.

Unfortunately, the pdflatex compiler does not support EPS images. But don’t worry, there are two options for solving that.

Option 2: Using pdflatex and PDF graphics

If you are using pdflatex, PDF graphics have to be produced instead of EPS graphics. This is done as described in the previous section, except another target file type is specified:

1
dot -Tpdf myGraph.dot -o myGraph.pdf

Option 3: Using pdflatex and converting EPS to PDF on the fly

The epstopdf LaTeX package converts your EPS files to PDF files on the fly, which then can be included in your document. This is how you must configure your graphic packages in the preamble of your LaTeX document (code from this blog post):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
\newif\ifpdf
\ifx\pdfoutput\undefined
   \pdffalse
\else
   \pdfoutput=1
   \pdftrue
\fi
\ifpdf
   \usepackage{graphicx}
   \usepackage{epstopdf}
   \DeclareGraphicsRule{.eps}{pdf}{.pdf}{`epstopdf #1}
   \pdfcompresslevel=9
\else
   \usepackage{graphicx}
\fi

The epstopdf package will automatically create a PDF file of your figure and include it in your document. However, the following requirements must be fulfilled:

The -shell-escape option must be set when invoking the compiler. The command line setting for this invocation can be set in your LaTeX IDE. Here I will illustrate how to configure this setting using the TeXlipse IDE for Eclipse:

Builder SettingsOpen Preferences -> Texlipse -> Builder Settings, select the PdfLatex program and click Edit. The following dialog appears, in which you can add the -shell-escape option to the command line:

-shell-escape optionAnother requirement (which is specific to the TeXlipse environment) is the PATH variable, which has to be set. Otherwise, the shell commands called from LaTeX can not be executed correctly. Check out your system path by opening a terminal and typing:

1
echo $PATH

Copy the output to the clipboard, and in TeXlipse go to Preferences -> TeXlipse -> Builder Settings -> Environment. Click Add and create a new environment variable named PATH with the value of your system path, which you just copied from the terminal:

AddEnvironmentVariableAfter that, the EPS-to-PDF conversion should work on the fly. If it does not work for some reason, you can manually invoke the conversion from the command line:

1
epstopdf myGraph.eps

You can now publish PDF documents with infinitely-scalable graphs 🙂

Installing LaTeX, Eclipse and TeXlipse on Mac OS X

LaTeX is an essential typesetting language for scientific papers and presentations. In this blog post I will explain how to install a complete LaTeX environment on your mac based on MacTex, Eclipse and TeXlipse. These components form a very powerful IDE for writing documents with LaTeX.

Installing a LaTeX distribution

The recommended LaTeX distribution to install on OS X is MacTex. Just follow the link, download the (very large!) installation bundle and execute it.

Installing Eclipse

Eclipse is a very powerful software platform, allowing to install plugins in order to assemble a flexible and powerful IDE. Download Eclipse (Version for Java Developers) here for your appropriate processor architecture. Unpack the file and execute Eclipse.app inside the unpacked folder.

If you are running Mountain Lion and get a system message that “Eclipse can not be executed because the developer is not verified”, unlock the App by starting a Terminal window and typing the following command:

xattr -d com.apple.quarantine /Applications/eclipse/Eclipse.app

Of course, you have to change the path to your custom location.

When Eclipse is started for the first time, it will ask you for a “workspace location”. This is a folder on your hard disk where your projects and files that are edited in Eclipse are stored. Choose an appropriate location of your choice and select “use this as default and do not ask again“.

01_workspace

On the first start, a welcome screen will appear, which you can simply close.

Installing TeXlipse (Option A – via Eclipse Marketplace)

To install the LaTeX plugin for Eclipse named TeXlipse, you simply go to Help -> Eclipse Marketplace.

03_marketplace

Wait until the list is loaded and type texlipse into the search field. TeXlipse will be listed as first option in the list. Click the Install button.

04_marketplace2

In the following dialog, click Next, read and accept the license and then click Finish. If you get a security warning saying that “you are trying to install software with unsigned content”, click OK. After the installation you’ll be asked to restart Eclipse, which you confirm with Yes.

Installing TeXlipse (Option B – Update Site)

If for some reason the menu item Eclipse Marketplace is missing, you can also install TeXlipse via Help -> Install new Software. In that case, you need to provide an Update Site, which is http://texlipse.sourceforge.net/.

Configuring TeXlipse

After the successful installation, TeXlipse needs some configuration. Therefore, go to Eclipse -> Preferences (Shortcut: Cmd + ,).

05_settings

In the preferences, go to TeXlipse -> Builder Settings. Here the paths to the MacTex binaries have to be set.

To set all paths simultaneously, click on the Browse… button and choose your LaTeX executable folder. On my system (64 bit), the path is

/usr/local/texlive/2011/bin/x86_64-darwin

On 32 bit systems, the path should be similar to

/usr/local/texlive/2011/bin/universal-darwin

After the path is selected, hit the Apply button. Now almost all executable paths should be configured (see screenshot).

06_builders

Next, you have to configure a PDF viewer. Go to TeXlipse -> Viewer settings -> New… and add the values shown in the screenshot (Name: open, Command: /user/bin/open, Arguments: %file).

08_viewer

Move your configuration up in the list.

09_viewer2

Creating a LaTeX project

To create your first LaTeX project, right click inside the Package Explorer (on the left) and choose New -> Project… and in the dialog select TeXlipse -> LaTeX Project. On the next screen, enter a project name and the language code and choose the output format pdf. The builds commands should automatically switch to pdflatex. The article template is a good starting point.

07_project

When you click Finish, Eclipse will ask you if the LaTeX perspective should be opened, which you confirm with Yes.

Building the PDF

To build the PDF, simply make changes to a .tex file and save it. Eclipse will automatically trigger a PDF build on every document save action. You can view the output in the console (located at the bottom of the IDE by default). To view the PDF, use the shortcut Cmd + 4. If everything went fine, you should see a simple PDF file:

10_pdfNow you are ready to write great papers with LaTeX. Enjoy 🙂