R: Plot a Pixel Image

plot.im {spatstat} | R Documentation

## Plot a Pixel Image

### Description

Plot a pixel image.

### Usage

      ## S3 method for class 'im'
    plot(x, ...,
                       main,
                       add=FALSE, clipwin=NULL,
                       col=NULL, valuesAreColours=NULL, log=FALSE,
                       ncolours=256, gamma=1,
                       ribbon=show.all, show.all=!add,
                       ribside=c("right", "left", "bottom", "top"),
                       ribsep=0.15, ribwid=0.05, ribn=1024,
                       ribscale=1, ribargs=list(), colargs=list(),
                       useRaster=NULL, workaround=FALSE,
                       do.plot=TRUE)

      ## S3 method for class 'im'
    image(x, ...,
                       main,
                       add=FALSE, clipwin=NULL,
                       col=NULL, valuesAreColours=NULL, log=FALSE,
                       ncolours=256, gamma=1,
                       ribbon=show.all, show.all=!add,
                       ribside=c("right", "left", "bottom", "top"),
                       ribsep=0.15, ribwid=0.05, ribn=1024,
                       ribscale=1, ribargs=list(), colargs=list(),
                       useRaster=NULL, workaround=FALSE,
                       do.plot=TRUE)

### 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.
`main` | Main title for the plot.
`add` | Logical value indicating whether to superimpose the image on the existing plot (`add=TRUE`) or to initialise a new plot (`add=FALSE`, the default).
`clipwin` | Optional. A window (object of class `"owin"`). Only this subset of the image will be displayed.
`col` | Colours for displaying the pixel values. Either a character vector of colour values, an object of class `colourmap`, or a `function` as described under Details.
`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.
`ncolours` | Integer. The default number of colours in the colour map for a real-valued image.
`gamma` | Exponent for the gamma correction of the colours. A single positive number.
`ribbon` | Logical flag indicating whether to display a ribbon showing the colour map. Default is `TRUE` for new plots and `FALSE` for added plots.
`show.all` | Logical value indicating whether to display all plot elements including the main title and colour ribbon. Default is `TRUE` for new plots and `FALSE` for added plots.
`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`, `axis` and `axisTicks` to control the display of the ribbon and its scale axis. These may override the `...` arguments.
`colargs` | List of additional arguments passed to `col` if it is a function.
`useRaster` | Logical value, passed to `image.default`. Images are plotted using a bitmap raster if `useRaster=TRUE` or by drawing polygons if `useRaster=FALSE`. Bitmap raster display tends to produce better results, but is not supported on all graphics devices. The default is to use bitmap raster display if it is supported.
`workaround` | Logical value, specifying whether to use a workaround to avoid a bug which occurs with some device drivers in R, in which the image has the wrong spatial orientation. See the section on Image is Displayed in Wrong Spatial Orientation below.
`do.plot` | Logical value indicating whether to actually plot the image and colour ribbon. Setting `do.plot=FALSE` will simply return the colour map and the bounding box that were chosen for the plot.

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

Arguments `ribside, ribsep, ribwid` control the placement of the colour ribbon. By default, the ribbon is placed at the right of the main image. This can be changed using the argument `ribside`. 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 the colours representing `ribn` different numerical values, evenly spaced between the minimum and maximum pixel values in the image `x`, rendered according to the chosen colour map.

The argument `ribargs` controls the annotation of the colour ribbon. It is a list of arguments to be passed to `image.default`, `axis` and `axisTicks`. To plot the colour ribbon without the axis and tick-marks, use `ribargs=list(axes=FALSE)`. To ensure that the numerals or symbols printed next to the colour map are oriented horizontally, use `ribargs=list(las=1)`. To control the number of tick-marks, use `ribargs=list(nint=N)` where `N` is the desired number of intervals (so there will be `N+1` tickmarks, subject to the vagaries of R internal code).

The argument `ribscale` is used to rescale the numerals printed next to the colour map.

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 command `colourmap`). This is the best way to ensure that when we plot different images, the colour maps are consistent.

- a character vector or integer vector that specifies a set of colours. The colour mapping will be stretched to match the range of pixel values in the image `x`. The mapping of pixel values to colours is determined as follows.

  logical-valued images:

    the values `FALSE` and `TRUE` are mapped to the colours `col[1]` and `col[2]` respectively. The vector `col` should have length 2.

  factor-valued images:

    the factor levels `levels(x)` are mapped to the entries of `col` in order. The vector `col` should have the same length as `levels(x)`.

  numeric-valued images:

    By default, the range of pixel values in `x` is divided into `n = length(col)` equal subintervals, which are mapped to the colours in `col`. (If `col` was not specified, it defaults to a vector of 255 colours.)

    Alternatively if the argument `zlim` is given, it should be a vector of length 2 specifying an interval of real numbers. This interval will be used instead of the range of pixel values. The interval from `zlim[1]` to `zlim[2]` will be mapped to the colours in `col`. This facility enables the user to plot several images using a consistent colour map.

    Alternatively if the argument `breaks` is given, then this specifies the endpoints of the subintervals that are mapped to each colour. This is incompatible with `zlim`.

    The arguments `col` and `zlim` or `breaks` are then passed to the function `image.default`. For examples of the use of these arguments, see `image.default`.

- a `function` in the R language with an argument named `range` or `inputs`.

  If `col` is a function with an argument named `range`, and if the pixel values of `x` are numeric values, then the colour values will be determined by evaluating `col(range=range(x))`. The result of this evaluation should be a character vector containing colour values, or a `"colourmap"` object. Examples of such functions are `beachcolours` and `beachcolourmap`.

  If `col` is a function with an argument named `inputs`, and if the pixel values of `x` are discrete values (integer, logical, factor or character), then the colour values will be determined by evaluating `col(inputs=p)` where `p` is the set of possible pixel values. The result should be a character vector containing colour values, or a `"colourmap"` object.

- a `function` in the R language with first argument named `n`. The colour values will be determined by evaluating `col(n)` where `n` is the number of distinct pixel values, up to a maximum of 128. The result of this evaluation should be a character vector containing color values. Examples of such functions are `heat.colors`, `terrain.colors`, `topo.colors` and `cm.colors`.

If `spatstat.options("monochrome")` has been set to `TRUE` then all colours will be converted to grey scale values.

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 of `image.default` that is operative when `add=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 in `par`.

