% Copyright 2006 by Till Tantau % % This file may be distributed and/or modified % % 1. under the LaTeX Project Public License and/or % 2. under the GNU Free Documentation License. % % See the file doc/generic/pgf/licenses/LICENSE for more details. \section{Creating Plots} \label{section-plots} This section describes the |plot| module. \begin{pgfmodule}{plot} This module provides a set of commands that are intended to make it reasonably easy to plot functions using \pgfname. It is loaded automatically by |pgf|, but you can load it manually if you have only included |pgfcore|. \end{pgfmodule} \subsection{Overview} There are different reasons for using \pgfname\ for creating plots rather than some more powerful program such as \textsc{gnuplot} or \textsc{mathematica}, as discussed in Section~\ref{section-why-pgname-for-plots}. So, let us assume that -- for whatever reason -- you wish to use \pgfname\ for generating a plot. \pgfname\ (conceptually) uses a two-stage process for generating plots. First, a \emph{plot stream} must be produced. This stream consists (more or less) of a large number of coordinates. Second a \emph{plot handler} is applied to the stream. A plot handler ``does something'' with the stream. The standard handler will issue line-to operations to the coordinates in the stream. However, a handler might also try to issue appropriate curve-to operations in order to smooth the curve. A handler may even do something else entirely, like writing each coordinate to another stream, thereby duplicating the original stream. Both for the creation of streams and the handling of streams different sets of commands exist. The commands for creating streams start with |\pgfplotstream|, the commands for setting the handler start with |\pgfplothandler|. \subsection{Generating Plot Streams} \subsubsection{Basic Building Blocks of Plot Streams} A \emph{plot stream} is a (long) sequence of the following three commands: \begin{enumerate} \item |\pgfplotstreamstart|, \item |\pgfplotstreampoint|, and \item |\pgfplotstreamend|. \end{enumerate} Between calls of these commands arbitrary other code may be called. Obviously, the stream should start with the first command and end with the last command. Here is an example of a plot stream: \begin{codeexample}[code only] \pgfplotstreamstart \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} \newdimen\mydim \mydim=2cm \pgfplotstreampoint{\pgfpoint{\mydim}{2cm}} \advance \mydim by 3cm \pgfplotstreampoint{\pgfpoint{\mydim}{2cm}} \pgfplotstreamend \end{codeexample} \begin{command}{\pgfplotstreamstart} This command signals that a plot stream starts. The effect of this command is to call the internal command |\pgf@plotstreamstart|, which is set by the current plot handler to do whatever needs to be done at the beginning of the plot. \end{command} \begin{command}{\pgfplotstreampoint\marg{point}} This command adds a \meta{point} to the current plot stream. The effect of this command is to call the internal command |\pgf@plotstreampoint|, which is also set by the current plot handler. This command should now ``handle'' the point in some sensible way. For example, a line-to command might be issued for the point. \end{command} \begin{command}{\pgfplotstreamend} This command signals that a plot stream ends. It calls |\pgf@plotstreamend|, which should now do any necessary ``cleanup.'' \end{command} Note that plot streams are not buffered, that is, the different points are handled immediately. However, using the recording handler, it is possible to record a stream. \subsubsection{Commands That Generate Plot Streams} Plot streams can be created ``by hand'' as in the earlier example. However, most of the time the coordinates will be produced internally by some command. For example, the |\pgfplotxyfile| reads a file and converts it into a plot stream. \begin{command}{\pgfplotxyfile\marg{filename}} This command will try to open the file \meta{filename}. If this succeeds, it will convert the file contents into a plot stream as follows: A |\pgfplotstreamstart| is issued. Then, each nonempty line of the file should start with two numbers separated by a space, such as |0.1 1| or |100 -.3|. Anything following the numbers is ignored. Each pair \meta{x} and \meta{y} of numbers is converted into one plot stream point in the xy-coordinate system. Thus, a line like \begin{codeexample}[code only] 2 -5 some text \end{codeexample} is turned into \begin{codeexample}[code only] \pgfplotstreampoint{\pgfpointxy{2}{-5}} \end{codeexample} The two characters |%| and |#| are also allowed in a file and they are both treated as comment characters. Thus, a line starting with either of them is empty and, hence, ignored. When the file has been read completely, |\pgfplotstreamend| is called. \end{command} \begin{command}{\pgfplotxyzfile\marg{filename}} This command works like |\pgfplotxyfile|, only \emph{three} numbers are expected on each non-empty line. They are converted into points in the xyz-coordinate system. Consider, the following file: \begin{codeexample}[code only] % Some comments # more comments 2 -5 1 first entry 2 -.2 2 second entry 2 -5 2 third entry \end{codeexample} It is turned into the following stream: \begin{codeexample}[code only] \pgfplotstreamstart \pgfplotstreampoint{\pgfpointxyz{2}{-5}{1}} \pgfplotstreampoint{\pgfpointxyz{2}{-.2}{2}} \pgfplotstreampoint{\pgfpointxyz{2}{-5}{2}} \pgfplotstreamend \end{codeexample} \end{command} Currently, there is no command that can decide automatically whether the xy-coordinate system should be used or whether the xyz-system should be used. However, it would not be terribly difficult to write a ``smart file reader'' that parses coordinate files a bit more intelligently. \begin{command}{\pgfplotfunction\marg{variable}\marg{sample list}\marg{point}} This command will produce coordinates by iterating the \meta{variable} over all values in \meta{sample list}, which should be a list in the |\foreach| syntax. For each value of \meta{variable}, the \meta{point} is evaluated and the resulting coordinate is inserted into the plot stream. \begin{codeexample}[] \begin{tikzpicture}[x=3.8cm/360] \pgfplothandlerlineto \pgfplotfunction{\x}{0,5,...,360}{\pgfpointxy{\x}{sin(\x)+sin(3*\x)}} \pgfusepath{stroke} \end{tikzpicture} \end{codeexample} \begin{codeexample}[] \begin{tikzpicture}[y=3cm/360] \pgfplothandlerlineto \pgfplotfunction{\y}{0,5,...,360}{\pgfpointxyz{sin(2*\y)}{\y}{cos(2*\y)}} \pgfusepath{stroke} \end{tikzpicture} \end{codeexample} Be warnded that if the expressions that need to evaluated for each point are complex, then this command can be very slow. \end{command} \begin{command}{\pgfplotgnuplot\oarg{prefix}\marg{function}} This command will ``try'' to call the \textsc{gnuplot} program to generate the coordinates of the \meta{function}. In detail, the following happens: This command works with two files: \meta{prefix}|.gnuplot| and \meta{prefix}|.table|. If the optional argument \meta{prefix} is not given, it is set to |\jobname|. Let us start with the situation where none of these files exists. Then \pgfname\ will first generate the file \meta{prefix}|.gnuplot|. In this file it writes \begin{codeexample}[code only] set terminal table; set output "#1.table"; set format "%.5f" \end{codeexample} where |#1| is replaced by \meta{prefix}. Then, in a second line, it writes the text \meta{function}. Next, \pgfname\ will try to invoke the program |gnuplot| with the argument \meta{prefix}|.gnuplot|. This call may or may not succeed, depending on whether the |\write18| mechanism (also known as shell escape) is switched on and whether the |gnuplot| program is available. Assuming that the call succeeded, the next step is to invoke |\pgfplotxyfile| on the file \meta{prefix}|.table|; which is exactly the file that has just been created by |gnuplot|. \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,-1) grid (4,1); \pgfplothandlerlineto \pgfplotgnuplot[plots/pgfplotgnuplot-example]{plot [x=0:3.5] x*sin(x)} \pgfusepath{stroke} \end{tikzpicture} \end{codeexample} The more difficult situation arises when the |.gnuplot| file exists, which will be the case on the second run of \TeX\ on the \TeX\ file. In this case \pgfname\ will read this file and check whether it contains exactly what \pgfname\ ``would have written'' into this file. If this is not the case, the file contents is overwritten with what ``should be there'' and, as above, |gnuplot| is invoked to generate a new |.table| file. However, if the file contents is ``as expected,'' the external |gnuplot| program is \emph{not} called. Instead, the \meta{prefix}|.table| file is immediately read. As explained in Section~\ref{section-tikz-gnuplot}, the net effect of the above mechanism is that |gnuplot| is called as little as possible and that when you pass along the |.gnuplot| and |.table| files with your |.tex| file to someone else, that person can \TeX\ the |.tex| file without having |gnuplot| installed and without having the |\write18| mechanism switched on. \end{command} \subsection{Plot Handlers} \label{section-plot-handlers} A \emph{plot handler} prescribes what ``should be done'' with a plot stream. You must set the plot handler before the stream starts. The following commands install the most basic plot handlers; more plot handlers are defined in the file |pgflibraryplothandlers|, which is documented in Section~\ref{section-library-plothandlers}. All plot handlers work by setting redefining the following three macros: |\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and |\pgf@plotstreamend|. \begin{command}{\pgfplothandlerlineto} This handler will issue a |\pgfpathlineto| command for each point of the plot, \emph{except} possibly for the first. What happens with the first point can be specified using the two commands described below. \begin{codeexample}[] \begin{pgfpicture} \pgfpathmoveto{\pgfpointorigin} \pgfplothandlerlineto \pgfplotstreamstart \pgfplotstreampoint{\pgfpoint{1cm}{0cm}} \pgfplotstreampoint{\pgfpoint{2cm}{1cm}} \pgfplotstreampoint{\pgfpoint{3cm}{2cm}} \pgfplotstreampoint{\pgfpoint{1cm}{2cm}} \pgfplotstreamend \pgfusepath{stroke} \end{pgfpicture} \end{codeexample} \end{command} \begin{command}{\pgfsetmovetofirstplotpoint} Specifies that the line-to plot handler (and also some other plot handlers) should issue a move-to command for the first point of the plot instead of a line-to. This will start a new part of the current path, which is not always, but often, desirable. This is the default. \end{command} \begin{command}{\pgfsetlinetofirstplotpoint} Specifies that plot handlers should issue a line-to command for the first point of the plot. \begin{codeexample}[] \begin{pgfpicture} \pgfpathmoveto{\pgfpointorigin} \pgfsetlinetofirstplotpoint \pgfplothandlerlineto \pgfplotstreamstart \pgfplotstreampoint{\pgfpoint{1cm}{0cm}} \pgfplotstreampoint{\pgfpoint{2cm}{1cm}} \pgfplotstreampoint{\pgfpoint{3cm}{2cm}} \pgfplotstreampoint{\pgfpoint{1cm}{2cm}} \pgfplotstreamend \pgfusepath{stroke} \end{pgfpicture} \end{codeexample} \end{command} \begin{command}{\pgfplothandlerdiscard} This handler will simply throw away the stream. \end{command} \begin{command}{\pgfplothandlerrecord\marg{macro}} When this handler is installed, each time a plot stream command is called, this command will be appended to \meta{macros}. Thus, at the end of the stream, \meta{macro} will contain all the commands that were issued on the stream. You can then install another handler and invoke \meta{macro} to ``replay'' the stream (possibly many times). \begin{codeexample}[] \begin{pgfpicture} \pgfplothandlerrecord{\mystream} \pgfplotstreamstart \pgfplotstreampoint{\pgfpoint{1cm}{0cm}} \pgfplotstreampoint{\pgfpoint{2cm}{1cm}} \pgfplotstreampoint{\pgfpoint{3cm}{1cm}} \pgfplotstreampoint{\pgfpoint{1cm}{2cm}} \pgfplotstreamend \pgfplothandlerlineto \mystream \pgfplothandlerclosedcurve \mystream \pgfusepath{stroke} \end{pgfpicture} \end{codeexample} \end{command} %%% Local Variables: %%% mode: latex %%% TeX-master: "pgfmanual" %%% End: