summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex73
1 files changed, 50 insertions, 23 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
index 87c87058fc1..0a63ad07dce 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
@@ -1,4 +1,7 @@
+
\section{Import/Export From Other Formats}
+{
+\tikzset{external/figure name/.add={}{importexport_}}%
\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.
@@ -22,7 +25,7 @@ It is possible to export images to single \pdf-documents using routines of \pgfn
\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 writes the resulting images using system calls of the form |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|.
+ \item The library writes the resulting images using system calls of the form |pdflatex --jobname |\meta{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
@@ -31,7 +34,7 @@ The only steps which are necessary is to use
|\tikzexternalize|
-\noindent somewhere in your document's preamble. No further modification to the document is necessary. Suppose we have a file called |test.tex|:
+\noindent 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|:
\begin{codeexample}[code only]
\documentclass{article}
@@ -66,7 +69,7 @@ pdflatex -shell-escape test
\end{codeexample}
\noindent 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 |tikzpicture|s as such are no longer considered (you need a different command line switch for Mik\TeX, see the |shell escape| option).
-If a figure shall be remade, one can simply delete all or selected graphics files and re-generate them. Alternatively, one can use the command |\tikzset{external/force remake}| somewhere in the document to remake every following picture automatically.
+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:
\begin{itemize}
@@ -91,7 +94,7 @@ There are three ways to modify the file names of externalized figures:
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 \marg{file name}.
+ Please note that |prefix| will still be prepended to \meta{file name}.
\begin{codeexample}[code only]
\documentclass{article}
% main document, called main.tex
@@ -123,7 +126,7 @@ pdflatex -shell-escape main
Same as |\tikzsetfigurename|\marg{name}.
\end{key}
\begin{command}{\tikzsetfigurename\marg{name}}
- Changes the names of \emph{all} following figures. It is possible to change |figure name| during the document using |\tikzset{external/figure name|=\marg{name}|}|. A unique counter\footnote{These counters are stored into into different \emph{macros}. In other words: no \TeX\ register will be needed.} will be used for each different \marg{name}, and each counter will start at $0$.
+ Changes the names of \emph{all} following figures. It is possible to change |figure name| during the document using |\tikzset{external/figure name|=\marg{name}|}|. A unique counter\footnote{These counters are stored into different \emph{macros}. In other words: no \TeX\ register will be needed.} will be used for each different \meta{name}, and each counter will start at $0$.
The value of |prefix| will be applied after |figure name| has been evaluated.
\begin{codeexample}[code only]
@@ -197,9 +200,14 @@ pdflatex -shell-escape main
\end{command}
+\paragraph{Configuration option for \textsc{eps} output or Mik\TeX:} Since the |external| lib works by means of system calls, it has to be modified to fit the local system. This is necessary for Mik\TeX\ since it uses a different option to enable these system calls. It is also necessary for \textsc{eps} output since this involves a different set of utilities.
+
+Note that the \emph{most important part} is to enable system calls. This is typically done by typesetting your document with |pdflatex -shell-escape| or |pdflatex -enable-write18| (Mik\TeX). These options \emph{need to be configured in your \TeX\ editor}.
+Besides this step, one may want to configure the system call:
+
\begin{key}{/tikz/external/system call=\marg{template}}
\label{extlib:systemcall:option}
- A template string used to generate system calls. Inside of \marg{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|\marg{main file name}, but that doesn't matter).
+ A template string used to generate system calls. Inside of \meta{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|\marg{main file name}, but that doesn't matter).
The default is
\begin{codeexample}[code only]
@@ -212,15 +220,17 @@ pdflatex -shell-escape main
For |eps| output, you can (and need to) use
\begin{codeexample}[code only]
\tikzset{external/system call={latex \tikzexternalcheckshellescape -halt-on-error
- -interaction=batchmode -jobname "\image" "\texsource";
+ -interaction=batchmode -jobname "\image" "\texsource" &&
dvips -o "\image".ps "\image".dvi}}
\end{codeexample}
- The argument \marg{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.
+ The argument \meta{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.
\end{key}
\begin{key}{/tikz/external/shell escape=\marg{command-line arg} (initially -shell-escape)}
- Contains the command line option for |latex| which enables the |\write18| feature. For \TeX-Live, this is |-shell-escape|. For Mik\TeX, you should use |\tikzexternalize[shell escape=-enable-write18]|.
+ Contains the command line option for |latex| which enables the |\write18| feature.
+
+ For \TeX-Live, this is |-shell-escape|. For Mik\TeX, you should use |\tikzexternalize[shell escape=-enable-write18]|.
\end{key}
\paragraph{Support for Labels and References In External Files}
@@ -238,9 +248,9 @@ Point b) is realized automatically by the external library. In detail, a |\label
\begin{enumerate}
\item The external graphics needs to be generated together with its |.dpth| (usually automatically by \tikzname).
\item The main document includes the external graphics and copies the |.dpth| content into its main |.aux| file.
- \item The main document needs to be translated one further time to re-read its |.aux| file\footnote{Note that it is not possible to activate the content of an auxiliary file after \texttt{\textbackslash begin\{document\}} in \LaTeX.}.
+ \item The main document needs to be translated once again to re-read its |.aux| file\footnote{Note that it is not possible to activate the content of an auxiliary file after \texttt{\textbackslash begin\{document\}} in \LaTeX.}.
\end{enumerate}
-There is just one special case which occurs if a |\label|/|\ref| combination is realized itsself by 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.
+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.
@@ -256,7 +266,7 @@ In other words: a |\label| in an external document works automatically, just tra
The two modes have the following characteristics:
\begin{enumerate}
\item |convert with system call| is automatic and does everything on--the--fly. However, it \emph{can't} work with |\ref| and/or |\label| information in external pictures.
- \item |list and make| requires either manual (by calling the system calls manually) or semi--automatic conversion (using the generated \meta{main}|.makefile|), and multiple runs of |pdflatex|. The generated Makefile can be processed in parallel. Furthermore, |list and make| provides \emph{full support} for |\ref| and |\label|: any |\label| defined inside of an externalized graphics is still available for the main document.
+ \item |list and make| requires either manual (by issuing the system calls manually) or semi--automatic conversion (using the generated \meta{main}|.makefile|), and multiple runs of |pdflatex|. The generated Makefile can be processed in parallel. Furthermore, |list and make| provides \emph{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.
\end{enumerate}
@@ -268,6 +278,7 @@ The complete reference documentation and remaining options are documented in~\ci
\item how to disable the externalization partially with |\tikzset{external/|\declareandlabel{export}|=false}| or completely with |\tikzexternaldisable|,
\item how to optimize the speed of the conversion process using |\tikzset{external/optimize command away=\myExpensiveMacro}|,
\item how to add further remake-dependencies with |\tikzpicturedependsonfile|\marg{name} and/or |\tikzexternalfiledependsonfile|\marg{external file}\marg{name},
+ \item examples how to enable |png| export,
\item how to typeset such a document without \pgfname\ installed or
\item how to provide work-arounds with |.pdf| images and bounding box restrictions.
\index{External Graphics!Bounding Box Issues}
@@ -318,8 +329,8 @@ The basic idea is to encapsulate the desired parts with
\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.
+ \item The first is the normal typesetting mode. \LaTeX\ checks whether a file named \meta{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 \meta{the real job's name}.
+ \item The second mode applies if |\jobname| equals \meta{output file name}, it initiates the ``conversion mode'' which is used to write the graphics file \meta{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}
@@ -364,9 +375,9 @@ pdflatex test
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|.
+\noindent to enter conversion mode. These last calls will \emph{only} write the contents of our named graphics environments, one for \meta{testfigure} and one for \meta{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}|.
+In summary, one needs |\pgfrealjobname| and calls |pdflatex --jobname |\meta{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}.
@@ -398,13 +409,14 @@ Simply uncomment the packages |\usepackage{tikz}| and |\usepackage{pgfplots}| an
\end{codeexample}
instead. This will include the generated graphics files (and it will respect the |baseline| information stored in |.dpth| files). Consequently, you won't need \pgfname\ or \PGFPlots\ installed. See Section``Externalizing Graphics'' of~\cite{tikz} for details.
+\subsection{Importing From Matlab}
-\subsection{Exporting Mesh Data From Matlab To \PGFPlots}
+\subsubsection{Importing Mesh Data From Matlab To PGFPlots}
While it is easy to write Matlab vectors to files (using |save P.dat data -ASCII|), it is more involved to export mesh data.
The main problem is to communicate the mesh structure to \PGFPlots.
-Here is an example how to realize this task: in Matlab, we have mesh data |X|, |Y| and |Z| which are matrizes of the same size. For example, suppose we have
+Here is an example how to realize this task: in Matlab, we have mesh data |X|, |Y| and |Z| which are matrices of the same size. For example, suppose we have
\begin{codeexample}[code only]
[X,Y] = meshgrid( linspace(-1,1,5), linspace(4,5,10) );
@@ -421,9 +433,9 @@ save P.dat data -ASCII
|\addplot3[surf,mesh/rows=10,mesh/ordering=colwise,shader=interp] file {P.dat};|
-in \PGFPlots\ to read this data. We need to provide either the number of rows ($10$ here) or the number of columns -- and the ordering (which is |colwise| for Matlab matrizes).
+in \PGFPlots\ to read this data. We need to provide either the number of rows ($10$ here) or the number of columns -- and the ordering (which is |colwise| for Matlab matrices).
-An alternative which is faster in \PGFPlots\ would be to transpose the matrizes in Matlab and tell \PGFPlots\ they are in |rowwise| ordering. So, the last step becomes
+An alternative which is faster in \PGFPlots\ would be to transpose the matrices in Matlab and tell \PGFPlots\ they are in |rowwise| ordering. So, the last step becomes
\begin{codeexample}[code only]
XX=X'; YY=Y'; ZZ=Z';
@@ -434,8 +446,8 @@ save P.dat data -ASCII
|\addplot3[surf,mesh/cols=10,mesh/ordering=rowwise,shader=interp] file {P.dat};|.
-\subsection{matlab2pgfplots.m}
-This is a Matlab (tm) script which attempts to convert a matlab figure to \PGFPlots. It requires Matlab version 7.4 (or higher).
+\subsubsection{matlab2pgfplots.m}
+This is a Matlab (tm) script which attempts to convert a Matlab figure to \PGFPlots. It requires Matlab version 7.4 (or higher).
\paragraph{Attention:} The author of \PGFPlots\ does not have enough time to maintain this script as much as he wants to. In other words, it supports only a small subset of \PGFPlots. You may also want to look at |matlab2tikz|, a conversion script of Nico Schl\"omer available at
@@ -460,7 +472,7 @@ on your matlab prompt for more information about its features and its limitation
This script is experimental.
-\subsection{matlab2pgfplots.sh}
+\subsubsection{matlab2pgfplots.sh}
A \texttt{bash}-script which simply starts matlab and runs
\begin{lstlisting}
f=hgload( 'somefigure.fig' );
@@ -468,8 +480,23 @@ A \texttt{bash}-script which simply starts matlab and runs
\end{lstlisting}
See matlab2pgfplots.m above.
+\subsubsection{Importing Colormaps From Matlab}
+Occasionally, you may want to reuse your matlab |colormap| in \PGFPlots. Here is a small Matlab script which converts it to \PGFPlots:
+\begin{codeexample}[code only]
+C = colormap; % gets data of the current colormap.
+% C = colormap(jet) % gets data of "jet"
+eachnth = 1;
+I = 1:eachnth:size(C,1); % this is nonsense for eachnth=1 -- but perhaps you don't want each color.
+CC = C(I,:);
+TeXstring = [ ...
+ sprintf('\\pgfplotsset{\n\tcolormap={matlab}{\n') ...
+ sprintf('\t\trgb=(%f,%f,%f)\n',CC') ...
+ sprintf('\t}\n}\n') ]
+\end{codeexample}
+
\subsection{SVG Output}
It is possible to write every single \Tikz\ picture into a scalable vector graphics (\texttt{.svg}) file. This has nothing to do with \PGFPlots, it is a separate driver of \PGF. Please refer to~\cite[Section ``Producing HTML / SVG Output'']{tikz}.
\subsection{Generate \PGFPlots\ Graphics Within Python}
Mario Orne D\'IAZ ANAD\'ON contributed a small python script |pgfplots.py| which provides a simple interface to generate \PGFPlots\ figures from within python. It can be found in the \PGFPlots\ installation directory, in |pgfplots/scripts/pgfplots/pgfplots.py|; documentation can be found in the file.
+}