Plot a Grayscale or Color Image

DESCRIPTION:

Creates an image, under some graphics devices, of shades of gray or colors that represent a third dimension.

USAGE:

image(x, y, z, zlim = range(z), add = F)

REQUIRED ARGUMENTS:

x
vector containing x coordinates of grid over which z is evaluated. The values should be in increasing order; missing values are not accepted.
y
vector of grid y coordinates. The values should be in increasing order; missing values are not accepted.
z
matrix length(x)-1 by length(y)-1 (or length(x) by length(y)) giving surface height at x-y cell centers, i.e., z[i,j] is evaluated at (x[i]+x[i+1])/2, (y[i]+y[i+1])/2 (or x-y points, i.e., z[i,j] is evaluated at x[i], y[j]). The rows of z are indexed by x, and the columns by y. Missing values ( NAs) are allowed.

The first argument may be a list with components x, y, and z. In particular, the result of interp is suitable as an argument to image.

If the first argument is a matrix, it is assumed to be the z matrix and vectors x and y are generated ( x is 1:nrow(z), y is 1:ncol(z)). The result of predict together with expand.grid is suitable as an argument to image.

OPTIONAL ARGUMENTS:

zlim
vector of length 2 containing minimum and maximum z values to plot. The image will be drawn so that a value of zlim[1] is lightest (or the first color) and zlim[2] is darkest (or the last color). If a value of z is outside of the range of zlim[1] and zlim[2] it will not be plotted, that is, the position will be the background color.
add=
logical flag which if TRUE, causes image to be added to the current plot.

Graphical parameters may also be supplied as arguments to this function (see par).

SIDE EFFECTS:

An image is created on the current graphics device. Either the image is added to the current plot or a new plot is created, depending on the value of the input add. An error occurs if the current graphics device does not support the image command.

NOTE:

Not all plotting devices are able to make images. See the Devices help file for a list of graphics devices that can use image.

DETAILS:

You have the choice between specifying the edges of the cells or the centers of the cells. If you specify the centers, the edges will be placed halfway between the centers and the outer edges will be placed as though all the cells were the same sized. It is generally more convenient to specify the cell centers, but you may need to specify cell edges for more control over the picture, especially if the grid points are not evenly spaced.

Some devices have difficulty overlaying image data on lines and text; try plotting the image data first.

By default, S-PLUS uses a global color palette and global image color palette to map color indices to specific colors. Color arguments can have integer values that map into the color palette, or they can be specified by RGB values or color names. For more information on color specification, see the chapter "Graphics Enhancements" in the Guide to Graphics.

SEE ALSO:

, , , , , , , , , , , , .

EXAMPLES:

rx <- range(ozone.xy$x)
ry <- range(ozone.xy$y)
usa(xlim=rx, ylim=ry, lwd=2, col=2)
i <- interp(ozone.xy$x, ozone.xy$y, ozone.median)
image(i, add=T)
text(ozone.xy, labels=ozone.median)
title(main="Median Ozone Concentrations in the North East")