rasterPlot function

Add Raster Elements to Plot

This function takes plotting commands and uses a temporary bitmap graphics device to capture their output. The resulting raster image is drawn in the plot or figure region of the active high-level plot. A new plot is started if one does not exist. UTF-8

rasterPlot(expr, res = 150, region = c("plot", "figure"), antialias,
           bg = "transparent", interpolate = TRUE, draw = TRUE,
           Cairo = FALSE, ...)

Arguments

• expr: Low-level plotting commands (lines, points, text, ) representing elements to be added to the current plot. A call or an expression.

• res: Resolution in points per inch (ppi). A numeric value. Suggested values for different types of display media are given in compactPDF. For example, the default 150 ppi corresponds to ebook quality.

• region: The function can draw in the "plot" region or the "figure" region which also includes "mar" margins (see par). If the drawing commands in expr

  contain no material for the margins, the default "plot" is optimal. Plotting in the outer margins ("oma" in par) is not supported.

• antialias: Antialiasing argument passed to png. The default (missing argument) is probably good for line plots but "none" is preferred for images in which color signifies value of data. Unused if a Cairo device is used instead of png.

• bg: Background color of the raster plot, an argument passed to the bitmap device. If the default "transparent" does not work, try "white" or another color. Note that a non-transparent background will mask any previous content in the figure or plot region, depending on the value of region.

• interpolate: Argument passed to rasterImage. A logical

  flag. The default is TRUE: use linear interpolation. Analogously to antialias, FALSE is preferred when color maps to value.

• draw: A logical flag. Draw the results (TRUE, the default) or return an image object (FALSE)?

• Cairo: A logical flag. TRUE for preferring a Cairo to png as the bitmap device, FALSE (the default) for the opposite. If the preferred device cannot be used, the other one will be tried.

• ...: Other arguments to png or Cairo.

Details

The appropriate graphical parameters of the current graphics device are copied to the temporary bitmap device. Therefore the appearance of the raster contents should be almost the same as when directly drawn.

The call or expression expr is evaluated in the environment of the caller.

It is possible that the raster contents will maintain a constant size when the graphics device is resized. If resizing works, however, the image may become distorted. For example, circle symbols will turn into ellipses if the width to height ratio is not maintained (see Examples ). This is in contrast to a standard plot in a display graphics device, e.g. x11, where text and symbols maintain their size when the device is resized.

Returns

If draw is TRUE, there is no return value. The function is used for the side effects.

If draw is FALSE, an object of class "nativeRaster" is returned. The object can be used as input for rasterImage or grid.raster. See readPNG. If no bitmap device is available (see Note ), NULL is returned.

Author(s)

Mikko Korpela

Note

• The graphics device used for the output must have support for including raster images. See "rasterImage" in dev.capabilities.

• The build must have a functional png device, which requires one of the following capabilities: "png", "aqua" or "cairo". Alternatively, a Cairo device from package Cairo must be available with Cairo.capabilities

  "raster" or "png".

If either of these requirements is not met, at least one message is generated and the function reverts to regular plotting. The bg argument is then handled by drawing a filled rectangle. Also region is honored, but the other settings do not apply.

Examples

library(graphics)
library(stats)

## Picture with various graphical elements
x <- 1:100
y0 <- quote(sin(pi * x / 20) + x / 100 + rnorm(100, 0, 0.2))
y <- eval(y0)
ylab <- deparse(y0)
spl <- smooth.spline(y)
plot(x, y, type = "n", axes = FALSE, ylab = ylab)
usr <- par("usr")
xrange <- usr[2] - usr[1]
xsize <- xrange * 0.4
nsteps <- 8
xmar <- xsize / 20
yrange <- usr[4] - usr[3]
ysize <- yrange / 20
ymar <- 0.5 * ysize
X <- seq(usr[1] + xmar, by = xsize / nsteps, length.out = nsteps + 1)
xleft <- X[-(nsteps + 1)]
xright <- X[-1]
pin <- par("pin")
maxrad <- xsize / 3 * min(1, pin[2] / pin[1])
nrad <- 16
minrad <- maxrad / nrad
Rad <- seq(maxrad, by = (minrad - maxrad) / (nrad - 1), length.out=nrad)
xmar2 <- xmar + maxrad
ymar2 <- (xmar2 / xrange) * pin[1] / pin[2] * yrange
expr <- quote({
    rect(xleft, usr[4] - 1.5 * ysize, xright, usr[4] - ymar,
         col = rainbow(8), border = NA)
    symbols(rep(usr[2] - xmar2, nrad), rep(usr[3] + ymar2, nrad),
            circles = Rad, inches = FALSE, add = TRUE, fg = NA,
            bg = gray.colors(nrad + 1, 1, 0)[-1])
    points(y)
    lines(spl)
})
rasterPlot(expr, res = 50)
box()
axis(1)
axis(2)

## The same picture with higher resolution but no antialiasing
plot(y, type = "n", axes = FALSE, ann = FALSE)
## No content in margin, but region = "figure" and bg = "white"
## paints margin white
rasterPlot(expr, antialias = "none", interpolate = FALSE,
           region = "figure", bg = "white")
## Draw box, axes, labels
parnew <- par(new = TRUE)
plot(x, y, type = "n", ylab = ylab)
par(parnew)

## Draw plot(1:5) with adjusted margins and additional axes.  Some parts
## are drawn with rasterPlot, others normally.  Resize to see stretching.
op <- par(no.readonly = TRUE)
par(mar = c(5.1, 4.1, 2.1, 2.1))
plot(1:5, type = "n", axes = FALSE, ann = FALSE)
expr2 <- quote({
    points(c(2, 4), c(2, 4))
    axis(2)
    axis(3)
})
rasterPlot(expr2, region = "figure", bg = "white")
points(c(1, 3, 5), c(1, 3, 5))
box()
axis(1)
axis(4)
title(xlab = "Index", ylab = "1:5")
par(op)