# 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 ```r 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 ```r 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) ```

rasterPlot function