1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
\section{Import/Export from other formats}
\label{sec:pgfplots:importexport}
This section contains information of how to single pictures into separate \pdf\ graphics files (or \eps\ graphics files). Furthermore, it explains a matlab (tm) script which allows to convert from matlab to \PGFPlots.
\subsection{Export to \pdf/\eps}
It is possible to export images to single \pdf-documents using routines of \pgfname\ and/or \Tikz.
\subsubsection{Using the Externalization framework of \pgfname\ ``by hand''}
The first way to export \TeX-pictures to single graphics files is to use the externalization framework of \pgfname.
The basic idea is to encapsulate the desired parts with
|\beginpgfgraphicnamed|\marg{output file name}
\meta{picture contents}
|\endpgfgraphicnamed|.
\noindent Furthermore, one needs to tell \pgfname\ the name of the main document using
|\pgfrealjobname|\marg{the real job's name}
\noindent in the preamble. This enables two different modes:
\begin{enumerate}
\item The first is the normal typesetting mode. \LaTeX\ checks whether a file named \marg{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 \meta{picture contents} is skipped. If no such file exists, the \meta{picture contents} is typeset normally. This mode is applied if |\jobname| equals \marg{the real job's name}.
\item The second mode applies if |\jobname| equals \marg{output file name}, it initiates the ``conversion mode'' which is used to write the graphics file \marg{output file name}. In this case, \emph{only} \meta{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 |\meta{output file name} for every externalized graphics file.
\end{enumerate}
A complete example may look as follows.
\begin{codeexample}[code only]
\documentclass{article}
\usepackage{pgfplots}
\pgfrealjobname{test}
\begin{document}
\begin{figure}
\beginpgfgraphicnamed{testfigure}
\begin{tikzpicture}
\begin{axis}
\addplot (\x,\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,\x^3);
\end{axis}
\end{tikzpicture}
\endpgfgraphicnamed
\caption{A second graphics}
\end{figure}
\end{document}
\end{codeexample}
\noindent The file is named |test.tex|, and it is processed (for example) with
\begin{codeexample}[code only]
pdflatex test
\end{codeexample}
\noindent Now, we type
\begin{codeexample}[code only]
pdflatex --jobname testfigure test
pdflatex --jobname testfigure2 test
\end{codeexample}
\noindent to enter conversion mode. These last calls will \emph{only} write the contents of our named graphics environments, one for \marg{testfigure} and one for \marg{testfigure2} into the respective output files |testfigure.pdf| and |testfigure2.pdf|.
In summary, one needs |\pgfrealjobname| and calls |pdflatex --jobname |\marg{graphics file} for every externalized graphics environment. Please note that it is absolutely necessary to use the syntax above, \emph{not} |\begin{pgfgraphicnamed}|.
These steps are explained in much more detail in Section``Externalizing Graphics'' of~\cite{tikz}. This reference also contains information about how to typeset such a document without \pgfname\ installed.
I once attempted to write a unix \texttt{bash}--script |pgf2pdf.sh| which simplifies these steps in case that every externalized graphics environment is placed into a separate file |.pgf|. Interested readers find it in the installation tree.
\paragraph{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.
\subsubsection{Using the automatic Externalization framework of \Tikz}
It is also possible to externalize graphics with the high-level library
|\usetikzlibrary{external}|
\noindent which comes with (recent versions of) \Tikz\footnote{At the time of this writing, it is only available in the CVS~$2.0$ version of \pgfname, sorry.}. It is a front-end for |\beginpgfgraphicnamed| which automatically encapsulates every picture in your document with the required externalization commands and performs commands to generate all required graphics files.
\begin{enumerate}
\item Every |\begin{tikzpicture}| $\dotsc$ |\end{tikzpicture}| gets a file name. The file name can be assigned manually with |\tikzsetnextfilename|\marg{output file name} or automatically, in which case \meta{tex file name}|-figure|\meta{number} is used with an increasing \meta{number}.
\item The library issues the required calls to |pdflatex --jobname |\marg{output file name} automatically, using the write18 system call of \TeX. It is the same framework which can be used to call |gnuplot|.
\end{enumerate}
The only steps which are necessary is to use
|\tikzexternalize|\marg{the job's real file name}
\noindent as above. No further modification to the document is necessary. Now, the example file |test.tex| of the last subsection reads as follows:
\begin{codeexample}[code only]
\documentclass{article}
\usepackage{pgfplots}
\usetikzlibrary{external}
\tikzexternalize{test}
\begin{document}
\begin{figure}
\begin{tikzpicture}
\begin{axis}
\addplot (\x,\x^2);
\end{axis}
\end{tikzpicture}
\caption{Our first external graphics example}
\end{figure}
\begin{figure}
\begin{tikzpicture}
\begin{axis}
\addplot (\x,\x^3);
\end{axis}
\end{tikzpicture}
\caption{A second graphics}
\end{figure}
\end{document}
\end{codeexample}
\noindent To enable the system calls, we type
\begin{codeexample}[code only]
pdflatex --shell-escape test
\end{codeexample}
\noindent and \LaTeX\ will now generate the required graphics files |test-figure0.pdf| and |test-figure1.pdf| automatically.
The command |\tikzset{external/force remake}| somewhere in the document can be used to remake every following picture automatically. Of course, it is also possible to simply delete every graphics file.
The library can also be configured to produce a list of figures in case system calls are undesired (or unavailable). In that case, |pdflatex --jobname |\marg{output file name} needs to be invoked for every file name listed in \meta{real file name}|.figlist|. This step can be done within a script.
The command |\tikzsetexternalprefix|\marg{file prefix} can be used to prepend a directory name to every figure, for example with
\begin{codeexample}[code only]
\tikzsetexternalprefix{figures/}
\end{codeexample}
\noindent to produce |figures/test-figure0.pdf| and |figures/test-figure1.pdf| in our example.
The complete reference documentation and remaining options are documented in the documentation for the ``PDF externalization library'' of~\cite{tikz}. This reference also contains information about how to typeset such a document without \pgfname\ installed.
\subsection{matlab2pgfplots.m}
This is a matlab (tm) script which attempts to convert a matlab figure to \PGFPlots.
The idea is to
\begin{itemize}
\item use a complete matlab figure as input,
\item acquire axis labels, axis scaling (log or normal) and legend entries,
\item acquire all plot coordinates
\end{itemize}
and write an equivalent \texttt{.pgf} file which typesets the plot with \PGFPlots.
The indention is \emph{not} to simulate matlab. It is a first step for a conversion. Type
\begin{lstlisting}
> help matlab2pgfplots
\end{lstlisting}
on your matlab prompt for more information about its features and its limitations.
This script is experimental.
\subsection{matlab2pgfplots.sh}
A \texttt{bash}-script which simply starts matlab and runs
\begin{lstlisting}
f=hgload( 'somefigure.fig' );
matlab2pgfplots( 'outputfile.pgf', 'fig', f );
\end{lstlisting}
See matlab2pgfplots.m above.
|
