summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex178
1 files changed, 128 insertions, 50 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
index e81c8fcb7d2..09671754622 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
@@ -98,6 +98,21 @@ Invoke them:
The result is `\pgfmathresult'.
\end{codeexample}
+ \noindent The math engine in \pgfname\ typically uses \TeX's internal arithmetics. That means: it is well suited for numbers in the range $[-16384,16384]$ and has a precision of $5$ digits.
+
+ The number range is typically too small for plotting applications. \PGFPlots\ improves the number range by means of |\pgfkeys{/pgf/fpu}\pgfmathparse{1+41}| to activate the ``floating point unit'' (fpu) and to apply all following operations in floating point.
+
+ In \PGFPlots, the key |/pgfplots/use fpu| is typically on, which means that any coordinate arithmetics are carried out with the |fpu|. However, all \pgfname\ related drawing operations still use the standard math engine.
+
+ In case you ever need to process numbers of extended precision, you may want to use
+\begin{codeexample}[]
+\pgfkeys{/pgf/fpu}%
+\pgfmathparse{1000*1000}
+
+The result is `\pgfmathprintnumber{\pgfmathresult}'.
+\end{codeexample}
+ Note that results of the |fpu| are typically not in human-readable format, so |\pgfmathprintnumber| is the preferred way to typeset such numbers.
+
Please refer to \cite{tikz} for more details.
\end{command}
@@ -209,16 +224,59 @@ The number is printed using the current number printing options, see the manual
\end{command}
\subsection{Specifying Basic Coordinates}
+\label{sec:basic:coordinates}
\begin{commandlist}{%
\pgfplotspointaxisxy\marg{x coordinate}\marg{y coordinate},%
\pgfplotspointaxisxyz\marg{x coordinate}\marg{y coordinate}\marg{z coordinate}}
- Point commands like |\pgfpointxy| which take logical, absolute coordinates and return a low--level point. Every transformation from user transformations to logarithms are applied.
+ Point commands like |\pgfpointxy| which take logical, absolute coordinates and return a low--level point. Every transformation from user transformations to logarithms is applied.
Since the transformations are initialized after the axis is complete, this command needs to be postponed (see |\pgfplotsextra|).
+
+ This command is the basic--level variant of |axis cs:|\meta{x coordinate}|,|\meta{y coordinate}|,|\meta{z coordinate}.
\end{commandlist}
\begin{commandlist}{%
+ \pgfplotspointaxisdirectionxy\marg{x coordinate}\marg{y coordinate},%
+ \pgfplotspointaxisdirectionxyz\marg{x coordinate}\marg{y coordinate}\marg{z coordinate}}
+ Point commands like |\pgfpointxy| which take logical, \emph{relative} coordinates and return a low--level point. Every transformation from user transformations to logarithms is applied. The difference to |\pgfplotspointaxisxy| is that the shift of the linear transformation is skipped here (compare |disabledatascaling|).
+
+ This command is the basic--level variant of |axis direction cs:|\meta{x coordinate}|,|\meta{y coordinate}|,|\meta{z coordinate}. Please refer to the documentation of |axis direction cs| for more details.
+
+ Use this command whenever something of \emph{relative} character like directions or lengths need to be supplied. One use-case is to draw ellipses:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ xmin=-3, xmax=3,
+ ymin=-3, ymax=3,
+ extra x ticks={-1,1},
+ extra y ticks={-2,2},
+ extra tick style={grid=major},
+]
+ \draw[red] \pgfextra{
+ \pgfpathellipse{\pgfplotspointaxisxy{0}{0}}
+ {\pgfplotspointaxisdirectionxy{1}{0}}
+ {\pgfplotspointaxisdirectionxy{0}{2}}
+ % see also the documentation of
+ % 'axis direction cs' which
+ % allows a simpler way to draw this ellipse
+ };
+ \draw[blue] \pgfextra{
+ \pgfpathellipse{\pgfplotspointaxisxy{0}{0}}
+ {\pgfplotspointaxisdirectionxy{1}{1}}
+ {\pgfplotspointaxisdirectionxy{0}{2}}
+ };
+ \addplot [only marks,mark=*] coordinates { (0,0) };
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ Since the transformations are initialized after the axis is complete, this command needs to be provided either inside of a \tikzname\ |\path| command (like |\draw| in the example above) or inside of |\pgfplotsextra|.
+
+\end{commandlist}
+
+
+\begin{commandlist}{%
\pgfplotspointrelaxisxy\marg{rel x coordinate}\marg{rel y coordinate},%
\pgfplotspointrelaxisxyz\marg{rel x coordinate}\marg{rel y coordinate}\marg{rel z coordinate}}
Point commands which take \emph{relative} coordinates such that $x=0$ is the \emph{lower} $x$ axis limit and $x=1$ the \emph{upper} $x$ axis limit.
@@ -236,13 +294,80 @@ The number is printed using the current number printing options, see the manual
They are used for |axis description cs|, see Section~\ref{pgfplots:sec:axis:description:cs}.
\end{commandlist}
+\begin{commandlist}{\pgfplotspointaxisorigin}
+ A point coordinate at the origin, $(0,0,0)$. If the origin is not part of the axis limits, the nearest point on the boundary is returned instead.
+
+ This is the same coordinate as returned by the |origin| anchor.
+\end{commandlist}
+
+\begin{commandlist}{%
+ \pgfplotstransformcoordinatex\marg{x coordinate of an axis},%
+ \pgfplotstransformcoordinatey\marg{y coordinate of an axis},%
+ \pgfplotstransformcoordinatey\marg{z coordinate of an axis}}
+ Defines |\pgfmathresult| to be the low-level \PGF\ coordinate corresponding to the input argument.
+
+ The command applies any |[xyz] coord trafo| keys, data scalings and/or logarithms or whatever \PGFPlots\ does to map input coordinates to internal coordinates.
+
+ The result can be used inside of a |\pgfpointxy| statement (i.e.\ it still needs to be scaled with the respective \PGF\ unit vector).
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[xmin=0,xmax=2,ymin=0,ymax=5]
+ \pgfplotsextra{%
+ \pgfplotstransformcoordinatex{1}%
+ \let\xcoord=\pgfmathresult
+ \pgfplotstransformcoordinatey{1}%
+ \let\ycoord=\pgfmathresult
+ \pgfpathcircle
+ {\pgfqpointxy{\xcoord}{\ycoord}}
+ {5pt}%
+ \pgfusepath{fill}%
+ }%
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ The result of this command is also available as math method |transformcoordinatex| (see the documentation for |axis cs|).
+
+ Please note that the transformations are only initialised if the axis is complete. This means you need to provide |\pgfplotsextra| as is shown in the example above.
+\end{commandlist}
+
+\begin{commandlist}{%
+ \pgfplotstransformdirectionx\marg{x direction of an axis},%
+ \pgfplotstransformdirectiony\marg{y direction of an axis},%
+ \pgfplotstransformdirectiony\marg{z direction of an axis}}
+ Defines |\pgfmathresult| to be a low-level \PGF\ \emph{direction vector component}.
+
+ A direction vector needs to be \emph{added} to some coordinate in order to get a coordinate, compare the documentation for |\pgfplotspointaxisdirectionxy| and |axis direction cs|.
+
+ The argument \meta{x direction of an axis} is processed in (almost) the same way as for |\pgfplotstransformcoordinatex|. The only difference is that \emph{directions} need no shifting transformation.
+
+ The result of this command is also available as math method |transformdirectionx| (see the documentation for |axis direction cs|).
+
+ See |axis direction cs| for details and examples about this command.
+\end{commandlist}
+
+\begin{command}{\pgfplotsconvertunittocoordinate\marg{x, y or z}\marg{dimension}}
+ Converts a dimension (with unit!) to a corresponding $x$, $y$ or $z$ coordinate. The result will be written to |\pgfmathresult| (without units).
+
+ It is possible to use the result as arguments for the |\pgfpointxyz| commands.
+
+ The effect is to multiply \meta{dimension} with the inverse length of the unit vector for the specified axis. These lengths are precomputed in \PGFPlots\ so the operation is fast.
+\begin{codeexample}[code only]
+\pgfplotsconvertunittocoordinate{x}{5pt}
+% now, the command uses exactly 5pt in x direction:
+\pgfqpointxyz{\pgfmathresult}{4}{3}
+\end{codeexample}
+\end{command}
+
+
\begin{commandlist}{%
\pgfplotspointunitx,%
\pgfplotspointunity,%
\pgfplotspointunitz}%
- Low--level point commands which return the $x$, $y$ or $z$ unit vectors.
+ Low--level point commands which return the canvas $x$, $y$ or $z$ unit vectors.
- The point |\pgfplotspointxyz{1}{0}{0}| is the same as |\pgfplotspointunitx|, the |{0}{1}{0}| coordinate the unit $y$ vector and the |{0}{0}{1}| coordinate the unit $z$ vector.
+ The |\pgfplotspointunitx| is the \pgfname\ unit vector in $x$ direction.
+
+ These vectors are essentially the same as |\pgfqpointxyz{1}{0}{0}|, |\pgfqpointxyz{0}{1}{0}|, and |\pgfqpointxyz{0}{0}{1}|, respectively.
The unit $z$ vector is only defined for three dimensional axes.
\end{commandlist}
@@ -259,12 +384,6 @@ The number is printed using the current number printing options, see the manual
The $x_i$ are the |\pgfplotspointunitx| variants.
\end{commandlist}
-\begin{commandlist}{\pgfplotspointaxisorigin}
- A point coordinate at the origin, $(0,0,0)$. If the origin is not part of the axis limits, the nearest point on the boundary is returned instead.
-
- This is the same coordinate as returned by the |origin| anchor.
-\end{commandlist}
-
\begin{command}{\pgfplotsqpointoutsideofaxis\marg{three-char-string}\marg{coordinate}\marg{normal distance}}
Provides a point coordinate on one of the available four axes in case of a two dimensional figure or on one of the available twelve axes in case of a three dimensional figure.
@@ -303,47 +422,6 @@ The number is printed using the current number printing options, see the manual
This value is used for |ticklabel cs|.
\end{command}
-\begin{commandlist}{%
- \pgfplotstransformcoordinatex\marg{x coordinate of an axis},%
- \pgfplotstransformcoordinatey\marg{y coordinate of an axis},%
- \pgfplotstransformcoordinatey\marg{z coordinate of an axis}}
- Defines |\pgfmathresult| to be the low-level \PGF\ coordinate corresponding to the input argument.
-
- The command applies any |[xyz] coord trafo| keys, data scalings and/or logarithms or whatever \PGFPlots\ does to map input coordinates to internal coordinates.
-
- The result can be used inside of a |\pgfpointxy| statement (i.e.\ it still needs to be scaled with the respective \PGF\ unit vector).
-\begin{codeexample}[]
-\begin{tikzpicture}
- \begin{axis}[xmin=0,xmax=2,ymin=0,ymax=5]
- \pgfplotsextra{%
- \pgfplotstransformcoordinatex{1}%
- \let\xcoord=\pgfmathresult
- \pgfplotstransformcoordinatey{1}%
- \let\ycoord=\pgfmathresult
- \pgfpathcircle
- {\pgfqpointxy{\xcoord}{\ycoord}}
- {5pt}%
- \pgfusepath{fill}%
- }%
- \end{axis}
-\end{tikzpicture}
-\end{codeexample}
- Please note that the transformations are only initialised if the axis is complete! This means you need to provide |\pgfplotsextra| as is shown in the example above.
-\end{commandlist}
-
-\begin{command}{\pgfplotsconvertunittocoordinate\marg{x, y or z}\marg{dimension}}
- Converts a dimension (with unit!) to a corresponding $x$, $y$ or $z$ coordinate. The result will be written to |\pgfmathresult| (without units).
-
- It is possible to use the result as arguments for the |\pgfpointxyz| commands.
-
- The effect is to multiply \meta{dimension} with the inverse length of the unit vector for the specified axis. These lengths are precomputed in \PGFPlots\ so the operation is fast.
-\begin{codeexample}[code only]
-\pgfplotsconvertunittocoordinate{x}{5pt}
-% now, the command uses exactly 5pt in x direction:
-\pgfqpointxyz{\pgfmathresult}{4}{3}
-\end{codeexample}
-\end{command}
-
\begin{commandlist}{\pgfplotsmathfloatviewdepthxyz\marg{x}\marg{y}\marg{z},
\pgfplotsmathviewdepthxyz\marg{x}\marg{y}\marg{z}}
Both macros define |\pgfmathresult| to be the ``depth'' of a three dimensional point $\bar x = (x,y,z)$. The depth is defined to be the scalar product of $\bar x$ with $\vec d$, the view direction of the current axis.