summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex365
1 files changed, 365 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
new file mode 100644
index 00000000000..5c5a1738bc8
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
@@ -0,0 +1,365 @@
+% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>.
+%
+% This program can be redistributed and/or modified under the terms
+% of the LaTeX Project Public License Distributed from CTAN
+% archives in directory macros/latex/base/lppl.txt.
+
+
+\section{Creating Plots}
+
+\label{section-plots}
+
+This section describes the |pgfbaseplot| package.
+
+\begin{package}{pgfbaseplot}
+ This package 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{package}
+
+\subsection{Overview}
+
+\subsubsection{When Should One Use PGF for Generating Plots? }
+
+There exist many powerful programs that produce plots, examples are
+\textsc{gnuplot} or \textsc{mathematica}. These programs can produce
+two different kinds of output: First, they can output a complete plot
+picture in a certain format (like \pdf) that includes all low-level
+commands necessary for drawing the complete plot (including axes and
+labels). Second, they can usually also produce ``just plain data'' in
+the form of a long list of coordinates. Most of the powerful programs
+consider it a to be ``a bit boring'' to just output tabled data and
+very much prefer to produce fancy pictures. Nevertheless, when coaxed,
+they can also provide the plain data.
+
+The plotting mechanism described in the following deals only with
+plotting data given in the form of a list of coordinates. Thus, this
+section is about using \pgfname\ to turn lists of coordinates into
+plots.
+
+\emph{Note that is often not necessary to use \pgfname\ for this.}
+Programs like \textsc{gnuplot} can produce very sophisticated plots
+and it is usually much easier to simply include these plots as a
+finished \textsc{pdf} or PostScript graphics.
+
+However, there are a number of reasons why you may wish to invest time
+and energy into mastering the \pgfname\ commands for creating plots:
+
+\begin{itemize}
+\item
+ Virtually all plots produced by ``external programs'' use different
+ fonts from the one used in your document.
+\item
+ Even worse, formulas will look totally different, if they can be
+ rendered at all.
+\item
+ Line width will usually be too large or too small.
+\item
+ Scaling effects upon inclusion can create a mismatch between sizes
+ in the plot and sizes in the text.
+\item
+ The automatic grid generated by most programs is mostly
+ distracting.
+\item
+ The automatic ticks generated by most programs are cryptic
+ numerics. (Try adding a tick reading ``$\pi$'' at the right point.)
+\item
+ Most programs make it very easy to create ``chart junk'' in a most
+ convenient fashion. All show, no content.
+\item
+ Arrows and plot marks will almost never match the arrows used in the
+ rest of the document.
+\end{itemize}
+
+The above list is not exhaustive, unfortunately.
+
+
+\subsubsection{How PGF Handles Plots}
+
+\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}{\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: