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 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
installed, you can easily install grImport2 using the
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
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.
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
> 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
which will plot multiple copies of an image. First, let us see the effect of
> grid.picture(flag, ext = "clipbbox")
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
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")
This shows how we can import a vector image and use it as a custom plotting character for use in grid plots.
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:
- Enhanced Vector Image Import: The grConvert and grImport2 packages. A draft article submitted to the R Journal.
- Improved Importing of Vector Graphics in R. A technical report published on the University of Auckland’s Department of Statistics Technical Report Blog.
- Plotting SVG State Flags in R. A demonstration of the ability to import various vector images using USA state flags as a test case. It shows the capabilities (and limitations) of grConvert, grImport and grImport2 as it imports vector images into R.