pgfplots

Import/Export From Other Formats

\(\newcommand{\footnotename}{footnote}\) \(\def \LWRfootnote {1}\) \(\newcommand {\footnote }[2][\LWRfootnote ]{{}^{\mathrm {#1}}}\) \(\newcommand {\footnotemark }[1][\LWRfootnote ]{{}^{\mathrm {#1}}}\) \(\let \LWRorighspace \hspace \) \(\renewcommand {\hspace }{\ifstar \LWRorighspace \LWRorighspace }\) \(\newcommand {\mathnormal }[1]{{#1}}\) \(\newcommand \ensuremath [1]{#1}\) \(\newcommand {\LWRframebox }[2][]{\fbox {#2}} \newcommand {\framebox }[1][]{\LWRframebox } \) \(\newcommand {\setlength }[2]{}\) \(\newcommand {\addtolength }[2]{}\) \(\newcommand {\setcounter }[2]{}\) \(\newcommand {\addtocounter }[2]{}\) \(\newcommand {\arabic }[1]{}\) \(\newcommand {\number }[1]{}\) \(\newcommand {\noalign }[1]{\text {#1}\notag \\}\) \(\newcommand {\cline }[1]{}\) \(\newcommand {\directlua }[1]{\text {(directlua)}}\) \(\newcommand {\luatexdirectlua }[1]{\text {(directlua)}}\) \(\newcommand {\protect }{}\) \(\def \LWRabsorbnumber #1 {}\) \(\def \LWRabsorbquotenumber "#1 {}\) \(\newcommand {\LWRabsorboption }[1][]{}\) \(\newcommand {\LWRabsorbtwooptions }[1][]{\LWRabsorboption }\) \(\def \mathchar {\ifnextchar "\LWRabsorbquotenumber \LWRabsorbnumber }\) \(\def \mathcode #1={\mathchar }\) \(\let \delcode \mathcode \) \(\let \delimiter \mathchar \) \(\def \oe {\unicode {x0153}}\) \(\def \OE {\unicode {x0152}}\) \(\def \ae {\unicode {x00E6}}\) \(\def \AE {\unicode {x00C6}}\) \(\def \aa {\unicode {x00E5}}\) \(\def \AA {\unicode {x00C5}}\) \(\def \o {\unicode {x00F8}}\) \(\def \O {\unicode {x00D8}}\) \(\def \l {\unicode {x0142}}\) \(\def \L {\unicode {x0141}}\) \(\def \ss {\unicode {x00DF}}\) \(\def \SS {\unicode {x1E9E}}\) \(\def \dag {\unicode {x2020}}\) \(\def \ddag {\unicode {x2021}}\) \(\def \P {\unicode {x00B6}}\) \(\def \copyright {\unicode {x00A9}}\) \(\def \pounds {\unicode {x00A3}}\) \(\let \LWRref \ref \) \(\renewcommand {\ref }{\ifstar \LWRref \LWRref }\) \( \newcommand {\multicolumn }[3]{#3}\) \(\require {textcomp}\) \( \newcommand {\meta }[1]{\langle \textit {#1}\rangle } \) \(\newcommand {\toprule }[1][]{\hline }\) \(\let \midrule \toprule \) \(\let \bottomrule \toprule \) \(\def \LWRbooktabscmidruleparen (#1)#2{}\) \(\newcommand {\LWRbooktabscmidrulenoparen }[1]{}\) \(\newcommand {\cmidrule }[1][]{\ifnextchar (\LWRbooktabscmidruleparen \LWRbooktabscmidrulenoparen }\) \(\newcommand {\morecmidrules }{}\) \(\newcommand {\specialrule }[3]{\hline }\) \(\newcommand {\addlinespace }[1][]{}\) \(\require {colortbl}\) \(\let \LWRorigcolumncolor \columncolor \) \(\renewcommand {\columncolor }[2][named]{\LWRorigcolumncolor [#1]{#2}\LWRabsorbtwooptions }\) \(\let \LWRorigrowcolor \rowcolor \) \(\renewcommand {\rowcolor }[2][named]{\LWRorigrowcolor [#1]{#2}\LWRabsorbtwooptions }\) \(\let \LWRorigcellcolor \cellcolor \) \(\renewcommand {\cellcolor }[2][named]{\LWRorigcellcolor [#1]{#2}\LWRabsorbtwooptions }\) \(\newcommand {\intertext }[1]{\text {#1}\notag \\}\) \(\let \Hat \hat \) \(\let \Check \check \) \(\let \Tilde \tilde \) \(\let \Acute \acute \) \(\let \Grave \grave \) \(\let \Dot \dot \) \(\let \Ddot \ddot \) \(\let \Breve \breve \) \(\let \Bar \bar \) \(\let \Vec \vec \) \(\newcommand {\nicefrac }[3][]{\mathinner {{}^{#2}\!/\!_{#3}}}\)

8.1Export to pdf/eps

It is possible to export images to single pdf-documents using routines of pgf and/or TikZ.

8.1.1Using the Automatic Externalization Framework of TikZ¶

\usepgfplotslibrary{external} % LaTeX and plain TeX

\usepgfplotslibrary[external] % ConTeXt

\usetikzlibrary{pgfplots.external} % LaTeX and plain TeX

\usetikzlibrary[pgfplots.external] % ConTeXt

The external library offers a convenient method to export every single tikzpicture into a separate .pdf (or .eps). Later runs of LaTeX will simply include these graphics, thereby reducing typesetting time considerably.

The library can also be used to submit documents to authors who do not even have pgfplots or TikZ installed.

Technical foreword:

The external library has been written by Christian Feuersänger (author of pgfplots). It has been contributed to TikZ as general purpose library, so the reference documentation along with all tweaks can be found in the PGF/TikZ manual (Section “Externalization Library”). The command \usepgfplotslibrary{external} is actually just a wrapper which loads \usetikzlibrary{external} or, if this library does not yet exist because the installed pgf has at most version \(2.00\), it will load a copy which is shipped with pgfplots.

The external library has been designed such that no changes to the document as such are necessary. The idea is as follows:

1. Every \begin{tikzpicture} \(\dotsc \) \end{tikzpicture} gets a file name. The file name can be assigned manually with \tikzsetnextfilename{output file name} or automatically, in which case tex file name-figurenumber is used with an increasing number.
2. The library writes the resulting images using system calls of the form pdflatex --jobname output file name automatically, using the write18 system call of TeX. It is the same framework which can be used to call gnuplot.

The only steps which are necessary is to use

\usepgfplotslibrary{external}

\tikzexternalize

somewhere in your document’s preamble (see below for system-dependent configuration options). No further modification to the document is necessary. Suppose we have a file called test.tex:

\documentclass{article} \usepackage{pgfplots}


                      \usepgfplotslibrary{external}


                      \tikzexternalize% activate externalization!

\begin{document} \begin{figure}


                          \begin{tikzpicture}


                              \begin{axis}


                                  \addplot {x^2};


                              \end{axis}


                          \end{tikzpicture}


                          \caption{Our
                  first external
                  graphics
                  example}

\end{figure} \begin{figure}


                          \begin{tikzpicture}


                              \begin{axis}


                                  \addplot {x^3};


                              \end{axis}


                          \end{tikzpicture}


                          \caption{A
                  second graphics}

\end{figure} \end{document}

To enable the system calls, we type

pdflatex -shell-escape test

and LaTeX will now generate the required graphics files test-figure0.pdf and test-figure1.pdf automatically. Any further call to pdflatex will simply use \includegraphics and the tikzpictures as such are no longer considered (you need a different command line switch for MiKTeX, see the shell escape option).

If a figure shall be remade, one can simply delete all or selected graphics files and regenerate them. Alternatively, one can use the command \tikzset{external/force remake} somewhere in the document to remake every following picture automatically.

There are three ways to modify the file names of externalized figures:

• 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={ (math image) file name prefix} (initially empty) ¶

A shortcut for \tikzsetexternalprefix{ (math image) file name prefix}, see below.

\tikzsetexternalprefix{ (math image) 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.

\tikzsetnextfilename{ (math image) file name} ¶

Sets the file name for the next TikZ picture or \tikz short command. It will only be used for the next picture.

Pictures for which no explicit file name has been set will get automatically generated file names.

Please note that prefix will still be prepended to (math image) file name.

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


                          \usepgfplotslibrary{external}


                          \tikzexternalize[prefix=figures/]% activate with a name prefix

\begin{document}


                      \tikzsetnextfilename{firstplot}


                      \begin{tikzpicture} % will be written to 'figures/firstplot.pdf'


                          \begin{axis}


                              \addplot {x};


                          \end{axis}


                      \end{tikzpicture}


                      \begin{tikzpicture} % will be written to 'figures/main-figure0.pdf'


                         \draw [help lines] (0,0) grid (5,5);


                      \end{tikzpicture}

\end{document}

pdflatex -shell-escape main

/tikz/external/figure name={ (math image) name} ¶

Same as \tikzsetfigurename{ (math image) name}.

\tikzsetfigurename{ (math image) name} ¶

Changes the names of all following figures. It is possible to change figure name during the document using \tikzset{external/figure name={ (math image) name}}. 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}


                          \usepgfplotslibrary{external}


                          \tikzexternalize% activate externalization!

\begin{document} % will be written to 'main-figure0.pdf'


                      \begin{tikzpicture}


                          \begin{semilogyaxis}


                              \addplot {exp(x)};


                          \end{semilogyaxis}


                      \end{tikzpicture}

{


                          \tikzset{external/figure name={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'


                              \begin{axis}


                                  \addplot {x^2};


                              \end{axis}


                          \end{tikzpicture}

}% here, the old file name will be restored:


                      \begin{tikzpicture} % will be written to 'main-figure1.pdf'


                          \begin{axis}


                              \addplot[domain=1e-3:100] {1/x};


                          \end{axis}


                      \end{tikzpicture}

\end{document}

The scope of figure name ends with the next closing brace (as all values set by \tikzset do).

Remark: Use \tikzset{external/figure name/.add={ (math image) prefix}{suffix}} to prepend a prefix and append a suffix to the actual value of figure name. Might be useful for something like


                      \tikzset{external/figure name=main}

% uses main_0.pdf, main_1.pdf, ... \chapter{The first section}


                      {\tikzset{external/figure name/.add={}{_firstsection}}

...


                          % uses
                      main_firstsection_0.pdf, main_firstsection_1.pdf, ...

} \chapter{The second section}


                      {\tikzset{external/figure name/.add={}{secondsection_}}

...


                          % uses
                      main_secondsection_0.pdf, main_secondsection_1.pdf, ...


                          \section{Second subsection}


                          {\tikzset{external/figure name/.add={}{sub_}}

...


                              %
                      uses main_secondsection_sub_0.pdf,
                      main_secondsection_sub_1.pdf, ...

}


                          % uses
                      main_secondsection_2.pdf, main_secondsection_3.pdf, ...

}

\tikzappendtofigurename{ (math image) suffix} ¶

Appends (math image) suffix to the actual value of figure name.

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

Configuration option for eps output or MiKTeX:

Since the external lib works by means of system calls, it has to be modified to fit the local system. This is necessary for MiKTeX since it uses a different option to enable these system calls. It is also necessary for eps output since this involves a different set of utilities.

Note that the most important part is to enable system calls. This is typically done by typesetting your document with pdflatex -shell-escape or pdflatex -enable-write18 (MiKTeX). These options need to be configured in your TeX editor. Besides this step, one may want to configure the system call:

/tikz/external/system call={ (math image) template} ¶

A template string used to generate system calls. Inside of (math image) 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 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-escape.¹¹⁶

For eps output, you can (and need to) use


                      \tikzset{external/system call={latex
                      \tikzexternalcheckshellescape -halt-on-error


                          -interaction=batchmode
                      -jobname "\image" "\texsource" &&


                          dvips -o "\image".ps
                      "\image".dvi}}

The argument (math image) 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={ (math image) command-line arg} (initially -shell-escape) ¶

Contains the command line option for latex which enables the \write18 feature.

For TeXLive, this is -shell-escape. For MiKTeX, the system uses -enable-write18.

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 of external files.

There are, however, some points which need your attention when you try to use

a) \ref to something in the main document inside of an externalized graphics or
b) \label in the externalized graphics which is referenced in the main document.

For point a), a \ref inside of an externalized graphics works only if you issue the required system call manually or by make. The initial configuration mode=convert with system call does not support \ref. But you can copy–paste the system call generated by mode=convert with system call and issue it manually. The reason is that \ref information is stored in the main .aux file – but this auxiliary file is not completely written when mode=convert with system call is invoked (there is a race condition). Note that \pageref is not supported (sorry). Thus: if you have \ref inside of external graphics, consider using mode=list and make or copy–paste the system call for the image(s) and issue it manually.

Point b) is realized automatically by the external library. In detail, a \label inside of an externalized graphics causes the external library to generate separate auxiliary files for every external image. These files are called (math image) 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 file.¹¹⁷

There is just a special case if a \label/\ref drawn as a tikzpicture. This is, for example, the case for the legend \ref images or for the \pgfplotslegendfromname feature. In such cases, you need to proceed as for case a) since mode=convert with system call can’t handle that stuff on its own.

In other words: a \label in an external document works automatically, just translate the main document often enough. A \ref might need manual adjustments as described for case a) above.

Operation Modes

/tikz/external/mode=convert with system call|list and make|\(\dotsc \) (initially convert with system call) ¶

This allows to change the default operation mode. There are a handful of choices possible, all of them are described in detail in the PGF/TikZ manual (Section “Externalization Library”). The most useful ones are probably the initial configuration convert with system call and the specialized choice list and make.

The choice list and make configures the library to check if there are already external graphics and uses them. If there are no graphics, the library will skip the figure. However, it will also generate a makefile to generate the graphics, and a list of all required graphics files.

It is not required to use make: the library expects you to generate the images somehow and it doesn’t care about the “how”. Using make -f (math image) name-of-tex-file.makefile -j 2 allows parallel execution which might, indeed, be an option. Furthermore, the makefile also supports file dependencies: if one of your data tables has been updated, the external graphics will be remade automatically. pgfplots tells the external library about any file dependencies (input files and tables).

The two modes have the following characteristics:

1. convert with system call is automatic and does everything on the fly. However, it can’t work with \ref and/or \label information in external pictures.
2. list and make requires either manual (by issuing the system calls manually) or semiautomatic conversion (using the generated main.makefile), and multiple runs of pdflatex. The generated Makefile can be processed in parallel. Furthermore, list and make provides full support for \ref and \label: any \label defined inside of an externalized graphics is still available for the main document.

