% 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: