\Header{persp}{Perspective Plots}
\methalias{persp.default}{persp}
\keyword{hplot}{persp}
\keyword{aplot}{persp}
\begin{Description}\relax
This function draws perspective plots of surfaces over the
x--y plane. \code{persp} is a generic function.
\end{Description}
\begin{Usage}
\begin{verbatim}
persp(x, ...)

## Default S3 method:
persp(x = seq(0, 1, len = nrow(z)), y = seq(0, 1, len = ncol(z)), z,
      xlim = range(x), ylim = range(y), zlim = range(z, na.rm = TRUE),
      xlab = NULL, ylab = NULL, zlab = NULL, main = NULL, sub = NULL,
      theta = 0, phi = 15, r = sqrt(3), d = 1, scale = TRUE, expand = 1,
      col = "white", border = NULL, ltheta = -135, lphi = 0, shade = NA,
      box = TRUE, axes = TRUE, nticks = 5, ticktype = "simple",
      ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, y}] locations of grid lines at which the values in \code{z} are
measured.  These must be in ascending order.  By default, equally
spaced values from 0 to 1 are used.  If \code{x} is a \code{list},
its components \code{x\$x} and \code{x\$y} are used for \code{x}
and \code{y}, respectively.
\item[\code{z}] a matrix containing the values to be plotted (\code{NA}s are
allowed).  Note that \code{x} can be used instead of \code{z} for
convenience.
\item[\code{xlim, ylim, zlim}] x-, y-  and z-limits.  The plot is produced
so that the rectangular volume defined by these limits is visible.
\item[\code{xlab, ylab, zlab}] titles for the axes.  N.B. These must be
character strings; expressions are not accepted.  Numbers will be
coerced to character strings.
\item[\code{main, sub}] main and sub title, as for \code{\Link{title}}.
\item[\code{theta, phi}] angles defining the viewing direction.
\code{theta} gives the azimuthal direction and \code{phi}
the colatitude.
\item[\code{r}] the distance of the eyepoint from the centre of the plotting box.
\item[\code{d}] a value which can be used to vary the strength of
the perspective transformation.  Values of \code{d} greater
than 1 will lessen the perspective effect and values less
and 1 will exaggerate it.
\item[\code{scale}] before viewing the x, y and z coordinates of the
points defining the surface are transformed to the interval
[0,1].  If \code{scale} is \code{TRUE} the x, y and z coordinates
are transformed separately.  If \code{scale} is \code{FALSE}
the coordinates are scaled so that aspect ratios are retained.
This is useful for rendering things like DEM information.
\item[\code{expand}] a expansion factor applied to the \code{z}
coordinates. Often used with \code{0 < expand < 1} to shrink the
plotting box in the \code{z} direction.
\item[\code{col}] the color(s) of the surface facets.  Transparent colours are
ignored.  This is recycled to the \eqn{(nx-1)(ny-1)}{} facets.
\item[\code{border}] the color of the line drawn around the surface facets.
A value of \code{NA} will disable the drawing of borders.  This is
sometimes useful when the surface is shaded.
\item[\code{ltheta, lphi}] if finite values are specified for \code{ltheta}
and \code{lphi}, the surface is shaded as though it was being
illuminated from the direction specified by azimuth \code{ltheta}
and colatitude \code{lphi}.
\item[\code{shade}] the shade at a surface facet is computed as
\code{((1+d)/2)\textasciicircum{}shade}, where \code{d} is the dot product of
a unit vector normal to the facet and a unit vector in the
direction of a light source.  Values of \code{shade} close
to one yield shading similar to a point light source model
and values close to zero produce no shading.  Values in the
range 0.5 to 0.75 provide an approximation to daylight
illumination.
\item[\code{box}] should the bounding box for the surface be displayed.
The default is \code{TRUE}.
\item[\code{axes}] should ticks and labels be added to the box.  The
default is \code{TRUE}.  If \code{box} is \code{FALSE} then no
ticks or labels are drawn.
\item[\code{ticktype}] character: \code{"simple"} draws just an arrow
parallel to the axis to indicate direction of increase;
\code{"detailed"} draws normal ticks as per 2D plots.
\item[\code{nticks}] the (approximate) number of tick marks to draw on the
axes.  Has no effect if \code{ticktype} is \code{"simple"}.
\item[\code{...}] additional graphical parameters (see \code{\Link{par}}).
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The plots are produced by first transforming the
coordinates to the interval [0,1].  The surface is then viewed
by looking at the origin from a direction defined by \code{theta}
and \code{phi}.  If \code{theta} and \code{phi} are both zero
the viewing direction is directly down the negative y axis.
Changing \code{theta} will vary the azimuth and changing \code{phi}
the colatitude.

There is a hook called \code{"persp"} (see \code{\Link{setHook}})
called after the plot is completed, which is used in the
testing code to annotate the plot page.  The hook function(s) are
called with no argument.
\end{Details}
\begin{Value}
The \emph{viewing transformation matrix}, say \code{VT}, a
\eqn{4 \times 4}{4 x 4} matrix suitable for projecting 3D coordinates
\eqn{(x,y,z)}{} into the 2D plane using homogenous 4D coordinates
\eqn{(x,y,z,t)}{}.
It can be used to superimpose additional graphical elements on the 3D
plot, by \code{\Link{lines}()} or \code{\Link{points}()}, e.g.
using the function \code{trans3d} given in the last examples section
below.
\end{Value}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\Link{contour}} and \code{\Link{image}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## More examples in  demo(persp) !!
##                   -----------

# (1) The Obligatory Mathematical surface.
#     Rotated sinc function.

x <- seq(-10, 10, length= 30)
y <- x
f <- function(x,y) { r <- sqrt(x^2+y^2); 10 * sin(r)/r }
z <- outer(x, y, f)
z[is.na(z)] <- 1
op <- par(bg = "white")
persp(x, y, z, theta = 30, phi = 30, expand = 0.5, col = "lightblue")
persp(x, y, z, theta = 30, phi = 30, expand = 0.5, col = "lightblue",
      ltheta = 120, shade = 0.75, ticktype = "detailed",
      xlab = "X", ylab = "Y", zlab = "Sinc( r )"
) -> res
round(res, 3)

# (2) Add to existing persp plot :

trans3d <- function(x,y,z, pmat) {
  tr <- cbind(x,y,z,1) %*% pmat
  list(x = tr[,1]/tr[,4], y= tr[,2]/tr[,4])
}
xE <- c(-10,10); xy <- expand.grid(xE, xE)
points(trans3d(xy[,1], xy[,2], 6, pm = res), col = 2, pch =16)
lines (trans3d(x, y=10, z= 6 + sin(x), pm = res), col = 3)

phi <- seq(0, 2*pi, len = 201)
r1 <- 7.725 # radius of 2nd maximum
xr <- r1 * cos(phi)
yr <- r1 * sin(phi)
lines(trans3d(xr,yr, f(xr,yr), res), col = "pink", lwd=2)## (no hidden lines)

# (3) Visualizing a simple DEM model

data(volcano)
z <- 2 * volcano        # Exaggerate the relief
x <- 10 * (1:nrow(z))   # 10 meter spacing (S to N)
y <- 10 * (1:ncol(z))   # 10 meter spacing (E to W)
## Don't draw the grid lines :  border = NA
par(bg = "slategray")
persp(x, y, z, theta = 135, phi = 30, col = "green3", scale = FALSE,
      ltheta = -120, shade = 0.75, border = NA, box = FALSE)
par(op)
\end{ExampleCode}
\end{Examples}