If you have legends with legend to name or \label/\ref, you need to generate the graphics defining the \label (or legend to name), then run pdflatex twice on the main document. Afterwards, you can externalize the legend graphics.

The complete reference documentation and remaining options are documented in the PGF/TikZ manual (Section “Externalization Library”). This reference also contains information about

• how to use \tikzset{external/force remake} and \tikzset{external/remake next} to remake selected figures,
• how to disable the externalization partially with \tikzset{external/export=false} or completely with \tikzexternaldisable,
• how to optimize the speed of the conversion process using \tikzset{external/optimize command away=\myExpensiveMacro},
• how to add further remake-dependencies with \tikzpicturedependsonfile{name} and/or \tikzexternalfiledependsonfile{external file}{name},
• examples how to enable png export,
• how to typeset such a document without pgf installed or
• how to provide workarounds with .pdf images and bounding box restrictions.

Using the Library Without pgf or pgfplots Installed

There is a small replacement package tikzexternal.sty which can be used once every figure has been exported. The idea is to comment \usepackage{tikz} and \usepackage{pgfplots} and write \usepackage{tikzexternal} instead:

% \usepackage{tikz} % \usepackage{pgfplots} \usepackage{tikzexternal}


                      \tikzexternalize% activate externalization

\begin{document}


                      \begin{tikzpicture}

