\Header{image}{Display a Color Image}
\methalias{image.default}{image}
\keyword{hplot}{image}
\keyword{aplot}{image}
\begin{Description}\relax
Creates a grid of colored or gray-scale rectangles with colors
corresponding to the values in \code{z}.  This can be used to display
three-dimensional or spatial data aka \dQuote{images}.
This is a generic function.

The functions \code{\Link{heat.colors}}, \code{\Link{terrain.colors}}
and \code{\Link{topo.colors}} create heat-spectrum (red to white) and
topographical color schemes suitable for displaying ordered data, with
\code{n} giving the number of colors desired.\end{Description}
\begin{Usage}
\begin{verbatim}
image(x, ...)

## Default S3 method:
image(x, y, z, zlim, xlim, ylim, col = heat.colors(12),
      add = FALSE, xaxs = "i", yaxs = "i", xlab, ylab,
      breaks, oldstyle = FALSE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x,y}] locations of grid lines at which the values in \code{z} are
measured.  These must be in (strictly) ascending order.
By default, equally
spaced values from 0 to 1 are used.  If \code{x} is a \code{list},
its components \code{x\$x} and \code{x\$y} are used for \code{x}
and \code{y}, respectively. If the list has component \code{z} this
is used for \code{z}.
\item[\code{z}] a matrix containing the values to be plotted (\code{NA}s are
allowed).  Note that \code{x} can be used instead of \code{z} for
convenience.
\item[\code{zlim}] the minimum and maximum \code{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 \emph{midpoints} of the
intervals cover the range, so that values just outside the range
will be plotted.
\item[\code{xlim, ylim}] ranges for the plotted \code{x} and \code{y} values,
defaulting to the range of the finite values of \code{x} and \code{y}.
\item[\code{col}] a list of colors such as that generated by
\code{\Link{rainbow}}, \code{\Link{heat.colors}},
\code{\Link{topo.colors}}, \code{\Link{terrain.colors}} or similar
functions.
\item[\code{add}] logical; if \code{TRUE}, add to current plot (and disregard
the following arguments).  This is rarely useful because
\code{image} \dQuote{paints} over existing graphics.
\item[\code{xaxs, yaxs}] style of x and y axis.  The default \code{"i"} is
appropriate for images.  See \code{\Link{par}}.
\item[\code{xlab, ylab}] each a character string giving the labels for the x and
y axis.  Default to the \sQuote{call names} of \code{x} or \code{y}, or to
\code{""} if these where unspecified.
\item[\code{breaks}] a set of breakpoints for the colours: must give one more
breakpoint than colour.
\item[\code{oldstyle}] logical. If true the midpoints of the colour intervals
are equally spaced, and \code{zlim[1]} and \code{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.
\item[\code{...}] graphical parameters for \code{\Link{plot}} may also be
passed as arguments to this function.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The length of \code{x} should be equal to the \code{nrow(x)+1} or
\code{nrow(x)}. In the first case \code{x} specifies the boundaries
between the cells: in the second case \code{x} specifies the
midpoints of the cells. Similar reasoning applies to \code{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 \code{x} or \code{y}, the whole user area in the
corresponding direction is filled.

If \code{breaks} is specified then \code{zlim} is unused and the
algorithm used follows \code{\Link{cut}}, so intervals are closed on
the right and open on the left except for the lowest interval.\end{Details}
\begin{Note}\relax
Based on a function by Thomas Lumley
\email{tlumley@u.washington.edu}.\end{Note}
\begin{SeeAlso}\relax
\code{\Link{filled.contour}} or \code{\Link{heatmap}} which can
look nicer (but are less modular),
\code{\Link{contour}};

\code{\Link{heat.colors}}, \code{\Link{topo.colors}},
\code{\Link{terrain.colors}}, \code{\Link{rainbow}},
\code{\Link{hsv}}, \code{\Link{par}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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)
\end{ExampleCode}
\end{Examples}

