image {base} | R Documentation

## Display a Color Image

### Description

Creates a grid of colored or gray-scale rectangles with colors corresponding to the values in `z`. This can be used to display three-dimensional or spatial data aka ``images''.

The functions `heat.colors`, `terrain.colors` and `topo.colors` create heat-spectrum (red to white) and topographical color schemes suitable for displaying ordered data, with `n` giving the number of colors desired.

### Usage

    image(x, y, z, zlim, xlim, ylim, col = heat.colors(12),
          add = FALSE, xaxs = "i", yaxs = "i", xlab, ylab,
          breaks, oldstyle = FALSE, ...)

### 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. If the list has component `z` this is used for `z`.
`z` | a matrix containing the values to be plotted (`NA`s are allowed). Note that `x` can be used instead of `z` for convenience.
`zlim` | the minimum and maximum `z` values for which colors should be plotted. Each of the given colors will be used to color an equispaced interval of this range. The midpoints of the intervals cover the range, so that values just outside the range will be plotted.
`xlim, ylim` | ranges for the plotted `x` and `y` values, defaulting to the range of the finite values of `x` and `y`.
`col` | a list of colors such as that generated by `rainbow`, `heat.colors`, `topo.colors`, `terrain.colors` or similar functions.
`add` | logical; if `TRUE`, add to current plot (and disregard the following arguments). This is rarely useful because `image` ``paints'' over existing graphics.
`xaxs, yaxs` | style of x and y axis. The default `"i"` is appropriate for images. See `par`.
`xlab, ylab` | each a character string giving the labels for the x and y axis. Default to the `call names' of `x` or `y`, or to `""` if these where unspecified.
`breaks` | a set of breakpoints for the colours: must give one more breakpoint than colour.
`oldstyle` | logical. If true the midpoints of the colour intervals are equally spaced, and `zlim[1]` and `zlim[2]` were taken to be midpoints. (This was the default prior to R 1.1.0.) The current default is to have colour intervals of equal lengths between the limits.
`...` | graphical parameters for `plot` may also be passed as arguments to this function.

### Details

The length of `x` should be equal to the `nrow(x)+1` or `nrow(x)`. In the first case `x` specifies the boundaries between the cells: in the second case `x` specifies the midpoints of the cells. Similar reasoning applies to `y`. It probably only makes sense to specify the midpoints of an equally-spaced grid. If you specify just one row or column and a length-one `x` or `y`, the whole user area in the corresponding direction is filled.

If `breaks` is specified then `zlim` is unused and the algorithm used follows `cut`, so intervals are closed on the right and open on the left except for the lowest interval.

### Note

Based on a function by Thomas Lumley tlumley@u.washington.edu.

The way in which `zlim` is divided into colours will be changed for the next major release (1.1.0) to divide the range into equal-length intervals.

### See Also

`contour`, `heat.colors`, `topo.colors`, `terrain.colors`, `rainbow`, `hsv`, `par`.

### Examples

    x <- y <- seq(-4*pi, 4*pi, len=27)
    r <- sqrt(outer(x^2, y^2, "+"))
    image(z = z <- cos(r^2)*exp(-r/6), col=gray((0:32)/32))
    image(z, axes = FALSE, main = "Math can be beautiful ...",
          xlab = expression(cos(r^2) * e^{-r/6}))
    contour(z, add = TRUE, drawlabels = FALSE)

    data(volcano)
    x <- 10*(1:nrow(volcano))
    y <- 10*(1:ncol(volcano))
    image(x, y, volcano, col = terrain.colors(100), axes = FALSE)
    contour(x, y, volcano, levels = seq(90, 200, by=5), add = TRUE, col = "peru")
    axis(1, at = seq(100, 800, by = 100))
    axis(2, at = seq(100, 600, by = 100))
    box()
    title(main = "Maunga Whau Volcano", font.main = 4)