The TikZ and PGF Packages
Manual for version 3.1.10

The Basic Layer

111 Externalizing Graphics¶

111.1 Overview¶

There are two fundamentally different ways of inserting graphics into a TeX-document. First, you can create a graphic using some external program like xfig or InDesign and then include this graphic in your text. This is done using commands like \includegraphics or \pgfimage. In this case, the graphic file contains all the low-level graphic commands that describe the picture. When such a file is included, all TeX has to worry about is the size of the picture; the internals of the picture are unknown to TeX and it does not care about them.

The second method of creating graphics is to use a special package that transforms TeX-commands like \draw or \psline into appropriate low-level graphic commands. In this case, TeX has to do all the hard work of “typesetting” the picture and if a picture has a complicated internal structure this may take a lot of time.

While pgf was created to facilitate the second method of creating pictures, there are two main reasons why you may need to employ the first method of image-inclusion, nevertheless:

• 1. Typesetting a picture using TeX can be a very time-consuming process. If TeX needs a minute to typeset a picture, you do not want to wait this minute when you reTeX your document after having changed a single comma.

• 2. Some users, especially journal editors, may not be able to process files that contain pgf commands – for the simple reason that the systems of many publishing houses do not have pgf installed.

In both cases, the solution is to “extract” or “externalize” pictures that would normally be typeset every time a document is TeXed. Once the pictures have been extracted into separate graphics files, these graphic files can be reinserted into the text using the first method.

Extracting a graphic from a file is not as easy as it may sound at first since TeX cannot write parts of its output into different files and a bit of trickery is needed. The following macros simplify the workflow:

• 1. You have to tell pgf which files will be used for which pictures. To do so, you enclose each picture that you wish to be “externalized” in a pair of \beginpgfgraphicnamed and \endpgfgraphicnamed macros.

• 2. The next step is to generate the extracted graphics. For this you run TeX with the \jobname set to the graphic file’s name. This will cause \pgfname to behave in a very special way: All of your document will simply be thrown away, except for the single graphic having the same name as the current jobname.

• 3. After you have run TeX once for each graphic that your wish to externalize, you can rerun TeX on your document normally. This will have the following effect: Each time a \beginpgfgraphicnamed is encountered, pgf checks whether a graphic file of the given name exists (if you did step 2, it will). If this graphic file exists, it will be input and the text till the corresponding \endpgfgraphicnamed will be ignored.

In the rest of this section, the above workflow is explained in more detail.

111.2 Workflow Step 1: Naming Graphics¶

In order to put each graphic in an external file, you first need to tell pgf the names of these files.

111.3 Workflow Step 2: Generating the External Graphics¶

We have now indicated all the graphics for which we would like graphic files to be generated. In order to generate the files, you now need to modify the \jobname appropriately. This is done in two steps:

• 1. You use the following command to tell pgf the real name of your .tex file:

  \pgfrealjobname{⟨name⟩} ¶

  Tells pgf the real name of your job. For instance, if you have a file called survey.tex that contains two graphics that you wish to be called survey-graphic1 and survey-graphic2, then you should write the following.

  copy
% This is file survey.tex
\documentclass{article}
...
\usepackage{tikz}
\pgfrealjobname{survey}


• 2. You run TeX with the \jobname set to the name of the graphic for which you need an external graphic to be generated. To set the \jobname, you use the --jobname= option of TeX:

  copy
bash> latex --jobname=survey-graphic1 survey.tex


The following things will now happen:

• 1. \pgfrealjobname notices that the \jobname is not the “real” jobname and, thus, must be the name of a graphic that is to be put in an external file.

• 2. At the beginning of the document, pgf changes the definition of TeX’s internal \shipout macro. The new shipout macro simply throws away the output. This means that the document is typeset normally, but no output is produced.

• 3. When the \beginpgfgraphicnamed{⟨name⟩} command is encountered where the ⟨name⟩ is the same as the current \jobname, then a TeX-box is started and ⟨everything⟩ up to the following \endpgfgraphicnamed command is stored inside this box.

  Note that, typically, ⟨everything⟩ will contain just a single {tikzpicture} or {pgfpicture} environment. However, this need not be the case, you can use, say, a {pspicture} environment as ⟨everything⟩ or even just some normal TeX-text.

• 4. At the \endpgfgraphicnamed, the box is shipped out using the original \shipout command. Thus, unlike everything else, the contents of the graphic is made part of the output.

• 5. When the box containing the graphic is shipped out, the paper size is modified such that it is exactly equal to the height and width of the box.

The net effect of everything described above is that the two commands

