path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex

\section{Utilities and Basic Level Commands}
\label{sec:pgfplots:lowlevel}
This section documents commands which provide access to more basic elements of \PGFPlots. Most of them are closely related to the basic level of \pgfname, especially various point commands which are specific to an axis. Some of them are general purpose utilities like loops.

However, most elements in this section are only interesting for advanced users -- and perhaps only for special cases.

\subsection{Utility Commands}

\begin{command}{\foreach \meta{variables} |in| \meta{list} \marg{commands}}
	A powerful loop command provided by \Tikz, see~\cite[Section Utilities]{tikz}.
\begin{codeexample}[]
\foreach \x in {1,2,...,4} {Iterating \x. }%
\end{codeexample}

	A \PGFPlots\ related example could be
\begin{codeexample}[code only]
\foreach \i in {1,2,...,10} {\addplot table {datafile\i}; }%
\end{codeexample}
\end{command}

\begin{command}{\pgfplotsforeachungrouped \meta{variable} |in| \meta{list} \marg{command}}
	A specialised variant of |\foreach| which can do two things: it does not introduce extra groups while executing \meta{command} and it allows to invoke the math parser for (simple!) \meta{$x_0$}|,|\meta{$x_1$}|,...,|\meta{$x_n$} expressions.

\begin{codeexample}[]
\def\allcollected{}
\pgfplotsforeachungrouped \x in {1,2,...,4} {Iterating \x. \edef\allcollected{\allcollected, \x}}%
All collected = \allcollected.
\end{codeexample}

	A more useful example might be to work with tables. The following example is taken from \PGFPlotstable:

\begin{codeexample}[code only]
\pgfplotsforeachungrouped \i in {1,2,...,10} {%
	\pgfplotstablevertcat{\output}{datafile\i} % appends `datafile\i' -> `\output'
}%
% since it was ungrouped, \output is still defined (would not work
% with \foreach)
\end{codeexample}

	\paragraph{Remark: } The special syntax \meta{list}=\meta{$x_0$}|,|\meta{$x_1$}|,...,|\meta{$x_n$}, i.e.\ with two leading elements, followed by dots and a final element, invokes the math parser for the loop. Thus, it allows larger number ranges than any other syntax if |/pgf/fpu| is active.  In all other cases, |\pgfplotsforeachungrouped| invokes |\foreach| and provides the results without \TeX\ groups.
	
	Keep in mind that inside of an axis environment, all loop constructions (including custom loops, |\foreach| and |\pgfplotsforeachungrouped|) need to be handled with care: loop arguments can only be used in places where they are immediately evaluated; but \PGFPlots\ postpones the evaluation of many macros. For example, to loop over something and to generate axis descriptions of the form |\node at (axis cs:\i,0.5)....|, the loop macro |\i| will be evaluated in |\end{axis}| -- but at that time, the loop is over and its value is lost. The correct way to handle such an application is to \emph{expand} the loop variable \emph{explicitly}. For example:
\begin{codeexample}[code only]
\pgfplotsforeachungrouped \i/\j in {
	1 / a,
	2 / b,
	3 / c
}{
	\edef\temp{\noexpand\node at (axis cs: \i,0.5) {\j};}
	% \show\temp % lets TeX show you what \temp contains
	\temp
}
\end{codeexample}
	The example generates three loop iterations: |\i=1|, |\j=a|; then |\i=2|, |j=b|; then |\i=3|, |\j=c|. Inside of the loop body, it expands them and assigns the result to a macro using an ``expanded definition'', |\edef|. The result no longer contains either |\i| or |\j| (since these have been expanded). Then, it invokes the resulting macro. Details about the \TeX\ command |\edef| and expansion control can be found in the document \href{file:TeX-programming-notes.pdf}{TeX-programming-notes.pdf} which comes with \PGFPlots.
\end{command}

\begin{command}{\pgfplotsinvokeforeach\marg{list} \marg{command}}
	A variant of |\pgfplotsforeachungrouped| (and such also of |\foreach|) which replaces any occurrence of |#1| inside of \meta{command} once for every element in \meta{list}. Thus, it actually assumes that \marg{command} is like a |\newcommand| body.

	In other words, \meta{command} is invoked for every element of \meta{list}. The actual element of \meta{list} is available as |#1|.

	As |\pgfplotsforeachungrouped|, this command does \emph{not} introduce extra scopes (i.e.\ it is ungrouped as well).

	The difference to |\foreach \x in |\meta{list}\marg{command} is subtle: the |\x| would \emph{not} be expanded whereas |#1| is. 
\begin{codeexample}[]
\pgfkeys{
  otherstyle a/.code={[a]},
  otherstyle b/.code={[b]},
  otherstyle c/.code={[c]},
  otherstyle d/.code={[d]}}
\pgfplotsinvokeforeach{a,b,c,d}        	
	{\pgfkeys{key #1/.style={otherstyle #1}}}
Invoke them: 
\pgfkeys{key a} \pgfkeys{key b} 
\pgfkeys{key c} \pgfkeys{key d}
\end{codeexample}
The counter example would use a macro (here |\x|) as loop argument:
\begin{codeexample}[]
\pgfkeys{
  otherstyle a/.code={[a]},
  otherstyle b/.code={[b]},
  otherstyle c/.code={[c]},
  otherstyle d/.code={[d]}}
\pgfplotsforeachungrouped \x in {a,b,c,d}        	
	{\pgfkeys{key \x/.style={otherstyle \x}}}
Invoke them: 
\pgfkeys{key a} \pgfkeys{key b}
\pgfkeys{key c} \pgfkeys{key d}
\end{codeexample}

	\paragraph{Restrictions:} you can't nest this command yet (since it does not introduce protection by scopes).
\end{command}

\begin{command}{\pgfmathparse\marg{expression}}
	Invokes the \pgfname\ math parser for \meta{expression} and defines \declareandlabel{\pgfmathresult} to be the result.
\begin{codeexample}[]
\pgfmathparse{1+41}

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}


\begin{command}{\pgfplotstableread\marg{file}}
	Please refer to the manual of \PGFPlotstable, |pgfplotstable.pdf|, which is part of the \PGFPlots-bundle.
\end{command}
\begin{command}{\pgfplotstabletypeset\marg{\textbackslash macro}}
	Please refer to the manual of \PGFPlotstable, |pgfplotstable.pdf|, which is part of the \PGFPlots-bundle.
\end{command}

\begin{command}{\pgfplotsiffileexists\marg{filename}\marg{true code}\marg{false code}}
	Invokes \meta{true code} if \meta{filename} exists and \meta{false code} if not. Can be used in looping macros, for example to plot every data file until there are no more of them.
\end{command}
\begin{command}{\pgfplotsutilifstringequal\marg{first}\marg{second}\marg{true code}\marg{false code}}
	A simple ``strcmp'' tool which invokes \meta{true code} if \meta{first} $=$\meta{second} and \meta{false code} otherwise. This does not expand macros.
\end{command}


\begin{commandlist}{\pgfkeys,\pgfeov,\pgfkeysvalueof,\pgfkeysgetvalue}
	These commands are part of the \Tikz\ way of specifying options, its sub-package |pgfkeys|. The |\pgfplotsset| command is actually nothing but a wrapper around |\pgfkeys|.

	A short introduction into |\pgfkeys| can be found in~\cite{keyvalintro} whereas the complete reference is, of course, the \Tikz\ manual~\cite{tikz}.

	The key |\pgfkeysvalueof|\marg{key name} expands to the value of a key; |\pgfkeysgetvalue|\marg{key name}\marg{\textbackslash macro} stores the value of \meta{key name} into \meta{\textbackslash macro}. The |\pgfeov| macro is used to delimit arguments for code keys in |\pgfkeys|, please refer to the references mentioned above.
\end{commandlist}

\subsection[Commands Inside Of PGFPlots Axes]{Commands Inside Of {\normalfont\PGFPlots} Axes}
\begin{command}{\autoplotspeclist}
This command should no longer be used, although it will be kept as technical implementation detail. Please use the `|cycle list|' option, Section~\ref{sec:cycle:list}.
\end{command}

\begin{command}{\logten}
Expands to the constant $\log(10)$. Useful for logplots because $\log(10^i) = i\log(10)$. This command is only available inside of a \Tikz-picture.
\end{command}

\begin{command}{\pgfmathprintnumber\marg{number}}
Generates pretty--printed output\footnote{This method was previously \texttt{\textbackslash prettyprintnumber}. Its functionality has been included into \PGF\ and the old command is now deprecated.} for \meta{number}. This method is used for every tick label.

The number is printed using the current number printing options, see the manual of \PGFPlotstable\ which comes with this package for the different number styles, rounding precision and rounding methods.
\end{command}

\begin{command}{\numplots}
	Inside of any of the axis environments, associated style, option or command, |\numplots| expands to the total number of  plots.
\end{command}
\begin{command}{\numplotsofactualtype}
	Like |\numplots|, this macro returns the total number of plots which have the same plot handler. Thus, if you have |sharp plot| active, it returns the number of all |sharp plots|. If you have |ybar| active, it returns the number of |ybar| plots and so on.
\end{command}

\begin{command}{\plotnum}
	Inside of |\addplot| or any associated style, option or command, |\plotnum| expands to the current plot's number, starting with~$0$.
\end{command}

\begin{command}{\plotnumofactualtype}
	Like |\plotnum|, but it returns the number among all plots of the same type. The number of all such plots is available using |\numplotsofactualtype|.	
\end{command}

\begin{command}{\coordindex}
	Inside of an |\addplot| command, this macro expands to the number of the actual coordinate (starting with~$0$).

	It is useful together with |x filter| or |y filter| to (de)select coordinates.
\end{command}

\subsection{Path Operations}

\begin{commandlist}{\path,\draw,\fill,\node,\matrix}
	These commands are \Tikz\ drawing commands all of which are documented in~\cite{tikz}. They are used to draw or fill paths, generate text nodes or aligned text matrices. They are equivalent to 
	\pgfmanualpdflabel{/tikz/draw}{}|\path[draw]|, 
	\pgfmanualpdflabel{/tikz/fill}{}|\path[fill]|, 
	\pgfmanualpdflabel{/tikz/node}{}|\path[node]|, 
	\pgfmanualpdflabel{/tikz/matrix}{}|\path[matrix]|, 
	respectively.
\end{commandlist}
\begin{pathoperation}{--}{\meta{coordinate}}
	A \Tikz\ path operation which connects the current point (the last one before |--|) and \meta{coordinate} with a straight line.
\end{pathoperation}
{\catcode`\|=12
\begin{pathoperation}[noindex]{|-}{\meta{coordinate}}
\pgfmanualpdflabel[\catcode`\|=12 ]{|-}{}%
	A \Tikz\ path operation which connects the current point and \meta{coordinate} with \emph{two} straight lines: first vertical, then horizontal.
\end{pathoperation}

\begin{pathoperation}[noindex]{-|}{\meta{coordinate}}
\pgfmanualpdflabel[\catcode`\|=12 ]{-|}{}%
	A \Tikz\ path operation which connects the current point and \meta{coordinate} with \emph{two} straight lines: first horizontal, then vertical.
\end{pathoperation}
}

\begin{keylist}{/tikz/xshift=\marg{dimension},/tikz/yshift=\marg{dimension}}
	These \Tikz\ keys allow to shift something by \meta{dimension} which is any \TeX\ size (or expression).
\end{keylist}


\begin{command}{\pgfplotsextra\marg{low-level path commands}}
	A command to execute \meta{low-level path commands} in a \PGFPlots\ axis. Since any drawing commands inside of an axis need to be postponed until the axis is complete and the scaling has been initialised, it is not possible to simply draw any paths.
	Instead, it is necessary to draw them as soon as the axis is finished. This is done automatically for every \Tikz\ path -- and it is also done manually if you write |\pgfplotsextra|\marg{commands}.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[xmin=0,xmax=3,ymin=0,ymax=5]
	\pgfplotsextra{%
		\pgfpathmoveto{\pgfplotspointaxisxy{1}{2}}%
		\pgfpathlineto{\pgfplotspointaxisxy{2}{4}}%
		\pgfusepath{stroke}%
	}
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	The example above initializes an axis and executes the basic level path commands as soon as the axis is ready. The execution of multiple |\path|, |\addplot| and |\pgfplotsextra| commands is in the same sequence as they occur in the environment\footnote{Except for stacked plots where the sequence may be reverse, see the key \texttt{reverse stack plots}.}.%
\end{command}

\begin{command}{\pgfplotspathaxisoutline}
	Generates a path which resembles the outline of the current axis. This path is used for clip paths and the background paths (if any).
\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 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.

	These commands are used for |rel axis cs|.

	Please note that the transformations are only initialised if the axis is complete! This means you need to provide |\pgfplotsextra|.
\end{commandlist}

\begin{commandlist}{%
	\pgfplotspointdescriptionxy\marg{$x$ fraction}\marg{$y$ fraction},%
	\pgfplotsqpointdescriptionxy\marg{$x$ fraction}\marg{$y$ fraction}}%
	Point commands such that |{0}{0}| is the lower left corner of the axis' bounding box and |{1}{1}| the upper right one; everything else is in between. The `|q|' variant is quicker as it doesn't invoke the math parser on its arguments.

	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 the macro which operates on absolute positions, |\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 canvas $x$, $y$ or $z$ unit vectors.

	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}

\begin{commandlist}{%
	\pgfplotsunitxlength,%
	\pgfplotsunitylength,%
	\pgfplotsunitzlength,%
	\pgfplotsunitxinvlength,%
	\pgfplotsunityinvlength,%
	\pgfplotsunitzinvlength}%
	Macros which expand to the vector length $\lVert x_i \rVert$ of the respective unit vector $x_i$ or the inverse vector length, $1/\lVert x_i \rVert$. These macros can be used inside of |\pgfmathparse|, for example.

	The $x_i$ are the |\pgfplotspointunitx| variants.
\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.
	
	The desired axis is uniquely identified by a three character string, provided as first argument to the command. The first of the three characters is `|0|' if the $x$ coordinate of the specified axis passes through the lower axis limit. It is `|1|', if the $x$ coordinate of the specified axis passes through the upper axis limit. Furthermore, it is `|2|' if it passes through the origin. The second character is also either |0|, |1| or |2| and it characterizes the position on the $y$ axis. The third character is for the third dimension, the $z$ axis. It should be left at `|0|' for two dimensional plots. However, \emph{one} of the three characters should be `|v|', meaning the axis \underline varies. For example, |v01| denotes $\{ (x,y_{\text{min}},z_{\text{max}}) \vert x \in \R \}$.
	
	The second argument, \meta{coordinate} is the logical coordinate on that axis. Since two coordinates of the axis are fixed, \meta{coordinate} refers to the \underline varying component of the axis. It must be a number without unit; no math expressions are supported here.

	The third argument \meta{normal distance} is a dimension like |10pt|. It shifts the coordinate away from the designated axis in direction of the outer normal vector. The outer normal vector always points away from the axis. It is computed using
	|\pgfplotspointouternormalvectorofaxis|.

	There are several variants of this command which are documented in the source code. One of them is particularly useful:
\end{command}

\begin{command}{\pgfplotsqpointoutsideofaxisrel\marg{three-char-string}\marg{axis fraction}\marg{normal distance}}
	This point coordinate is a variant of |\pgfplotsqpointoutsideofaxis| which allows to provide an \meta{axis fraction} instead of an absolute coordinate. The fraction is a number between $0$ (lower axis limit) and $1$ (upper axis limit), i.e.\ it is given in percent of the total axis. It is possible to provide negative values or values larger than one.

	The |\pgfplotsqpointoutsideofaxisrel| command is similar in spirit to |rel axis cs|.

	There is one speciality in conjunction with reversed axes: if the axis has been reversed by |x dir=reverse| and, in addition, |allow reversal of rel axis cs| is true, the value $0$ denotes the \emph{upper} limit while $1$ denotes the \emph{lower} limit. The effect is that coordinates won't change just because of axis reversal.
\index{allow reversal of rel axis cs}%
\end{command}

\begin{command}{\pgfplotspointouternormalvectorofaxis\marg{three-char-string}}
	A point command which yields the outer normal vector of the respective axis. The normal vector has length $1$ (computed with |\pgfpointnormalised|). It is the same normal vector used inside of |\pgfplotsqpointoutsideofaxis| and its variants.

	The output of this command will be cached and re-used during the lifetime of an axis. 
\end{command}

\begin{command}{\pgfplotsticklabelaxisspec\marg{x, y or z}}
	Expands to the three-character-identification for the axis containing tick labels for the chosen axis, either \meta{x}, \meta{y} or \meta{z}.
\end{command}

\begin{command}{\pgfplotsvalueoflargesttickdimen\marg{x, y or z}}
	Expands to the largest distance of a tick position to its tick label bounding box in direction of the outer unit normal vector. It does also include the value of the |ticklabel shift| key.

	This value is used for |ticklabel cs|.
\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.

	For |\pgfplotsmathfloatviewdepthxyz|, the arguments are parsed as floating point numbers and the result is encoded in floating point. A fixed point representation can be generated with |\pgfmathfloattofixed{\pgfmathresult}|.

	For |\pgfplotsmathviewdepthxyz|, \TeX\ arithmetics is employed for the inner product and the result is assigned in fixed point. This is slightly faster, but has considerably smaller data range.

	Both commands can only be used \emph{inside} of a three dimensional \PGFPlots\ axis (as soon as the axis is initialised, see |\pgfplotsextra|). 
\end{commandlist}

\begin{texif}{pgfplotsthreedim}
	A \TeX\ |\if| which evaluates the \meta{true code} if the axis is three dimensional and the \meta{else code} if not.
\end{texif}

\subsection{Accessing Axis Limits}
It is also possible to access axis limits during the visualization phase, i.e.\ during |\end{axis}|. Please refer to the reference documentation for |xmin| on page~\pageref{page:access:limits}.

\subsection{Layer Access}
\begin{command}{\pgfplotsonlayer\marg{layer name}}
    A low-level command which will check if the current axis has layer support activated and, if so, calls |\pgfonlayer|\marg{layer name}.

    There must be a |\endpgfplotsonlayer| to delimit the environment.
\end{command}
\begin{command}{\endpgfplotsonlayer}
    The end of |\pgfplotsonlayer|.
\end{command}

\begin{command}{\pgfonlayer\marg{layer name}}
    A low-level command of \PGF\ which will collect everything until the matching |\endpgfonlayer| into layer \meta{layer name}.

    The \meta{layer name} must be active, i.e.\ it must be part of the layer names of |set layers|. 
    
    The only special case is if you call |\pgfdeclarelayer{discard}| somewhere: this special layer has a ``magical name'' which serves as |/dev/null| if it is enabled using |\pgfonlayer{discard}|: it does not need to be active and everything assigned to this layer will be thrown away if it is not part of the layer name configuration.

    There must be a |\endpgfonlayer| to delimit the environment.
\end{command}
\begin{command}{\endpgfonlayer}
    The end of |\pgfonlayer|.
\end{command}


\begin{command}{\pgfsetlayers\marg{layer list}}
	This is a low-level command of \PGF. At the time of this writing, it is the only way to tell \PGF\ which layers it shall use for the current / next picture. It is used implicitly by |set layers|.
\end{command}