persp {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, 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",
          ...)

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

### Value

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.

### References

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

### See Also

`contour` and `image`.

### Examples

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

[Package Contents]