\HeaderA{image}{Display a Color Image}{image}
\methaliasA{image.default}{image}{image.default}
\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{\LinkA{heat.colors}{heat.colors}}, \code{\LinkA{terrain.colors}{terrain.colors}}
and \code{\LinkA{topo.colors}{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 finite, non-missing and 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, defaulting to the range of the finite values of
\code{z}. 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{\LinkA{rainbow}{rainbow}}, \code{\LinkA{heat.colors}{heat.colors}},
\code{\LinkA{topo.colors}{topo.colors}}, \code{\LinkA{terrain.colors}{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{\LinkA{par}{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{\LinkA{plot}{plot}} may also be
passed as arguments to this function, as can the plot aspect ratio
\code{asp} (see \code{\LinkA{plot.window}{plot.window}}).
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The length of \code{x} should be equal to the \code{nrow(z)+1} or
\code{nrow(z)}.  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.

Rectangles corresponding to missing values are not plotted (and so are
transparent and (unless \code{add=TRUE}) the default background painted
in \code{par("bg")} will show though and if that is transparent, the
canvas colour will be seen).

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

Notice that \code{image} interprets the \code{z} matrix as a table of
\code{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 counter-clockwise rotation of the conventional
printed layout of a matrix.
\end{Details}
\begin{Note}\relax
Based on a function by Thomas Lumley
\email{tlumley@u.washington.edu}.
\end{Note}
\begin{SeeAlso}\relax
\code{\LinkA{filled.contour}{filled.contour}} or \code{\LinkA{heatmap}{heatmap}} which can
look nicer (but are less modular),
\code{\LinkA{contour}{contour}};

\code{\LinkA{heat.colors}{heat.colors}}, \code{\LinkA{topo.colors}{topo.colors}},
\code{\LinkA{terrain.colors}{terrain.colors}}, \code{\LinkA{rainbow}{rainbow}},
\code{\LinkA{hsv}{hsv}}, \code{\LinkA{par}{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)

# Volcano data visualized as matrix. Need to transpose and flip
# matrix horizontally. 
image(t(volcano)[ncol(volcano):1,])

# A prettier display of the 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}

