\Header{xyz.coords}{Extracting Plotting Structures}
\keyword{dplot}{xyz.coords}
\begin{Description}\relax
Utility for obtaining consistent x, y and z coordinates and labels
for three dimensional (3D) plots.\end{Description}
\begin{Usage}
\begin{verbatim}
xyz.coords(x, y, z, xlab=NULL, ylab=NULL, zlab=NULL, log=NULL,
    recycle=FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, y, z}] the x, y and z coordinates of a set of points.
Alternatively, a single argument \code{x} can be be provided.
In this case, an attempt is made to interpret the
argument in a way suitable for plotting.

If the argument is a formula \code{zvar $\,\tilde{\,}$ xvar + yvar},
\code{xvar}, \code{yvar} and \code{zvar} are used as x, y and z
variables;
if the argument is a list containing components \code{x},
\code{y} and \code{z}, these are assumed to define plotting coordinates;
if the argument is a matrix with three columns, the first is
assumed to contain the x values, etc.

Alternatively, two arguments \code{x} and \code{y} can be be provided.
One may be real, the other complex;
in any other case, the arguments are coerced to vectors
and the values plotted against their indices.

\item[\code{xlab, ylab, zlab}] names for the x, y and z variables to be extracted.
\item[\code{log}] character, \code{"x"}, \code{"y"}, \code{"z"} or combinations.
Sets negative values to \code{\Link{NA}} and gives a warning.
\item[\code{recycle}] logical; if \code{TRUE}, recycle (\code{\Link{rep}}) the
shorter ones of \code{x}, \code{y} or \code{z} if their lengths differ.
\end{ldescription}
\end{Arguments}
\begin{Value}
A list with the components
\begin{ldescription}
\item[\code{x}] numeric (i.e. \code{\Link{double}}) vector of abscissa values.
\item[\code{y}] numeric vector of the same length as \code{x}.
\item[\code{z}] numeric vector of the same length as \code{x}.
\item[\code{xlab}] \code{character(1)} or \code{NULL}, the axis label of \code{x}.
\item[\code{ylab}] \code{character(1)} or \code{NULL}, the axis label of \code{y}.
\item[\code{zlab}] \code{character(1)} or \code{NULL}, the axis label of \code{z}.
\end{ldescription}
\end{Value}
\begin{Author}\relax
Uwe Ligges and Martin Maechler\end{Author}
\begin{SeeAlso}\relax
\code{\Link{xy.coords}} for 2D.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
str(xyz.coords(data.frame(10*1:9, -4),y=NULL,z=NULL))

str(xyz.coords(1:6, fft(1:6),z=NULL,xlab="X", ylab="Y"))

y <- 2 * (x2 <- 10 + (x1 <- 1:10))
str(xyz.coords(y ~ x1 + x2,y=NULL,z=NULL))

str(xyz.coords(data.frame(x=-1:9,y=2:12,z=3:13),y=NULL,z=NULL,
    log="xy"))
##> Warning message: 2 x values <= 0 omitted ...
\end{ExampleCode}
\end{Examples}

