diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex new file mode 100644 index 00000000000..efe70ab6975 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex @@ -0,0 +1,319 @@ +% 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{Plot Handler Library} +\label{section-library-plothandlers} + +\begin{pgflibrary}{plothandlers} + This library packages defines additional plot handlers, see + Section~\ref{section-plot-handlers} for an introduction to plot + handlers. The additional handlers are described in the following. + + This library is loaded automatically by \tikzname. +\end{pgflibrary} + + +\subsection{Curve Plot Handlers} + +\begin{command}{\pgfplothandlercurveto} + This handler will issue a |\pgfpathcurveto| command for each point of + the plot, \emph{except} possibly for the first. As for the line-to + handler, what happens with the first point can be specified using + |\pgfsetmovetofirstplotpoint| or |\pgfsetlinetofirstplotpoint|. + + Obviously, the |\pgfpathcurveto| command needs, in addition to the + points on the path, some control points. These are generated + automatically using a somewhat ``dumb'' algorithm: Suppose you have + three points $x$, $y$, and $z$ on the curve such that $y$ is between + $x$ and $z$: +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlercurveto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + + In order to determine the control points of the curve at the point + $y$, the handler computes the vector $z-x$ and scales it by the + tension factor (see below). Let us call the resulting vector + $s$. Then $y+s$ and $y-s$ will be the control points around $y$. The + first control point at the beginning of the curve will be the + beginning itself, once more; likewise the last control point is the + end itself. +\end{command} + +\begin{command}{\pgfsetplottension\marg{value}} + Sets the factor used by the curve plot handlers to determine the + distance of the control points from the points they control. The + higher the curvature of the curve points, the higher this value + should be. A value of $1$ will cause four points at quarter + positions of a circle to be connected using a circle. The default is + $0.5$. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfsetplottension{0.75} + \pgfplothandlercurveto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfplothandlerclosedcurve} + This handler works like the curve-to plot handler, only it will + add a new part to the current path that is a closed curve through + the plot points. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerclosedcurve + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\subsection{Comb Plot Handlers} + +There are three ``comb'' plot handlers. There name stems from the fact +that the plots they produce look like ``combs'' (more or less). + +\begin{command}{\pgfplothandlerxcomb} + This handler converts each point in the plot stream into a line from + the $y$-axis to the point's coordinate, resulting in a ``horizontal + comb.'' + + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerxcomb + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfplothandlerycomb} + This handler converts each point in the plot stream into a line from + the $x$-axis to the point's coordinate, resulting in a ``vertical + comb.'' + + This handler is useful for creating ``bar diagrams.'' +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerycomb + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfplothandlerpolarcomb} + This handler converts each point in the plot stream into a line from + the origin to the point's coordinate. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerpolarcomb + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\subsection{Mark Plot Handler} + +\label{section-plot-marks} + +\begin{command}{\pgfplothandlermark\marg{mark code}} + This command will execute the \meta{mark code} for some points of the + plot, but each time the coordinate transformation matrix will be + setup such that the origin is at the position of the point to be + plotted. This way, if the \meta{mark code} draws a little circle + around the origin, little circles will be drawn at some point of the + plot. + + By default, a mark is drawn at all points of the plot. However, two + parameters $r$ and $p$ influence this. First, only every $r$th mark + is drawn. Second, the first mark drawn is the $p$th. These + parameters can be influenced using the commands below. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermark{\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + + Typically, the \meta{code} will be |\pgfuseplotmark{|\meta{plot mark + name}|}|, where \meta{plot mark name} is the name of a + predefined plot mark. +\end{command} + +\begin{command}{\pgfsetplotmarkrepeat\marg{repeat}} + Sets the $r$ parameter to \meta{repeat}, that is, only every $r$th + mark will be drawn. +\end{command} + +\begin{command}{\pgfsetplotmarkphase\marg{phase}} + Sets the $p$ parameter to \meta{phase}, that is, the first mark to + be drawn is the $p$th, followed by the $(p+r)$th, then the + $(p+2r)$th, and so on. +\end{command} + +\begin{command}{\pgfplothandlermarklisted\marg{mark code}\marg{index list}} + This command works similar to the previous one. However, marks will + only be placed at those indices in the given \meta{index list}. The + syntax for the list is the same as for the |\foreach| statement. For + example, if you provide the list |1,3,...,25|, a mark will be placed + only at every second point. Similarly, |1,2,4,8,16,32| yields marks + only at those points that are powers of two. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermarklisted + {\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}} + {1,3} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfuseplotmark\marg{plot mark name}} + Draws the given \meta{plot mark name} at the origin. The \meta{plot + mark name} must previously have been declared using + |\pgfdeclareplotmark|. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermark{\pgfuseplotmark{pentagon}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfdeclareplotmark\marg{plot mark name}\marg{code}} + Declares a plot mark for later used with the |\pgfuseplotmark| + command. + +\begin{codeexample}[] +\pgfdeclareplotmark{my plot mark} + {\pgfpathcircle{\pgfpoint{0cm}{1ex}}{1ex}\pgfusepathqstroke} +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermark{\pgfuseplotmark{my plot mark}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfsetplotmarksize\marg{dimension}} + This command sets the \TeX\ dimension |\pgfplotmarksize| to + \meta{dimension}. This dimension is a ``recommendation'' for plot + mark code at which size the plot mark should be drawn; plot mark + code may choose to ignore this \meta{dimension} altogether. For + circles, \meta{dimension} should be the radius, for other shapes it + should be about half the width/height. + + The predefined plot marks all take this dimension into account. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfsetplotmarksize{1ex} + \pgfplothandlermark{\pgfuseplotmark{*}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{textoken}{\pgfplotmarksize} + A \TeX\ dimension that is a ``recommendation'' for the size of plot + marks. +\end{textoken} + +The following plot marks are predefined (the filling color has been +set to yellow): + +\medskip +\begin{tabular}{lc} + \plotmarkentry{*} + \plotmarkentry{x} + \plotmarkentry{+} +\end{tabular} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: |