PGF/TikZ Manual

The TikZ and PGF Packages
Manual for version 3.1.9a

Libraries

52 Externalization Library

by Christian Feuersänger

  • TikZ Library external

  • \usetikzlibrary{external} % and plain
    \usetikzlibrary[external] % Cont

    This library provides a high-level automatic or semi-automatic export feature for TikZ pictures. Its purpose is to convert each picture to a separate pdf without changing the document as such.

    It also externalizes \label information (and other aux file related stuff) using auxiliary files.

52.1 Overview

There are several reasons why external images for at least some pictures are of interest:

  • 1. Larger picture require a considerable amount of time, which is necessary for every compilation. However, only few images will change from run to run. It can simply save time to export finished images and include them as final graphics.

  • 2. It may be desirable to have final images for some graphics, for example to include them in third–party programs or to communicate them electronically.

  • 3. It may be necessary to typeset a file in environments where pgf and TikZ are not available. In this case, external images are the only way to ensure compatibility.

The purpose of this library is to provide a way to export any TikZ-picture to separate pdf (or eps) images without changing the main document. It is actually a simple user interface to the \beginpgfgraphicnamed \(\dotsc \) \endpgfgraphicnamed framework of pgf which is discussed in section 111.

52.2 Requirements

For most users, the library does not need special attention since requirements are met anyway. It collects all tokens between \begin{tikzpicture} and the next following \end{tikzpicture} and replaces them by the appropriate graphics or it takes steps to generate such an image.

It can’t expand macros during this step, so the only requirement is that every picture’s end is directly reachable from its beginning, without further macro expansion. Furthermore, the library assumes that all pictures are ended with \end{tikzpicture}.

The library always searches for the next picture’s end, \end{tikzpicture}. As a consequence, you can’t use nested pictures directly. You can nest pictures, but you have to avoid that the nested picture’s \end command is found before the outer \end command (for example using bracing constructs or by writing the nested picture into a separate macro call).

Consider using the \tikzexternaldisable method in case you’d like to skip selected pictures which do not meet the requirements.

52.3 A Word About Cont And Plain

Currently, the basic layer backend \beginpgfgraphicnamed \(\dotsc \) \endpgfgraphicnamed relies on only, so externalization is currently only supported for .

52.4 Externalizing Graphics

After loading the library, a call to \tikzexternalize is necessary to activate the externalization.


\documentclass{article}
% main document, called main.tex
\usepackage{tikz}

\usetikzlibrary{external}
\tikzexternalize % activate!

\begin{document}
\begin{tikzpicture}
\node {root}
child {node {left}}
child {node {right}
child {node {child}}
child {node {child}}
};
\end{tikzpicture}

A simple image is \tikz \fill (0,0) circle(5pt);.
\end{document}

The method works as follows: if the document is typeset normally, the library searches for replacement images for every picture. Filenames are generated automatically in the default configuration. In our case, the two file names will be main-figure0 and main-figure1. If they exist, those images are simply included and the pictures as such are not processed. If graphics files do not exist, steps are taken to generate the missing ones. Since (currently) only one output file can be set, each missing image needs to be generated by a separate run of in which the \jobname is set to the desired image file name. In the default configuration mode=convert with system call, these commands are issued automatically by using the \write18 method to call system commands. It is also possible to output every required file name or to generate a makefile; users will need to issue the required commands manually (or with make). The probably most comfortable way is to use the default configuration with


pdflatex -shell-escape main

which authorizes pdflatex to call itself recursively to generate the images. When it finishes, all images are generated and the document already includes them.

From this point on, successive runs of will use the final graphics files, the pictures won’t be used anymore. Section 52.5 contains details about how to submit such a file to environments where pgf is not available.

  • \tikzexternalize[optional arguments]

  • This command activates the externalization. It installs commands to replace every TikZ-picture. It needs to be called before \begin{document} because it may need to install its separate shipout routine.

    The optional arguments can be any of the keys described below.

    Note that the generation/modification of auxiliary files like .aux, .toc etc. is usually suppressed while a single image is externalized (details for \label support follow).

    It is also possible to write \tikzexternalize{main job name} if the argument is delimited by curly braces. This case is mainly for backwards compatibility and is no longer necessary. Since it might be useful in rare circumstances, it is documented in section 52.4.5.

    A detailed description about the process of externalization is provided in section 52.4.5.

    • \tikzexternalrealjob

    • After the library is loaded, this macro will always contain the correct main job’s name (in the example above, it is main). It is to be used instead of \jobname when the externalization is in effect.

    • \pgfactualjobname

    • Once \tikzexternalize has been called, \pgfactualjobname contains the name of the currently generated output file (which may be main or main-figure0 or main-figure1 in our example above).

    • \jobname

    • The value of \jobname is one of \tikzexternalrealjob or \pgfactualjobname, depending on the configuration. In short: if auxiliary file support (\label and \ref) is activated, \jobname=\tikzexternalrealjob (since that’s the base file name of auxiliary files).

  • /tikz/external/system call={template}(no default)

  • A template string used to generate system calls. Inside of {template}, the macro \image can be used as placeholder for the image which is about to be generated while \texsource contains the main file name (in truth, it contains \input{main file name}, but that doesn’t matter).

    The default depends on the value of \pgfsysdriver. For pgfsys-pdftex.def, it is


    \tikzset{external/system call={pdflatex \tikzexternalcheckshellescape -halt-on-error
    -interaction=batchmode -jobname "\image" "\texsource"}
    }

    where \tikzexternalcheckshellescape inserts the value of the configuration key shell escape if and only if the current document has been typeset with -shell-escape6.

    Other drivers result in slightly different calls. There is support for lualatex, xelatex, and dvips. The precise values are written to the .log file as soon as you attempt to compile a document.

    The argument {template} will be expanded using \edef, so any control sequences will be expanded. During this evaluation, ‘\\’ will result in a normal backslash, ‘\’. Furthermore, double quotes ‘"’, single quotes ‘'’, semicolons and dashes ‘-’ will be made to normal characters if any package uses them as macros. This ensures compatibility with the german package, for example.

  • /tikz/external/shell escape={command-line arg} (no default, initially -shell-escape)

  • Contains the command line option for latex which enables the \write18 feature. For -Live, this is -shell-escape. For MiK, you should use \tikzexternalize[shell escape=-enable-write18].

6 Note that this is always true for the default configuration. This security consideration applies mainly for mode=list and make which will also work without shell escapes.

52.4.1 Support for Labels and References In External Files

The external library comes with extra support for \label and \ref (and other commands which usually store information in the .aux file) inside an external files.

In particular, it supports the two use-cases

  • a) \ref to something in the main document inside an externalized graphics or

  • b) \label in the externalized graphics which is referenced in the main document.

The only restriction is that you need to compile your document multiple times (as usual for references).

NOTE: support for a) is unavailable for versions up to and including pgf 3.0.1.

  • /tikz/external/aux in dpth={boolean} (no default, initially true)

  • Allows to enable or disable the feature which handles references and labels as part of image externalization. Disabling it will safe one \newwrite command, i.e. a write register.

    Also see the disable dependency files feature.

    Here are some implementation details on how references within/from external graphics work for those who would like to know the details:

    For point a), a \ref inside of an externalized graphics works by reading the main document’s .aux file. To this end, the standard mode=convert with system call detects such references and reschedules the externalization to \end{document}.7 Other values of mode require just one attempt to externalize the picture.

    Note that \pageref is not supported (sorry).

    Point b) works as follows: a \label inside of an externalized graphics causes the external library to generate separate auxiliary files for every external image. These files are called imagename.dpth. The extension .dpth indicates that the file also contains the image’s depth (the baseline key of TikZ). Furthermore, anything which would have been written to an .aux file will be redirected to the .dpth file – but only things which occur inside of the externalized tikzpicture environment. When the main document loads the image, it will copy the .dpth file into the main .aux file. Then, successive compilations of the main document contain the external \label information. In other words, a \label in an external graphics needs the following work flow:

    • 1. The external graphics needs to be generated together with its .dpth (usually automatically by TikZ).

    • 2. The main document includes the external graphics and copies the .dpth content into its main .aux file.

    • 3. The main document needs to be translated once again to re-read its .aux file8.

    This does also work if a \label/\ref combination is implemented itself by a tikzpicture (a feature offered by pgfplots).

