— Robbie Morrison 2009/06/18

This page explains how to read and display image files in plot frames. A plot frame is the display device used to show plots in R (the exact device depends on your platform).

confirm and/or correct the example code

The following bitmap formats are considered here:

• PNG — portable network graphic

• JPEG — JPEG image

• GIF — graphical interchange format

• TIFF — tagged image format

• PPM, PGM, PBM — portable bitmap images in color, gray-scale, and black and white, respectively (ImageMagick)

As are the following vector graphics formats:

• PS, EPS — PostScript, encapsulated PostScript (Adobe)

• PDF – portable document format (Adobe)

• SVG — scalable vector graphics (web)

The packages reviewed here also support some less common formats, listed below for completeness but not discussed further:

• BMP — Windows bitmap format (not considered particularly portable) (Microsoft)

• ENVI — a GIS (geographic information system) format

• GDAL — a geospatial raster graphics format

• OGR — a geospatial vector graphics format

Formats lacking direct support in R include:

• WMF, EMF — Windows vector graphics formats (non-portable) (Microsoft)

The direct display of PDF images is not possible. However see package grImport to get started on a lossless work-around. Or convert first to a bitmap format (ImageMagick can do this) and then read and display that.

There is not always a good solution for a particular format. In some cases, reliance on utility software (such as ImageMagick or Inkscape) or pre-installed system libraries (like libjpeg or libtiff) may add complexity to a particular pathway and thereby limit its appeal.

Users should therefore select their formats and pathways with some care — whilst noting that support for displaying bitmap images is currently much better than for vector graphics.

To save plot frames as images — that is, head in the reverse direction — see exporting R graphs. Also note the package GDD.

The following R packages are reviewed here:

• EBImage — based on ImageMagick

• rgdal — geospatial image processing

• rimage and ReadImage — JPEG processing

• caTools — GIF import (among other things)

• rtiff — TIFF processing

• pixmap — PPM, PGM, PBM processing

• grImport — PostScript import

This page is written from the perspective of Linux. Windows and Mac OS users are invited to contribute their experiences and insights!

When pre-installing system libraries using a Linux package management system (based on RPM or DEB), you may need to download the associated dev package as well. This then provides the relevant header file or files (usually *.h) to the R package which wants to link to that library. If the headers are not present, then the R package will doubtless fail to build and install.

Bitmap images are also known as pixmaps and as raster graphics.

Package EBImage provides an image processing toolkit based on ImageMagick — which (as at June 2009) requires ImageMagick 6.2.4 or better.

• supports: PNG JPEG GIF TIFF PPM PGM PBM

library(EBImage)
plot.new()
p   <- system.file("images", "my.png", package = "EBImage")
png <- readImage(p)
display(png)

Similarly for "my.ppm", "my.pgm", and "my.pbm". And for "my.jpg", "my.gif", and "my.tif", depending on the capabilities of the ImageMagick installation you have.

EBImage may be your best choice for PNG. In addition, this may be your best overall choice if you require support for a variety of common bitmap formats.

Package rgdal requires binaries and headers for the GDAL geospatial data and PROJ.4 libraries.

• supports (among others): PNG JPG TIFF

library(rgdal)
plot.new()
p <- system.file("my.png", package = "rgdal")
h <- GDAL.open(p)
getDriverLongName(getDriver(h))
displayDataset(h)
GDAL.close(h)

GDAL.open() returns the file handle h and getDriverLongName() should report “Portable Network Graphics”.

Package rimage provides functions for processing images and for reading JPEG files — this package requires binaries and headers for libjpeg and fftw-2 (providing fast Fourier transforms for image processing) libraries. Package ReadImages is a subset of rimage and does not require fftw-2.

• supports: JPEG PNG?

library(ReadImages)
plot.new()
j    <- system.file("data", "my.jpg", package = "ReadImages")
jpeg <- read.jpeg(j)
plot(jpeg)

ReadImages may be your best choice for JPEG.

Here is that same functionality using rimage.

library(rimage)
plot.new()
j    <-system.file("data", "my.jpg", package = "rimage")
jpeg <- read.jpeg(j)
plot(jpeg)

There was a suggestion on R-help that recent versions of rimage support PNG but I could not find further evidence of that.

