persp                  package:base                  R Documentation

_P_e_r_s_p_e_c_t_i_v_e _P_l_o_t_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     persp(x, ...)
     persp.default(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",
           ...)

_A_r_g_u_m_e_n_t_s:

    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. 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').

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     The viewing transformation matrix, say `VT', a 4 x 4 matrix
     suitable for projecting 3D coordinates (x,y,z) into the 2D plane
     using homogenous 4D coordinates (x,y,z,t). It can be used to
     superimpose additional graphical elements on the 3D plot, by
     `lines()' or `points()', e.g. using the function `trans3d' given
     in the last examples section below.

_S_e_e _A_l_s_o:

     `contour' and `image'.

_E_x_a_m_p_l_e_s:

     ## 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)