7 Note that this requires the atveryend package. The purpose to reschedule the externalization is to access the main job’s aux file, but only after it has been written completely.

8 Note that it is not possible to activate the content of an auxiliary file after \begin{document} in .

52.4.2 Customizing the Generated File Names

The default filename for externalized graphics is ‘real file name-figure_number’ where number ranges from \(0\) to whatever is required. However, there are a couple of ways to change the generated filenames:

  • • Changing the overall file name using a prefix,

  • • Changing the file name for a single figure using \tikzsetnextfilename,

  • • Changing the file name for a restricted set of figures using figure name.

  • /tikz/external/prefix={file name prefix} (no default, initially empty)

  • A shortcut for \tikzsetexternalprefix{file name prefix}, see below.

  • \tikzsetexternalprefix{file name prefix}

  • Assigns a common prefix used by all file names. For example,


    \tikzsetexternalprefix{figures/}

    will prepend figures/ to every external graphics file name.

    Please note that \tikzsetexternalprefix is the only way to assign a prefix in case you want to prepare your document for environments where pgf is not installed (see section 52.5).

  • /tikz/external/figure name={name}(no default)

  • Same as \tikzsetfigurename{name}.

  • \tikzsetfigurename{name}

  • Changes the names of all following figures. It is possible to change figure name during the document either using \tikzset{external/figure name={name}} or with this command. A unique counter will be used for each different {name}, and each counter will start at \(0\).

    The value of prefix will be applied after figure name has been evaluated.


    \documentclass{article}
    % main document, called main.tex
    \usepackage{tikz}

    \usetikzlibrary{external}
    \tikzexternalize % activate

    \begin{document}

    \begin{tikzpicture} % will be written to 'main-figure0.pdf'
    \node {root}
    child {node {left}}
    child {node {right}
    child {node {child}}
    child {node {child}}
    };
    \end{tikzpicture}

    {
    \tikzsetfigurename{subset_}
    A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'subset_0.pdf'

    \begin{tikzpicture} % will be written to 'subset_1.pdf'
    \draw[help lines] (0,0) grid (5,5);
    \end{tikzpicture}
    }% here, the old file name will be restored:

    \begin{tikzpicture} % will be written to 'main-figure1.pdf'
    \draw (0,0) -- (5,5);
    \end{tikzpicture}
    \end{document}

    The scope of figure name ends with the next closing brace.

    Remark: Use \tikzset{external/figure name/.add={prefix_}{_suffix_}} to add a prefix_ and a _suffix_ to the actual value of figure name.

  • \tikzappendtofigurename{suffix}

  • Appends suffix to the actual value of figure name.

    It is a shortcut for \tikzset{external/figure name/.add={}{suffix}} (a shortcut which is also supported if TikZ is not installed, see below).

52.4.3 Remaking Figures or Skipping Figures
  • \tikzpicturedependsonfile{file name}

  • Adds a dependency for the next picture which is about to be externalized. If the command is invoked within a picture environment, it adds a dependency for the surrounding picture. Dependencies are written into target file.dep in the format

    target file.\tikzexternalimgextension: file name.

    The effect is that if file name changes, the external graphics associated with the picture shall be remade.

    This command uses the contents of \tikzexternalimgextension to check for graphics. If you encounter difficulties with image extensions, consider redefining this macro (after \tikzexternalize).

