persp                package:graphics                R Documentation

Perspective Plots

Description:

     This function draws perspective plots of surfaces over the x-y
     plane. 'persp' is a generic function.

Usage:

     persp(x, ...)

     ## Default S3 method:
     persp(x = seq(0, 1, length.out = nrow(z)),
           y = seq(0, 1, length.out = 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", ...)

Arguments:

    x, y: locations of grid lines at which the values in 'z' are
          measured.  These must be in ascending order.  By default,
          equally spaced values from 0 to 1 are used.  If 'x' is a
          'list', its components 'x$x' and 'x$y' are used for 'x' and
          'y', respectively.

       z: a matrix containing the values to be plotted ('NA's are
          allowed).  Note that 'x' can be used instead of 'z' for
          convenience.

xlim, ylim, zlim: x-, y-  and z-limits.  The plot is produced so that
          the rectangular volume defined by these limits is visible.

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.

main, sub: main and sub title, as for 'title'.

theta, phi: angles defining the viewing direction. 'theta' gives the
          azimuthal direction and 'phi' the colatitude.

       r: the distance of the eyepoint from the centre of the plotting
          box.

       d: a value which can be used to vary the strength of the
          perspective transformation.  Values of 'd' greater than 1
          will lessen the perspective effect and values less and 1 will
          exaggerate it.

   scale: before viewing the x, y and z coordinates of the points
          defining the surface are transformed to the interval [0,1]. 
          If 'scale' is 'TRUE' the x, y and z coordinates are
          transformed separately.  If 'scale' is 'FALSE' the
          coordinates are scaled so that aspect ratios are retained.
          This is useful for rendering things like DEM information.

  expand: a expansion factor applied to the 'z' coordinates. Often used
          with '0 < expand < 1' to shrink the plotting box in the 'z'
          direction.

     col: the color(s) of the surface facets.  Transparent colours are
          ignored.  This is recycled to the (nx-1)(ny-1) facets.

  border: the color of the line drawn around the surface facets. The
          default, 'NULL', corresponds to 'par("fg")'. A value of 'NA'
          will disable the drawing of borders: this is sometimes useful
          when the surface is shaded.

ltheta, lphi: if finite values are specified for 'ltheta' and 'lphi',
          the surface is shaded as though it was being illuminated from
          the direction specified by azimuth 'ltheta' and colatitude
          'lphi'.

   shade: the shade at a surface facet is computed as
          '((1+d)/2)^shade', where '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 '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.

     box: should the bounding box for the surface be displayed. The
          default is 'TRUE'.

    axes: should ticks and labels be added to the box.  The default is
          'TRUE'.  If 'box' is 'FALSE' then no ticks or labels are
          drawn.

ticktype: character: '"simple"' draws just an arrow parallel to the
          axis to indicate direction of increase; '"detailed"' draws
          normal ticks as per 2D plots.

  nticks: the (approximate) number of tick marks to draw on the axes. 
          Has no effect if 'ticktype' is '"simple"'.

     ...: additional graphical parameters (see 'par').

Details:

     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 'theta' and 'phi'.  If 'theta'
     and 'phi' are both zero the viewing direction is directly down the
     negative y axis. Changing 'theta' will vary the azimuth and
     changing 'phi' the colatitude.

     There is a hook called '"persp"' (see '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.

     Notice that 'persp' interprets the 'z' matrix as a table of
     'f(x[i], y[j])' values, so that the x axis corresponds to row
     number and the y axis to column number, with column 1 at the
     bottom, so that with the standard rotation angles, the top left
     corner of the matrix is displayed at the left hand side, closest
     to the user.

     The sizes and fonts of the axis labels and the annotations for
     'ticktype="detailed"' are controlled by graphics parameters
     '"cex.lab"'/'"font.lab"' and '"cex.axis"'/'"font.axis"'
     respectively.  (This changed in R 2.5.0.)

Value:

     'persp()' returns the _viewing transformation matrix_, say 'VT', a
     4 x 4 matrix suitable for projecting 3D coordinates (x,y,z) into
     the 2D plane using homogeneous 4D coordinates (x,y,z,t). It can be
     used to superimpose additional graphical elements on the 3D plot,
     by 'lines()' or 'points()', using the simple function 'trans3d()'.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'contour' and 'image'; 'trans3d'.

Examples:

     require(grDevices) # for trans3d
     ## 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 - using trans3d() :

     xE <- c(-10,10); xy <- expand.grid(xE, xE)
     points(trans3d(xy[,1], xy[,2], 6, pmat = res), col = 2, pch =16)
     lines (trans3d(x, y=10, z= 6 + sin(x), pmat = 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

     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)

     # (4) Surface colours corresponding to z-values

     par(bg = "white")
     x <- seq(-1.95, 1.95, length = 30)
     y <- seq(-1.95, 1.95, length = 35)
     z <- outer(x, y, function(a,b) a*b^2)
     nrz <- nrow(z)
     ncz <- ncol(z)
     # Create a function interpolating colors in the range of specified colors
     jet.colors <- colorRampPalette( c("blue", "green") ) 
     # Generate the desired number of colors from this palette
     nbcol <- 100
     color <- jet.colors(nbcol)
     # Compute the z-value at the facet centres
     zfacet <- z[-1, -1] + z[-1, -ncz] + z[-nrz, -1] + z[-nrz, -ncz]
     # Recode facet z-values into color indices
     facetcol <- cut(zfacet, nbcol)
     persp(x, y, z, col=color[facetcol], phi=30, theta=-30)

     par(op)