- the argument `box`, a logical value specifying whether a box should be drawn.

Images are plotted using a bitmap raster if `useRaster=TRUE` or by drawing polygons if `useRaster=FALSE`. Bitmap raster display (performed by `rasterImage`) tends to produce better results, but is not supported on all graphics devices. The default is to use bitmap raster display if it is supported according to `dev.capabilities`.

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.

- If `valuesAreColours=TRUE`, then the pixel values will be interpreted as colour values and displayed using these colours.

- If `valuesAreColours=FALSE`, then the pixel values will not be interpreted as colour values, even if they could be.

- If `valuesAreColours=NULL`, the algorithm will guess what it should do. If the argument `col` is given, the pixel values will not be 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.

### Value

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

Also has an attribute `"bbox"` giving a bounding box for the colour image (including the ribbon if present).

### Complex-valued images

If the pixel values in `x` are complex numbers, they will be converted into four images containing the real and imaginary parts and the modulus and argument, and plotted side-by-side using `plot.imlist`.

### Monochrome colours

If `spatstat.options("monochrome")` has been set to `TRUE`, then the image will be plotted in greyscale. The colours are converted to grey scale values using `to.grey`. The choice of colour map still has an effect, since it determines the final grey scale values.

Monochrome display can also be achieved by setting the graphics device parameter `colormodel="grey"` when starting a new graphics device, or in a call to `ps.options` or `pdf.options`.

### Image Rendering Errors and Problems

The help for `image.default` and `rasterImage` 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.

If the image is not displayed at all, try setting `useRaster=FALSE` in the call to `plot.im`. If the ribbon colours are not displayed, set `ribargs=list(useRaster=FALSE)`.

Errors 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)`.

### Image is Displayed in Wrong Spatial Orientation

If the image is displayed in the wrong spatial orientation, and you created the image data directly, please check that you understand the spatstat convention for the spatial orientation of pixel images. The row index of the matrix of pixel values corresponds to the increasing y coordinate; the column index of the matrix corresponds to the increasing x coordinate (Baddeley, Rubak and Turner, 2015, section 3.6.3, pages 66–67).

Images can be displayed in the wrong spatial orientation on some devices, due to a bug in the device driver. This occurs only when the plot coordinates are reversed, that is, when the plot was initialised with coordinate limits `xlim, ylim` such that `xlim[1] > xlim[2]` or `ylim[1] > ylim[2]` or both. This bug is reported to occur only when `useRaster=TRUE`. To fix this, try setting `workaround=TRUE`, or if that is unsuccessful, `useRaster=FALSE`.

### Author(s)

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

### References

Baddeley, A., Rubak, E. and Turner, R. (2015) Spatial Point Patterns: Methodology and Applications with R. Chapman and Hall/CRC Press.

### See Also

`im.object`, `colourmap`, `contour.im`, `persp.im`, `hist.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)
       # colour map function, with argument 'range'
       plot(Z, col=beachcolours, colargs=list(sealevel=0.5))
       # 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")
       # it's complex
       Y <- exp(Z + V * 1i)
       plot(Y)

[Package spatstat version 1.54-0 Index]