...


                      \end{tikzpicture}

... \end{document}

You do not need pgf, TikZ or pgfplots installed. What you need is tikzexternal.sty and all generated figures (consisting of the image files, ‘.pdf’ and the ‘.dpth’ files containing information of the baseline option). The file tikzexternal.sty is shipped with pgf in the directory

latex/pgf/utilities/tikzexternal.sty

and a copy is shipped with pgfplots in


                  tex/generic/pgfplots/oldpgfcompatib/pgfplotsoldpgfsupp_tikzexternal.sty

Just copy the file into your directory and rename it to tikzexternal.sty.

Attention:

The small replacement package doesn’t support key–value interfaces. Thus, it is necessary 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. Also, you may want to define a dummy macro \pgfplotsset if you have used \pgfplotsset.

¹¹⁵ These counters are stored into different macros. In other words: no TeX register will be needed.

¹¹⁶ 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.

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

8.1.2Using the Externalization Framework of pgf “By Hand”¶

Another way to export TeX pictures to single graphics files is to use the externalization framework of pgf, which requires more work but works more generally than the external library. The basic idea is to encapsulate the desired parts with

\beginpgfgraphicnamed{ (math image) output file name}

(math image) picture contents

\endpgfgraphicnamed.

Furthermore, one needs to tell pgf the name of the main document using

\pgfrealjobname{ (math image) the real job’s name}

in the preamble. This enables two different modes:

1. The first is the normal typesetting mode. LaTeX checks whether a file named output file name with one of the accepted file extensions exists – if that is the case, the graphics file is included with \pgfimage and the picture contents is skipped. If no such file exists, the picture contents is typeset normally. This mode is applied if \jobname equals the real job’s name.
2. The second mode applies if \jobname equals output file name, it initiates the “conversion mode” which is used to write the graphics file output file name. In this case, only picture contents is written to \jobname, the complete rest of the LaTeX is processed as normal, but it is silently discarded.

This mode needs to be started manually with pdflatex --jobname output file name for every externalized graphics file.

A complete example may look as follows.

\documentclass{article} \usepackage{pgfplots}


                    \pgfrealjobname{test}

\begin{document} \begin{figure}


                        \beginpgfgraphicnamed{testfigure}


                            \begin{tikzpicture}


                                \begin{axis}


                                    \addplot {x^2};


                                \end{axis}


                            \end{tikzpicture}


                        \endpgfgraphicnamed


                        \caption{Our
                first external
                graphics example}

\end{figure} \begin{figure}


                        \beginpgfgraphicnamed{testfigure2}


                            \begin{tikzpicture}


                                \begin{axis}


                                    \addplot {x^3};


                                \end{axis}


                            \end{tikzpicture}


                        \endpgfgraphicnamed


                        \caption{A
                second graphics}

\end{figure} \end{document}

The file is named test.tex, and it is processed (for example) with

pdflatex test

Now, we type

pdflatex --jobname testfigure test pdflatex --jobname testfigure2 test

to enter conversion mode. These last calls will only write the contents of our named graphics environments, one for (math image) testfigure and one for testfigure2 into the respective output files testfigure.pdf and testfigure2.pdf.

In summary, one needs \pgfrealjobname and calls pdflatex --jobname (math image) graphics file for every externalized graphics environment. Please note that it is absolutely necessary to use the syntax above, not \begin{pgfgraphicnamed}.

These steps are explained in much more detail in Section“Externalizing Graphics” of the PGF/TikZ manual.

Attention:

Do not forget a correct \pgfrealjobname statement! If it is missing, externalization simply won’t work. If it is wrong, any call to LaTeX will produce empty output files.

It should be noted that this approach of image externalization is not limited to TikZ picture environments. In fact, it collects everything between the begin and end statements into the external file. It is implicitly assumed that the encapsulated stuff is one box, but you can also encapsulate complete paragraphs using something like the LaTeX minipage (or a \vbox which is not as powerful but does not affect the remaining document that much).

/pgf/images/aux in dpth=true|false (initially false) ¶

If this boolean is set to true, any \label information generated inside of the external image is stored into the already mentioned .dpth file. The main document can thus reference label information of externalized parts of the document (although you may need to run latex several times).

Label support is provided for \ref, and probably \cite. The \pageref command is only partially supported.

Using the Library Without pgf Installed

Simply uncomment the packages \usepackage{tikz} and \usepackage{pgfplots} and use


                \long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{%

\begingroup


                    \setbox1=\hbox{\includegraphics{#1}}%

\openin1=#1.dpth \ifeof1 \box1 \else


                        \read1
                to\pgfincludeexternalgraphicsdp \closein1


                        \dimen0=\pgfincludeexternalgraphicsdp\relax


                        \hbox{\lower\dimen0
                \box1 }%

\fi \endgroup }

instead. This will include the generated graphics files (and it will respect the baseline information stored in .dpth files). Consequently, you won’t need pgf or pgfplots installed. See Section“Externalizing Graphics” of the PGF/TikZ manual for details.

Manual for Package pgfplots 2D/3D Plots in LATeX, Version 1.18.1 http://sourceforge.net/projects/pgfplots

Import/Export From Other Formats

8.1Export to pdf/eps

8.1.1Using the Automatic Externalization Framework of TikZ¶

8.1.2Using the Externalization Framework of pgf “By Hand”¶

Manual for Package pgfplots
2D/3D Plots in LATeX, Version 1.18.1
http://sourceforge.net/projects/pgfplots