| % File src/library/graphics/man/image.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2019 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{image} |
| \alias{image} |
| \alias{image.default} |
| \title{Display a Color Image} |
| \usage{ |
| image(x, \dots) |
| |
| \method{image}{default}(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, \dots) |
| } |
| \arguments{ |
| \item{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{z}{a numeric or logical 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{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{xlim, ylim}{ranges for the plotted \code{x} and \code{y} values, |
| defaulting to the ranges of \code{x} and \code{y}.} |
| \item{col}{a list of colors such as that generated by |
| \code{\link{hcl.colors}}, \code{\link{gray.colors}} or similar |
| functions.} |
| \item{add}{logical; if \code{TRUE}, add to current plot (and disregard |
| the following four arguments). This is rarely useful because |
| \code{image} \sQuote{paints} over existing graphics.} |
| \item{xaxs, yaxs}{style of x and y axis. The default \code{"i"} is |
| appropriate for images. See \code{\link{par}}.} |
| \item{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 were unspecified.} |
| \item{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.} |
| \item{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. The default is to have colour intervals of equal |
| lengths between the limits.} |
| \item{useRaster}{logical; if \code{TRUE} a bitmap raster is used to |
| plot the image instead of polygons. The grid must be regular in that |
| case, otherwise an error is raised. For the behaviour when this is |
| not specified, see \sQuote{Details}.} |
| \item{\dots}{\link{graphical parameters} for \code{\link{plot}} may also be |
| passed as arguments to this function, as can the plot aspect ratio |
| \code{asp} and \code{axes} (see \code{\link{plot.window}}).} |
| } |
| \description{ |
| 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 \emph{images}. |
| This is a generic function. |
| |
| The function \code{\link{hcl.colors}} provides a broad range of sequential |
| color palettes that are suitable for displaying ordered data, with |
| \code{n} giving the number of colors desired. |
| } |
| \details{ |
| 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. For logarithmic \code{x} or \code{y} axes the boundaries between |
| cells must be specified. |
| |
| 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 through 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{\link{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 \code{xlim} and |
| \code{ylim} (and hence by default the classes of \code{x} and |
| \code{y}): this will mean that for example dates are labelled as |
| such. |
| |
| 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.\sspace{}a 90 degree counter-clockwise rotation of the conventional |
| printed layout of a matrix. |
| |
| Images for large \code{z} on a regular grid are rendered more |
| efficiently with \code{useRaster = TRUE} and can prevent rare |
| anti-aliasing artifacts, but may not be supported by all graphics |
| devices. Some devices (such as \code{postscript} and \code{X11(type = |
| "Xlib")}) which do not support semi-transparent 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 |
| \code{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 \code{useRaster} is not specified, raster images are used when the |
| \code{\link{getOption}("preferRaster")} is true, the grid is regular |
| and either \code{\link{dev.capabilities}("rasterImage")$rasterImage} |
| is \code{"yes"} or it is \code{"non-missing"} and there are no missing |
| values. |
| } |
| |
| \note{ |
| Originally based on a function by Thomas Lumley. |
| } |
| |
| \seealso{ |
| \code{\link{filled.contour}} or \code{\link{heatmap}} which can |
| look nicer (but are less modular), |
| \code{\link{contour}}; |
| The \CRANpkg{lattice} equivalent of \code{image} is |
| \code{\link[lattice]{levelplot}}. |
| |
| \code{\link{hcl.colors}}, \code{\link{gray.colors}}, |
| \code{\link{hcl}}, \code{\link{hsv}}, \code{\link{par}}. |
| |
| \code{\link{dev.capabilities}} to see if \code{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) |
| |
| # 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 = 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) |
| } |
| \keyword{hplot} |
| \keyword{aplot} |