grImport2

The grImport2 package is an R package for importing vector images to be drawn within an R plot. It was developed as part of the 2013 Google Summer of Code. It improves upon some of the limitations of the grImport package and more comprehensively reproduces vector images in R.

It can import any SVG image that has been generated by the Cairo graphics library. To ensure that this has been performed, it is often necessary to use the grConvert package to convert from popular vector image formats (PostScript, PDF and SVG) into an SVG image that has been generated by Cairo.

An example of what can be achieved is shown below, where I import the Flag of New Zealand (from Wikimedia) into a basic plot.

> library(grImport2)
> flag <- readPicture("nzflag.svg")
> xs <- runif(10)
> ys <- runif(10)
> grid.symbols(flag,
+              x = xs, y = ys, size = 0.3, default.units = "npc",
+              ext = "clipbbox")

grImport2 example plot

Installation

grImport2 requires a few packages in order to run. To install them, run the following command:

> install.packages(c("XML", "png", "jpeg", "base64enc"))

If you have the devtools package installed, you can easily install grImport2 using the install_github() function.

> devtools::install_github("sjp/grImport2")

If you do not have devtools installed, you will have to install using Subversion from the canonical source.

$ svn checkout svn://r-forge.r-project.org/svnroot/grimport/pkg/grImport2

Now we can build and install grImport2.

$ cd grImport2
$ R CMD build .
$ R CMD INSTALL grImport2*.tar.gz

Usage

We will demonstrate basic usage of the grImport2 package using the example shown earlier. It should be noted however that knowledge of the grid package is considered a pre-requisite to proper usage of the grImport2 package.

The first thing we need to do is load the package.

> library(grImport2)

Now we can begin to load a picture that has been converted by grConvert to an SVG image format. We will store the definition of the picture in a variable called flag.

> flag <- readPicture("nzflag.svg")

Now in order to plot the image we have two options. We can either use the grid.picture(), which will plot a single image or we can use grid.symbols() which will plot multiple copies of an image. First, let us see the effect of grid.picture().

> grid.picture(flag, ext = "clipbbox")

grImport2 example plot

We can see that the image has been reproduced reasonably faithfully, but there are some parts of the image that are not correct. To correct this requires the use of the gridSVG package and will not be discussed in this brief overview. For more information consult the package documentation on the ext argument in grid.picture().

Another function that is provided by grImport2 is grid.symbols(). Rather than having to call grid.picture() multiple times, we can (if desired), call grid.symbols() just once instead.

> xs <- runif(10)
> ys <- runif(10)
> grid.symbols(flag,
+              x = xs, y = ys, size = 0.3, default.units = "npc",
+              ext = "clipbbox")

grImport2 example plot

This shows how we can import a vector image and use it as a custom plotting character for use in grid plots.

Documentation

As with all R packages, documentation is provided with the package. Help is available for the grImport2 functions by typing the commands listed below:

Further information demonstrating its usage is available in the following locations: