R: Perspective Plot of Pixel Image

persp.im {spatstat} | R Documentation

## Perspective Plot of Pixel Image

### Description

Displays a perspective plot of a pixel image.

### Usage

      ## S3 method for class 'im'
    persp(x, ...,
                         colmap=NULL, colin=x, apron=FALSE, visible=FALSE)

### Arguments

`x` | The pixel image to be plotted as a surface. An object of class `"im"` (see `im.object`).
`...` | Extra arguments passed to `persp.default` to control the display.
`colmap` | Optional data controlling the colour map. See Details.
`colin` | Optional. Colour input. Another pixel image (of the same dimensions as `x`) containing the values that will be mapped to colours.
`apron` | Logical. If `TRUE`, a grey apron is placed around the sides of the perspective plot.
`visible` | Logical value indicating whether to compute which pixels of `x` are visible in the perspective view. See Details.

### Details

This is the `persp` method for the class `"im"`.

The pixel image `x` must have real or integer values. These values are treated as heights of a surface, and the surface is displayed as a perspective plot on the current plot device, using equal scales on the `x` and `y` axes.

The optional argument `colmap` gives an easy way to display different altitudes in different colours (if this is what you want).

- If `colmap` is a colour map (object of class `"colourmap"`, created by the function `colourmap`) then this colour map will be used to associate altitudes with colours.

- If `colmap` is a character vector, then the range of altitudes in the perspective plot will be divided into `length(colmap)` intervals, and those parts of the surface which lie in a particular altitude range will be assigned the corresponding colour from `colmap`.

- If `colmap` is a function in the R language of the form `function(n, ...)`, this function will be called with an appropriate value of `n` to generate a character vector of `n` colours. Examples of such functions are `heat.colors`, `terrain.colors`, `topo.colors` and `cm.colors`.

- If `colmap` is a function in the R language of the form `function(range, ...)` then it will be called with `range` equal to the range of altitudes, to determine the colour values or colour map. Examples of such functions are `beachcolours` and `beachcolourmap`.

- If `colmap` is a list with entries `breaks` and `col`, then `colmap$breaks` determines the breakpoints of the altitude intervals, and `colmap$col` provides the corresponding colours.

Alternatively, if the argument `colin` (colour input) is present, then the colour map `colmap` will be applied to the pixel values of `colin` instead of the pixel values of `x`. The result is a perspective view of a surface with heights determined by `x` and colours determined by `colin` (mapped by `colmap`).

If `apron=TRUE`, vertical surface is drawn around the boundary of the perspective plot, so that the terrain appears to have been cut out of a solid material. If colour data were supplied, then the apron is coloured light grey.

Graphical parameters controlling the perspective plot are passed through the `...` arguments directly to the function `persp.default`. See the examples in `persp.default` or in `demo(persp)`.

The vertical scale is controlled by the argument `expand`: setting `expand=1` will interpret the pixel values as being in the same units as the spatial coordinates x and y and represent them at the same scale.

If `visible=TRUE`, the algorithm also computes whether each pixel in `x` is visible in the perspective view. In order to be visible, a pixel must not be obscured by another pixel which lies in front of it (as seen from the viewing direction), and the three-dimensional vector normal to the surface must be pointing toward the viewer. The return value of `persp.im` then has an attribute `"visible"` which is a pixel image, compatible with `x`, with pixel value equal to `TRUE` if the corresponding pixel in `x` is visible, and `FALSE` if it is not visible.

### Value

(invisibly) the 3D transformation matrix returned by `persp.default`, together with an attribute `"expand"` which gives the relative scale of the z coordinate.

If argument `visible=TRUE` was given, the return value also has an attribute `"visible"` which is a pixel image, compatible with `x`, with logical values which are TRUE when the corresponding pixel is visible in the perspective view, and `FALSE` when it is obscured.

### Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner r.turner@auckland.ac.nz and Ege Rubak rubak@math.aau.dk.

### See Also

`perspPoints`, `perspLines` for drawing additional points or lines on the surface.

`trans3d` for mapping arbitrary (x,y,z) coordinate locations to the plotting coordinates.

`im.object`, `plot.im`, `contour.im`

### Examples

       # an image
       Z <- setcov(owin())
       persp(Z, colmap=terrain.colors(128))
       co <- colourmap(range=c(0,1), col=rainbow(128))
       persp(Z, colmap=co, axes=FALSE, shade=0.3)

       ## Terrain elevation
       persp(bei.extra$elev, colmap=terrain.colors(128),
             apron=TRUE, theta=-30, phi=20,
             zlab="Elevation", main="", ticktype="detailed",
             expand=6)

[Package spatstat version 1.63-3 Index]