Package caTools provides a number of utility functions, including calls to read and write GIF files — this package depends on package bitopts (but contains no system requirements).

• supports: GIF

library(caTools)
plot.new()
gif <- read.gif("my.gif", verbose = TRUE, flip = TRUE)
image(gif$image, col = gif$col, main = gif$comment, asp = 1)

Note that image() needs flip = TRUE and that asp = 1 sets the aspect ratio to unity.

caTools may be your best choice for GIF.

Package rtiff reads TIFF format images and returns them as pixmaps objects. The package requires that the libtiff binary and header are present.

• supports: TIFF

library(rtiff)
plot.new()
tif <- read.tiff("my.tif")
plot(tif)

The resulting pixmaps can be very large, but users can reduce the resolution of TIFF files on-the-fly in order to improve performance. Consult the package documentation for details.

rtiff may be your best choice for TIFF.

Package pixmap provides functions for the import, export, plotting and manipulation of bitmapped images (the package has no internal dependencies or system requirements).

• supports: PPM PGM PBM

library(pixmap)
plot.new()
p   <- system.file("my.ppm", package="pixmap")
ppm <- read.pnm(p)
plot(ppm)

Similarly for "my.pgm" and "my.pbm".

pixmap may be your best choice for PPM, PGM, and PBM.

Package grImport provides functions for converting, importing, and drawing PostScript pictures in R plots. The package uses particular a dialect of XML, known as RGML, as an intermediate format.

• supports: PS EPS
• indirectly supports: PDF SVG

library(grImport)
plot.new()
PostScriptTrace("tiger.ps")
tiger <- readPicture("tiger.ps.xml")
plot(tiger)

If need be, SVG can be converted into PostScript using Inkscape in batch mode.

infilename  <- "tiger.svg"
outfilename <- sub("\\.svg$", ".ps", infilename)
call        <- paste("inkscape", "--export-eps=", outfilename, "&")
ret         <- system(call)

SVG can also be converted to PostScript via Batik, given your system has Java installed.

infilename <- "my.svg"
call       <- paste("java", "-jar batik-rasterizer.jar", infilename, "-m application/postscript")
ret        <- system(call)

In addition, there are a number of PDF to PostScript conversion utilities. These are well documented on the web and elsewhere and are therefore not discussed here.

For more information:

[2009, article| url]

Murrell, P. (2009). Importing vector graphics : the grImport package for R. Journal of Statistical Software, 30(4), 1-37.

[2006, conference| url]

Murrell, P. (2006). Can R draw graphs?.

It may well be that grImport should be regarded as experimental at this stage in development.

A number of stand-alone graphics utilities can be called in batch mode using system() to convert to and from different graphics formats and/or resolutions. The merits of different conversion routes are left to the user, beyond noting that not all routes maintain sampling fidelity and/or color depth. That said, it may well be useful to reduce the size of your image to match your display device, prior to import.

In most cases, additional material can be added to the plot frame, thereby relegating the original graphic to that of a backing image.

Simple plot calls naturally place the image in the plot region. With additional work, images can also be placed in the plot margin, as described in this R-help posting.

The ImageMagick display utility can be called directly from R, thereby bypassing the need to import the graphics file as data:

frame_title <- "\"override default title\""
graphic     <- "my.png"
call        <- paste("display", "-title", frame_title, graphic, "&")
ret         <- system(call)

This, of course, means that the image is not contained in an R display device and therefore not under the direct control of R. Furthermore, although the above code shows a PNG file, ImageMagick normally also supports GIF, JPEG, TIFF, PPM, PGM, and PBM.

The package RgoogleMaps allows suitably re-scaled static maps from Google to be used as underlay graphics in R. The map itself defaults to GIF and is displayed using package rgdal. Further discussion lies outside the scope of this wiki page, but for a good overview, see:

[2009, techreport| url]

Loecher, M. (2009). Plotting on Google static maps in R.

Users may also wish to consider the use of map images from OpenStreetMap.

The original author was not able to evaluate and rank the various options presented in a robust manner — although some pointers regarding usage were included where thought appropriate.

Readers are strongly encouraged to test and correct the examples given and to indicate which formats and pathways should be generally or specifically preferred on the basis of real experience.