\Header{image}{Display a color image}
\keyword{hplot}{image}
\keyword{aplot}{image}
\begin{Usage}
\begin{verbatim}
image(x, y, z, zlim, col = heat.colors(12),
      add = FALSE, xaxs = "i", yaxs = "i", xlab, ylab, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{x,y}] locations of grid lines at which the values in \texttt{z} are
measured.  These must be in ascending order.  By default, equally
spaced values from 0 to 1 are used.  If \texttt{x} is a \texttt{list},
its components \texttt{x\$x} and \texttt{x\$y} are used for \texttt{x}
and \texttt{y}, respectively. If the list has component \texttt{z} this
is used for \texttt{z}.
\item[\texttt{z}] a matrix containing the values to be plotted (\texttt{NA}s are
allowed).  Note that \texttt{x} can be used instead of \texttt{z} for
convenience.
\item[\texttt{zlim}] the minimum and maximum \texttt{z} values for which colors
will be plotted.  Each of the given colors will be used to color an
equispaced interval of this range.
\item[\texttt{col}] a list of colors such as that generated by
\texttt{\Link{rainbow}}, \texttt{\Link{heat.colors}},
\texttt{\Link{topo.colors}}, \texttt{\Link{terrain.colors}} or similar
functions.
\item[\texttt{add}] logical; if \texttt{TRUE}, add to current plot (and disregard
the following arguments).  This is rarely useful because
\texttt{image} ``paints'' over existing graphics.
\item[\texttt{xaxs, yaxs}] style of x and y axis.  The default \texttt{"i"} is
appropriate for images.  See \texttt{\Link{par}}.
\item[\texttt{xlab, ylab}] each a character string giving the labels for the x and
y axis.  Default to the `call names' of \texttt{x} or \texttt{y}, or to
\texttt{""} if these where unspecified.
\item[\texttt{...}] graphical parameters for \texttt{\Link{plot}} may also be
passed as arguments to this function.
\end{ldescription}
\end{Arguments}
\begin{Description}
Creates a grid of colored or gray-scale rectangles with colors
corresponding to the values in \texttt{z}.  This can be used to display
three-dimensional or spatial data aka ``images''.
The functions \texttt{\Link{heat.colors}}, \texttt{\Link{terrain.colors}}
and \texttt{\Link{topo.colors}} create heat-spectrum (red to white) and
topographical color schemes suitable for displaying ordered data, with
\texttt{n} giving the number of colors desired.\end{Description}
\begin{Note}
Based on a function by Thomas Lumley
\email{thomas@biostat.washington.edu}.\end{Note}
\begin{SeeAlso}
\texttt{\Link{contour}},
\texttt{\Link{heat.colors}}, \texttt{\Link{topo.colors}},
\texttt{\Link{terrain.colors}}, \texttt{\Link{rainbow}},
\texttt{\Link{hsv}}, \texttt{\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=F, main="Math can be beautiful ...",
      xlab=expression(cos(r^2) * e^{-r/6}))
contour(z, add=T)

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}