Limitations: this command is currently only supported for mode=list and make and the generated makefile.

  • \tikzexternalfiledependsonfile{external graphics}{file name}

  • A variant of \tikzpicturedependsonfile which adds a dependency for an external graphics. The argument external graphics must be the path as it would have been generated by the external library, i.e. without file extension but including any prefixes.

  • /tikz/external/disable dependency files(no value)

  • Allows to (irreversibly) disable the generation of file dependencies. Disabling it will safe one \newwrite command, i.e. a write register. Note that the write register is only allocated if the feature has been used at all. This key needs to be provided as argument to \tikzexternalize (or it needs to be set before calling \tikzexternalize).

    Also see the aux in dpth key.

  • /tikz/external/force remake={boolean} (default true)

  • A boolean which is used to customize the up-to-date checks of all following figures. Every up-to-date check will fail, resulting in automatic regeneration of every following figure.

    You can also use force remake inside of a local group to remake only selected pictures. The example


    \tikz \draw (0,0) -- (1,1);

    {
    \tikzset{external/force remake}
    \begin{tikzpicture}
    \draw (0,0) circle(5pt);
    \end{tikzpicture}
    }

    \tikz \draw (0,0) -- (1,1);

    will only apply force remake to the second figure.

    Up-to-date checks are applied for mode=convert with system call and the makefile generated by mode=list and make.

  • /tikz/external/remake next={boolean} (default true)

  • A variant of force remake which applies only to the next image.

  • /tikz/external/export next={boolean} (default true)

  • A boolean which can be used to disable the export mechanism for single pictures.

  • /tikz/external/export={boolean} (no default, initially true)

  • A boolean which can be used to disable the export mechanism for all pictures inside of the current -scope.


    \begin{document}
    \begin{tikzpicture} % will be exported
    ...
    \end{tikzpicture}

    {
    \tikzset{external/export=false}
    \begin{tikzpicture} % won't be exported
    ...
    \end{tikzpicture}
    ...
    }

    \begin{tikzpicture} % will be exported
    ...
    \end{tikzpicture}
    \end{document}

    For , the feature lasts until the next \end{\(\cdot \)} (this holds for every call to \tikzset).

  • /tikz/external/up to date check={choice} (no default, initially md5)

  • The external lib has to decide when some existing figure is up-to-date. In such a case, it can be used without remaking it. Outdated pictures will be remade.

    The key up to date check allows to choose among a couple of heuristics which are supposed to catch the most important reasons to remake a figure.

    The up to date check can be overrule by any of the force remake or remake next keys: if one of them is true, the figure is not up-to-date.

    The choice simple is based on the existence of the file: the file is up-to-date if and only if it exists.

    The choice md5 generates an MD5 checksum of the picture for which the up-to-date check is running. The MD5 is compared against the MD5 of the previous run, which, in turn, will be written into an extra file with the extension .md5. This file will be modified if and only if the MD5 comparison indicates a difference. The MD5 computation is based on the pdf method \pdfmdfivesum. If it is unavailable for some reason, the choice diff will be used instead.

    The choice diff is the same as MD5 – except that it compares the picture content as-is instead of a hash. The .md5 file will be used to compare an old version with the current one – but its content is some “normalized” version of the picture for internal use.

Attention: the content–based strategies md5 and diff operate on the picture content – and only on the picture content. Here, “picture content” only includes the top–level tokens; no expansion is applied and no included files are part of the strategies. If you change preamble styles, you have to rebuild the figures manually (for example by deleting the generated graphics files). If you have include files, consider using \tikzpicturedependsonfile and its variants. Since this key provides heuristics, you should always remake your figures before you finally publish your document. Example: Suppose we have the following picture which depends on a command \mycommand:


\def\mycommand{My comment}

\begin{tikzpicture}

\node at (0,0) {\mycommand};

\end{tikzpicture}

What happens if you change “My comment” to “My super comment”? Well, external will not pick it up; you will need to handle this manually. However, if you modify anything between \begin{tikzpicture} and \end{tikzpicture}, the external library will pick it up and regenerate the picture.

The up to date check is applied for mode=convert with system call and mode=list and make.

  • \tikzexternaldisable

  • Allows to disable the complete externalization. While export next will still collect the contents of picture environments, this command uninstalls the hooks for the external library completely. Thus, nested picture environments or environments where \end{tikzpicture} is not directly reachable won’t produce compilation failures – although it is not possible to externalize them automatically.

    The externalization remains disabled until the end of the next group (or environment) or until the next call to \tikzexternalenable.

  • \tikzexternalenable

  • Re-enables a previously running externalization after \tikzexternaldisable.

