spatstat (version 1.31-3)

plot.im: Plot a Pixel Image

Description

Plot a pixel image.

Usage

## S3 method for class 'im':
plot(x, \dots,
                   col=NULL, valuesAreColours=NULL,
                   log=FALSE,
                   ribbon=TRUE,
                   ribside=c("right", "left", "bottom", "top"),
                   ribsep=0.15, ribwid=0.05, ribn=1024,
                   ribscale=1, ribargs=list())

Arguments

x

The pixel image to be plotted. An object of class "im" (see im.object).

...

Extra arguments passed to image.default to control the plot. See Details.

col

Colours for displaying the pixel values. Either a character vector of colour values, or an object of class colourmap.

valuesAreColours

Logical value. If TRUE, the pixel values of x are to be interpreted as colour values.

log

Logical value. If TRUE, the colour map will be evenly-spaced on a logarithmic scale.

ribbon

Logical flag indicating whether to display a ribbon showing the colour map.

ribside

Character string indicating where to display the ribbon relative to the main image.

ribsep

Factor controlling the space between the ribbon and the image.

ribwid

Factor controlling the width of the ribbon.

ribn

Number of different values to display in the ribbon.

ribscale

Rescaling factor for tick marks. The values on the numerical scale printed beside the ribbon will be multiplied by this rescaling factor.

ribargs

List of additional arguments passed to image.default and axis to control the display of the ribbon and its scale axis. These

Value

• The colour map used. An object of class "colourmap".

Image Rendering Errors and Problems

The help for image.default explains that errors may occur, or images may be rendered incorrectly, on some devices, depending on the availability of colours and other device-specific constraints. An error may occur on some graphics devices if the image is very large. If this happens, try setting useRaster=FALSE in the call to plot.im.

The error message useRaster=TRUE can only be used with a regular grid means that the $x$ and $y$ coordinates of the pixels in the image are not perfectly equally spaced, due to numerical rounding. This occurs with some images created by earlier versions of spatstat. To repair the coordinates in an image X, type X <- as.im(X).

Details

This is the plot method for the class "im". [It is also the image method for "im".]

The pixel image x is displayed on the current plot device, using equal scales on the x and y axes.

If ribbon=TRUE, a legend will be plotted. The legend consists of a colour ribbon and an axis with tick-marks, showing the correspondence between the pixel values and the colour map.

By default, the ribbon is placed at the right of the main image. This can be changed using the argument ribside. Arguments ribsep, ribwid, ribn control the appearance of the ribbon. The width of the ribbon is ribwid times the size of the pixel image, where `size' means the larger of the width and the height. The distance separating the ribbon and the image is ribsep times the size of the pixel image. The ribbon contains ribn different numerical values, evenly spaced between the minimum and maximum pixel values in the image x, rendered according to the chosen colour map.

Arguments ribscale, ribargs control the annotation of the colour ribbon. To plot the colour ribbon without the axis and tick-marks, use ribargs=list(axes=FALSE).

Normally the pixel values are displayed using the colours given in the argument col. This may be either an explicit colour map (an object of class "colourmap", created by the function colourmap) or a character vector or integer vector that specifies a set of colours. If col is an explicit colour map (an object of class "colourmap") then the same colour always represents the same numeric value. For example this ensures that when we plot different images, the colour maps are consistent.

If col is a character vector or integer vector that specifies colours, then the colour mapping will be stretched to match the range of pixel values in the image x. In this case, the mapping of pixel values to colours is determined as follows. [object Object],[object Object],[object Object] Other graphical parameters controlling the display of both the pixel image and the ribbon can be passed through the ... arguments to the function image.default. A parameter is handled only if it is one of the following:

• a formal argument ofimage.defaultthat is operative whenadd=TRUE.
• one of the parameters"main", "asp", "sub", "axes", "ann", "cex", "font", "cex.axis", "cex.lab", "cex.main", "cex.sub", "col.axis", "col.lab", "col.main", "col.sub", "font.axis", "font.lab", "font.main", "font.sub"described inpar.
• the argumentbox, a logical value specifying whether a box should be drawn.

By default, images are plotted using image rasters rather than polygons, by setting useRaster=TRUE in image.default.

Alternatively, the pixel values could be directly interpretable as colour values in R. That is, the pixel values could be character strings that represent colours, or values of a factor whose levels are character strings representing colours.

• IfvaluesAreColours=TRUE, then the pixel values will be interpreted as colour values and displayed using these colours.
• IfvaluesAreColours=FALSE, then the pixel values willnotbe interpreted as colour values, even if they could be.
• IfvaluesAreColours=NULL, the algorithm will guess what it should do. If the argumentcolis given, the pixel values willnotbe interpreted as colour values. Otherwise, if all the pixel values are strings that represent colours, then they will be interpreted and displayed as colours.

If pixel values are interpreted as colours, the arguments col and ribbon will be ignored, and a ribbon will not be plotted.

See Also

im.object, colourmap, contour.im, persp.im, image.default, spatstat.options

Examples

# an image
   Z <- setcov(owin())
   plot(Z)
   plot(Z, ribside="bottom")
   # stretchable colour map
   plot(Z, col=terrain.colors(128), axes=FALSE)
   # fixed colour map
   tc <- colourmap(rainbow(128), breaks=seq(-1,2,length=129))
   plot(Z, col=tc)
   # tweaking the plot
   plot(Z, main="La vie en bleu", col.main="blue", cex.main=1.5,
        box=FALSE,
        ribargs=list(col.axis="blue", col.ticks="blue", cex.axis=0.75))
   # log scale
   V <- eval.im(exp(exp(Z+2))/1e4)
   plot(V, log=TRUE, main="Log scale")