produce a file called survey-graphic1.ps that consists of a single page that contains exactly the graphic produced by the code between \beginpgfgraphicnamed{survey-graphic1} and \endpgfgraphicnamed. Furthermore, the size of this single page is exactly the size of the graphic.

If you use pdfTeX, producing the graphic is even simpler:

produces the single-page pdf-file survey-graphic1.pdf.

111.4 Workflow Step 3: Including the External Graphics¶

Once you have produced all the pictures in the text, including them into the main document is easy: Simply run TeX again without any modification of the \jobname. In this case the \pgfrealjobname command will notice that the main file is, indeed, the main file. The main file will then be typeset normally and the \beginpgfgraphicnamed commands also behave normally, which means that they will try to include the generated graphic files – which is exactly what you want.

Suppose that you wish to send your survey to a journal that does not have pgf installed. In this case, you now have all the necessary external graphics, but you still need pgf to automatically include them instead of the executing the picture code! One way to solve this problem is to simply delete all of the pgf or TikZ code from your survey.tex and instead insert appropriate \includegraphics commands “by hand”. However, there is a better way: You input the file pgfexternal.tex.

As a final remark, note that the baseline option does not work directly with pictures written to an external graphic file. The simple reason is that there is no way to store this baseline information in an external graphic file. To allow the baseline option (or any TeX construction with non-zero depth), the baseline information is stored into a separate file. This file is named {⟨image file⟩}.dpth and contains something like 5pt.

So, if you need baseline information, you will have to keep the external graphic file together with its .dpth file. Furthermore, the short command in \input pgfexternal.tex is no longer enough because it ignores any baseline information. You will need to use \input pgfexternalwithdepth.tex instead (it is shown below). It is slightly longer, but it can be used in the same way as pgfexternal.tex.

111.5 A Complete Example¶

Let us now have a look at a simple, but complete example. We start out with a normal file called survey.tex that has the following contents:

Now our editor tells us that the publisher will need all figures to be provided in separate PostScript or .pdf-files. For this, we enclose all figures in ...graphicnamed-pairs and we add a call to the \pgfrealjobname macro:

After these changes, typesetting the file will still yield the same output as it did before – after all, we have not yet created any external graphics.

To create the external graphics, we run pdflatex twice, once for each graphic:

We can now send the two generated graphics (survey-f1.pdf and survey-f2.pdf) to the editor. However, the publisher cannot use our survey.tex file, yet. The reason is that it contains the command \usepackage{tikz} and they do not have pgf installed.

Thus, we modify the main file survey.tex as follows:

If we now run pdfLaTeX, then, indeed, pgf is no longer needed:

bash> pdflatex survey.tex
This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6)
entering extended mode
(./survey.tex
LaTeX2e <2005/12/01>
Babel  and hyphenation patterns for english, ..., loaded.
(/usr/local/gwTeX/texmf.texlive/tex/latex/base/article.cls
Document Class: article 2005/09/16 v1.4f Standard LaTeX document class
(/usr/local/gwTeX/texmf.texlive/tex/latex/base/size10.clo))
(/usr/local/gwTeX/texmf.texlive/tex/latex/graphics/graphics.sty
(/usr/local/gwTeX/texmf.texlive/tex/latex/graphics/trig.sty)
(/usr/local/gwTeX/texmf.texlive/tex/latex/config/graphics.cfg)
(/usr/local/gwTeX/texmf.texlive/tex/latex/pdftex-def/pdftex.def))
(/Users/tantau/Library/texmf/tex/generic/pgf/generic/pgf/utilities/pgfexternal.
tex) (./survey.aux)
(/usr/local/gwTeX/texmf.texlive/tex/context/base/supp-pdf.tex
[Loading MPS to PDF converter (version 2006.09.02).]
)  
  [1{/Users/ta
ntau/Library/texmf/fonts/map/pdftex/updmap/pdftex.map} <./survey-f1.pdf> <./sur
vey-f2.pdf>] (./survey.aux) )
Output written on survey.pdf (1 page, 10006 bytes).
Transcript written on survey.log.

To our editor, we send the following files:

• • The last survey.tex shown above.

• • The graphic file survey-f1.pdf.

• • The graphic file survey-f2.pdf.

• • The file pgfexternal.tex, whose contents is simply

  copy
\long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{\includegraphics{#1}}


  (Alternatively, we can also directly add this line to our survey.tex file).

In case we have used the baseline option, we also need to include any .dpth files and we need to use the file pgfexternalwithdepth.tex instead of pgfexternal.tex. This file also checks for the existence of .dpth files containing baseline information, its contents is

Again, we could simply copy these lines to our survey.tex file.