image {graphics}  R Documentation 
Display a Color Image
Description
Creates a grid of colored or grayscale rectangles with colors
corresponding to the values in z
. This can be used to display
threedimensional or spatial data aka images.
This is a generic function.
NOTE: the grid is drawn as a set of rectangles by default;
see the useRaster
argument to draw the grid as a raster image.
The function hcl.colors
provides a broad range of sequential
color palettes that are suitable for displaying ordered data, with
n
giving the number of colors desired.
Usage
image(x, ...)
## Default S3 method:
image(x, y, z, zlim, xlim, ylim,
col = hcl.colors(12, "YlOrRd", rev = TRUE),
add = FALSE, xaxs = "i", yaxs = "i", xlab, ylab,
breaks, oldstyle = FALSE, useRaster, ...)
Arguments
x , y 
locations of grid lines at which the values in 
z 
a numeric or logical matrix containing the values to be plotted
( 
zlim 
the minimum and maximum 
xlim , ylim 
ranges for the plotted 
col 
a list of colors such as that generated by

add 
logical; if 
xaxs , yaxs 
style of x and y axis. The default 
xlab , ylab 
each a character string giving the labels for the x and
y axis. Default to the ‘call names’ of 
breaks 
a set of finite numeric breakpoints for the colours: must have one more breakpoint than colour and be in increasing order. Unsorted vectors will be sorted, with a warning. 
oldstyle 
logical. If true the midpoints of the colour intervals
are equally spaced, and 
useRaster 
logical; if 
... 
graphical parameters for 
Details
The length of x
should be equal to the nrow(z)+1
or
nrow(z)
. 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 equallyspaced
grid. If you specify just one row or column and a lengthone x
or y
, the whole user area in the corresponding direction is
filled. For logarithmic x
or y
axes the boundaries between
cells must be specified.
Rectangles corresponding to missing values are not plotted (and so are
transparent and (unless add = TRUE
) the default background
painted in par("bg")
will show through and if that is
transparent, the canvas colour will be seen).
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 which is
closed at both ends.
The axes (where plotted) make use of the classes of xlim
and
ylim
(and hence by default the classes of x
and
y
): this will mean that for example dates are labelled as
such.
Notice that image
interprets the z
matrix as a table of
f(x[i], y[j])
values, so that the x axis corresponds to row
number and the y axis to column number, with column 1 at the bottom,
i.e. a 90 degree counterclockwise rotation of the conventional
printed layout of a matrix.
Images for large z
on a regular grid are rendered more
efficiently with useRaster = TRUE
and can prevent rare
antialiasing artifacts, but may not be supported by all graphics
devices. Some devices (such as postscript
and X11(type =
"Xlib")
) which do not support semitransparent colours may emit
missing values as white rather than transparent, and there may be
limitations on the size of a raster image. (Problems with the
rendering of raster images have been reported by users of
windows()
devices under Remote Desktop, at least under its
default settings.)
The graphics files in PDF and PostScript can be much smaller under this option.
If useRaster
is not specified, raster images are used when the
getOption("preferRaster")
is true, the grid is regular
and either dev.capabilities("rasterImage")$rasterImage
is "yes"
or it is "nonmissing"
and there are no missing
values.
Note
Originally based on a function by Thomas Lumley.
See Also
filled.contour
or heatmap
which can
look nicer (but are less modular),
contour
;
The lattice equivalent of image
is
levelplot
.
hcl.colors
, gray.colors
,
hcl
, hsv
, par
.
dev.capabilities
to see if useRaster = TRUE
is
supported on the current device.
Examples
require("grDevices") # for colours
x < y < seq(4*pi, 4*pi, length.out = 27)
r < sqrt(outer(x^2, y^2, `+`))
image(z = z < cos(r^2)*exp(r/6), col = gray.colors(33))
image(z, axes = FALSE, main = "Math can be beautiful ...",
xlab = expression(cos(r^2) * e^{r/6}))
contour(z, add = TRUE, drawlabels = FALSE)
# Visualize as matrix. Need to transpose matrix and then flip it horizontally:
tf < function(m) t(m)[, nrow(m):1]
imageM < function(m, grid = max(dim(m)) <= 25, asp = (nrow(m)1)/(ncol(m)1), ...) {
image(tf(m), asp=asp, axes = FALSE, ...)
mAxis < function(side, at, ...) # using 'j'
axis(side, at=at, labels=as.character(j+1L), col="gray", col.axis=1, ...)
n < ncol(m); n1 < n1L; j < 0L:n1; mAxis(1, at= j/n1)
if(grid) abline(v = (0:n  .5)/n1, col="gray77", lty="dotted")
n < nrow(m); n1 < n1L; j < 0L:n1; mAxis(2, at=1j/n1, las=1)
if(grid) abline(h = (0:n  .5)/n1, col="gray77", lty="dotted")
}
(m < outer(1:5, 1:14))
imageM(m, main = "image(<5 x 14 matrix>) with rows and columns")
imageM(volcano)
# A prettier display of the volcano
x < 10*(1:nrow(volcano))
y < 10*(1:ncol(volcano))
image(x, y, volcano, col = hcl.colors(100, "terrain"), axes = FALSE)
contour(x, y, volcano, levels = seq(90, 200, by = 5),
add = TRUE, col = "brown")
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)