persp.im {spatstat.geom}

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 [e-mail], Rolf Turner [e-mail] and Ege Rubak [e-mail].

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(), dimyx=32)
   persp(Z, colmap=terrain.colors(128))
   if(interactive()) {
     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)