diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex | 73 |
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. +} |