52.4.4 Customizing the Externalization
  • /tikz/external/mode={choice} (no default, initially convert with system call)

  • Configures what to do with TikZ pictures (unless we are currently externalizing one particular image, in that case, these modes are ignored).

    The preconfigured mode convert with system call checks whether external graphics files are up-to-date and includes them if that is the case. Any picture which is not up-to-date will be generated automatically using a system call. The system call can be configured using the system call template. The up-to-date check is applied according to the up to date check key. As soon as convert with system call is set, the figure list will be disabled – such a file is not required. In case you still need or want it, you can enable it after setting mode.

    Please note that system calls may be disabled for security reasons. For pdflatex, they can be enabled using


    pdflatex -shell-escape

    while other variants may need other switches. The feature is sometimes called \write18.

    The choice only graphics always tries to replace pictures with external graphics. It is an error if the graphics file does not exist.

    The choice no graphics (or, equivalently, only pictures) typesets TikZ pictures without checking for external graphics.

    A mixture is graphics if exists, it checks whether a suitable graphics file exists and includes it if that is the case. If it does not exist, the picture is typeset using .

    Mode list only skips every TikZ picture; it only generates the file {main file}.figlist containing file names for every picture, the contents of any picture environment is thrown away and a replacement text is shown. This implies figure list=true. See also the list and make mode which includes available graphics.

    The mode list and make is similar to list only: it generates the same file {main file}.figlist, but any images which exist already are included as graphics instead of ignoring them. Furthermore, this mode generates an additional file: {main file}.makefile. This allows to use a work flow like


    % step 1: generate main.makefile:
    pdflatex main
    % step 2: generate ALL graphics on 2 processors:
    make -j 2 -f main.makefile
    % step 3: include the graphics:
    pdflatex main

    This last make method is optional: list and make just assumes that images are generated somehow (not necessarily with the generated makefile). The generated makefile allows parallel externalization of graphics on multi-core systems and it supports any file dependencies configured with \tikzpicturedependsonfile. Furthermore, it respects the force remake and remake next keys.

  • /tikz/external/verbose IO={boolean} (no default, initially true)

  • A boolean which configures whether I/O operations shall be listed in the logfile.

  • /tikz/external/verbose optimize={boolean} (no default, initially true)

  • A boolean which configures whether optimization operations shall be listed in the logfile.

  • /tikz/external/verbose={boolean} (no default, initially true)

  • Sets all verbosity flags to boolean.

  • /tikz/external/optimize={boolean} (no default, initially true)

  • Configures whether the conversion process shall be optimized. This affects only the case when \jobname differs from the main file name, i.e. when single pictures are converted.

    In that case, the main file is compiled as usual – but everything except the selected picture is thrown away. If optimization is enabled, all other pictures won’t be processed at all. Furthermore, expensive commands which do not contribute to the selected picture will be thrown away as well.

    The default implementation discards \includegraphics commands which are not inside of the selected picture to reduce conversion time.

    It is possible to add commands which shall be optimized away, see below.

  • /tikz/external/optimize command away=\command{required argument count}(no default)

  • Installs commands to optimize \command away. As is described above, optimization applies to the case when single pictures are converted: one usually doesn’t need to process (probably expensive) commands which do not contribute to the selected picture.

    The argument {required argument count} is either empty or a non-negative integer between \(0\) and \(9\). It denotes the number of arguments which should be consumed after \command. In any case, one argument in square brackets after the command will be recognized as well. To be more precise, the following cases for arguments of \command are supported:

    • 1. If {required argument count} is empty (the default), \command may take one optional argument in square brackets and one in curly braces (which is also optional).

    • 2. If {required argument count} is not empty, {\command} may take one optional argument in square brackets. Furthermore, it expects exactly {required argument count} following arguments.

    Example:


    \tikzset{external/optimize command away=\includegraphics}

    \newcommand{\myExpensiveMacro}[1]{Very expensive!}

    \tikzset{external/optimize command away=\myExpensiveMacro}

    \newcommand{\myExpensiveMacroWithThreeArgs}[3]{Very expensive!}

    \tikzset{external/optimize command away={\myExpensiveMacroWithThreeArgs}{3}}

    % A command with optional argument:
    \newcommand{\aFurtherExample}[3][]{Very expensive!}

    % consume only two arguments: the first optional one will be processed
    % anyway:
    \tikzset{external/optimize command away={\myExpensiveMacroWithThreeArgs}{2}}

    The argument \command must be the name of a single macro. Any occurrence of this macro, together with its arguments, will be removed.


    \begin{tikzpicture}
    % this picture is currently converted!
    \end{tikzpicture}

    This here is outside of the converted picture and contains \myExpensiveMacro. It will be discarded.

    This call: \myExpensiveMacro[argument=value]{Argument} as well.
    And this here: \myExpensiveMacro{Argument} also.

    The default is to optimize \includegraphics away.

    This key is actually a style which sets the optimize/install and optimize/restore keys.

  • /tikz/external/optimize/install(no value)

  • A command key which contains code to install optimizations. You can append code here (or clear the macro) if you need to modify the optimization.

  • /tikz/external/optimize/restore(no value)

  • A command key which contains code to undo optimizations. You can append code here (or clear the macro) if you need to modify the optimization.

  • /tikz/external/only named={boolean} (no default, initially false)

  • If enabled, only pictures for which file names have been set explicitly using \tikzsetnextfilename will be considered, no file names will be generated automatically.

  • /pgf/images/include external(initially \pgfimage{#1})

  • This command key constitutes the public interface to exchange the \includegraphics command used for the image inclusion. If can be overwritten using include external/.code={ code}.

    Its description can be found in the corresponding basic layer documentation in section 111.4.

    Just one example here: you can use


    \pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}}

    to manually change the viewport (bounding box) for included graphics.

    Another example (of probably limited use) is

    which will generate a clickable hyperlink around the image. Clicking on it opens the single exported file9.

    If you want to limit the effects of this key to just one externalized figure, use


    {
    \pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}}
    \begin{tikzpicture}
    ...
    \end{tikzpicture}
    }% this brace ends the effect of `include external'

  • \tikzifexternalizing{true code}{false code}

  • This command can be used to check whether an image is currently written to its separate graphics file (if the “grab” procedure is running). If so, the {true code} will be executed. If not, that means if the main document is being typeset normally, the {false code} will be invoked.

    This command must be used after \tikzexternalize.

  • \tikzifexternalizingnext{true code}{false code}

  • Like \tikzifexternalizing, but this variant also checks if the next following figure is the one which is about to be written to its separate graphics file.

9 This requires all external graphics files in the same base directory as the main .pdf file.

52.4.5 Details About The Process

The standard run pdflatex main document causes the external library to check every occurrence of \begin{tikzpicture} and every \tikz short command. If it finds a picture which shall be exported, it queries the respective file name and checks whether the file exists already. If so, it includes the external graphics. If not, it requires an externalization which can be done automatically (the default), semi-automatically (with mode=list and make) or manually (by issuing the requires system calls somehow).

The library can detect whether it runs in “conversion mode”, i.e. if it should only process a single image. To do so, it checks whether the internal macro \tikzexternalrealjob exists. If so, its contents is assumed to be main document (without the suffix .tex). Usually, this macro is set by the conversion system call,


pdflatex -jobname "main-figure0" "\def\tikzexternalrealjob{main}\input{main}"

where main-figure0 is the picture we are currently externalizing and main.tex is the main document.

As soon as “conversion mode” has been detected, pgf changes the output routine. The complete file main.tex is processed as normal, but only the part of the desired picture will be written to the output file, in our case main-figure0.pdf. The rest of the document is silently thrown away. Of course, such a conversion process is quite expensive since we need to do it for every picture. Since everything except the current picture is thrown away, the library skips all other pictures. Furthermore, any \includegraphics commands which are outside of the converted TikZ-picture will be skipped as well. Thus, the conversion process should be much faster than typesetting the complete document, but it still requires its time. Eventually, the call \input{main} returns and the picture is ready. From this point on, the external graphics will be used.

There is another possibility to communicate main document to the subprocess performing the externalization: namely to write ‘\tikzexternalize{main}’ into the document. In this case, the conversion system call will be


pdflatex -jobname "main-figure0" "main"

and the contents of \tikzexternalrealjob is set automatically. This case is detected by \tikzexternalize, and the system call is updated automatically (by patching its \texsource template argument). It is not necessary to change the system call manually.

The sequence in which system calls are performed and the decision whether they are issued automatically is governed by the mode key, consult its documentation for details.

52.5 Using External Graphics Without pgf Installed

Given that every picture has been exported correctly, one may want to compile a file without pgf and TikZ installed. TikZ comes with a minimal package which contains just enough commands to replace every tikzpicture environment and the \tikz short command with the appropriate external graphics. It can be found at


latex/pgf/utilities/tikzexternal.sty

and needs to be used instead of \usepackage{tikz}. So, we comment \usepackage{tikz} and \usetikzlibrary{external}, load packages graphicx and tikzexternal, and finally our example from the beginning becomes


\documentclass{article}
% main document, called main.tex
%\usepackage{tikz}

\usepackage{graphicx}
\usepackage{tikzexternal}

%\usetikzlibrary{external}
\tikzexternalize

\begin{document}
\begin{tikzpicture}
\node {root}
child {node {left}}
child {node {right}
child {node {child}}
child {node {child}}
};
\end{tikzpicture}

A simple image is \tikz \fill (0,0) circle(5pt);.

Furthermore, we might want to draw \tikz[baseline]\draw (0,-1) rectangle (1,1);
\end{document}

where the following files are necessary to compile the document:


tikzexternal.sty
main.tex
main-figure0.pdf
main-figure1.pdf
main-figure2.pdf

If there are any ‘.dpth’ files, for example main-figure2.dpth, these files are also required. They contain information for the TikZ baseline option (or \labels inside external graphics).

Just copy the .sty file into the directory of your main.tex file and use it as part of your document.

Please keep in mind, that only tikzpicture environments and \tikz short images are available within the externalization framework. Additionally, calls to \tikzset and \pgfkeys won’t lead to compilation errors because they are simply ignored. But since pgfkeys is not available, any option supplied to \tikzexternalize is ignored.

Attention: Since the simple replacement \usepackage{tikzexternal} doesn’t support the key–value interface, you need to use \tikzsetexternalprefix instead of the prefix option and \tikzsetfigurename instead of the figure name option since \tikzset is not available in such a context.

Remark: Some of the features of this library are mainly useful to improve the speed of successive document compilations. In other words: you can’t use all features in this context, keep it simple.

52.6 eps Graphics Export

It is also possible to use eps graphics instead of pdf files. There are different ways to produce them, for example to use pdflatex and call pdftops -eps {pdf file} {eps file} afterwards. You could add this command to the system call option.

Alternatively, you can use latex and dvips for image conversion as is explained for the system call option, see section 52.4. See the documentation for the basic level externalization in section 111 for restrictions of other drivers.

52.7 Bitmap Graphics Export

Occasionally, you may have an extremely large graphics which takes long times to render. It might be interesting to generate a bitmap (raster) image, which displays much faster (for example in a presentation). I have used this feature to speed-up the display of large shadings.

The external library can be customized to export bitmap images – with the help of external programs. Due to the dependence of external programs, you may need to adjust these commands manually. For example, on my computer, the ImageMagick Suite is installed which comes with the convert tool. Together with pdflatex, I can define the following style:


\tikzset{
% Defines a custom style which generates BOTH, .pdf and .png export
% but prefers the .png on inclusion.
%
% This style is not pre-defined, you may need to copy-paste and
% adjust it.
png export/.style={
external/system call/.add=
{}
{; convert -density 300 -transparent white "\image.pdf" "\image.png"}
,
%
/pgf/images/external info,
/pgf/images/include external/.code={%
\includegraphics
[width=\pgfexternalwidth,height=\pgfexternalheight]
{##1.png}%
}
,
}
}

The example above defines a new style called ‘png export’ which, when it is set with \tikzset{png export} somewhere in the document, modifies the configuration for both file generation and file input. The file generation is modified by appending the ImageMagick command to system call (separated by ‘;’ as usual on Linux). This is, in principle, enough to generate a .png file. The include external command is overwritten such that it uses the .png file instead of the .pdf file (which exists as well in the configuration above). But since a .png file can have a much higher resolution than the desired image dimensions, we have to add width and height explicitly. Usually, the external library does not provide size information (it is unnecessary for .pdf or .eps since these formats have their bounding box information). To enable size information, the style uses the external info key, which, in turn, provides the \pgfexternalwidth and \pgfexternalheight commands.

Now we can use \tikzset{png export} either document-wide or just for one particular image. The configuration remains in effect until the end of the current environment (or until the next closing curly brace ‘}’).

  • /pgf/images/external info={boolean} (no default, initially false)

  • If this key is activated, the size for any externalized image will be stored explicitly into the associated .dpth file.

    When the file is included by \pgfincludeexternalgraphics (or automatically by the external library), the width is available as >\pgfexternalwidth and the height as \pgfexternalheight.

52.8 Compatibility Issues
52.8.1 References In External Pictures

It is allowed if a picture contains references, for example \tikz \node {Reference to \ref{a:label}};.

There is just one issue: if the main job is currently compiling, its .aux file is not in its final state (even worse: it may not be readable at all). The picture externalization, however, needs the main .aux file to query any references.

Thus, you will need to invoke pdflatex -jobname image mainfile manually for any image which contains references.

This problem arises only for mode=convert with system call. In this case, the external library creates a special \jobname.auxlock file to check whether the main .aux file is currently usable.

52.8.2 Compatibility With Other Libraries or Packages

The external library has the following compatibility issues:

  • 1. The external library comes with special support for \usetikzlibrary{fadings}: the fadings library may define local pictures which would be externalized (although they shouldn’t). There is special handling to suppress this bug if \tikzexternalize is called after \usetikzlibrary{fadings} or if all fadings are defined before \tikzexternalize.

  • 2. Problems have been reported when using \tikzexternalize (or the basic layer externalization) together with \usepackage{glossary}. This problem disappears if \tikzexternalize is called before \usepackage{glossary}.

  • 3. Problems with \usepackage{pdfpages} and \usepackage{vmargin}: The external library replaces the current shipout routine of during its externalization. This might raise problems with other packages which also manipulate the shipout routine (like the mentioned ones). To fix those problems, use



    \usetikzlibrary{external}

    \tikzifexternalizing{%
    % don't include package XYZ here
    }{%
    \usepackage{pdfpages}
    \usepackage{vmargin}
    ...
    }%

    This uses the requested packages for the main document, but not for the single, exported graphics.

In general, the \tikzifexternalizing feature might be used to solve package conflicts and the \tikzexternaldisable and \tikzexternalenable features can be used to solve problems with single pictures.

52.8.3 Compatibility With Bounding Box Restrictions

Bounding box restrictions provide no problem when used with eps graphics. However, they pose problems for pdflatex, so you may need to use the latex/dvips combination if you use bounding box restrictions and externalization. Currently, the only possibility for bounding box restrictions and pdflatex is to use a combination of trim left/trim right/baseline: these keys do not really truncate the bounding box, they only store horizontal and vertical shifts (also see the trim lowlevel key in this context).

52.8.4 Interoperability With The Basic Layer Externalization

This library is fully compatible with \beginpgfgraphicnamed\(\dotsc \)\endpgfgraphicnamed environments. However, you will need to use the export next=false key to avoid conflicts:

Please keep in mind that file prefixes do not apply to the basic layer.