grConvert

The grConvert package is an R package for conveniently converting popular vector image formats (PostScript, PDF and SVG) into valid input formats for the grImport and grImport2 packages. It was developed as part of the 2013 Google Summer of Code.

The key problem that grConvert aims to solve is that grImport requires PostScript images whereas grImport2 requires SVG images to import vector images into R. In particular, grImport2 is able to import only the SVG images that are generated by the Cairo graphics library. By providing a simple way of generating valid images for these packages we can use them more easily and effectively than would otherwise be the case.

To convert between image formats, grConvert leverages the following libraries:

• libspectre for parsing PostScript images.
• Poppler for parsing PDF images.
• libRSVG for parsing SVG images.
• Cairo for rendering parsed images in the target image format.

Installation

Linux

In order to install grConvert on Linux, some dependencies are required. A command has been provided that installs the dependencies on Debian-based distributions (e.g. Ubuntu).

# apt-get install libcairo2-dev libspectre-dev librsvg2-dev \
>     libpoppler-glib-dev r-base-dev

If you have the devtools package installed, you can run the following command in R to install grConvert from a GitHub repository.

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

If you do not have devtools, or want to install grConvert from the canonical source you will need to use Subversion.

Firstly, we need to ensure that Subversion is installed on your system. Following that, we can begin to check out the grConvert package.

# apt-get install subversion

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

Finally we can build and install the grConvert package.

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

OSX

The grConvert package has been tested and works on OSX. It requires the same dependencies that the Linux installation uses, but by another name.

Using either MacPorts or Homebrew should suffice.

If using MacPorts, the following command will install the necessary libraries.

$ port install cairo-devel poppler libspectre librsvg

If using Homebrew, the required libraries can be installed with the following command.

$ brew install poppler librsvg cairo

When last checked, libspectre was not available on Homebrew, therefore using PostScript images for input will not be available when Homebrew is used.

If you have the devtools package installed, you can run the following command in R to install grConvert from a GitHub repository.

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

If you do not have devtools, or want to install grConvert from the canonical source you will need to use Subversion. It can be obtained via Xcode’s “Command Line Tools” downloadable component. Once Subversion has been installed, open up an instance of Terminal and run the following command:

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

Then run the following command to build and install the package in R.

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

Because I do not typically use OSX, these instructions may not be correct. Please contact me if this is the case.

Windows

Currently Windows support is not available. This is primarily due to the difficulty in packaging grConvert’s dependencies for use in a Windows environment.

Usage

The grConvert package is very minimal, exporting only two functions: grConvert.capabilities() and convertPicture().

The first function, grConvert.capabilities() is a utility function that displays which input formats are supported by grConvert. In other words it will inform the user which dependencies were available at install-time.

> library(grConvert)
> grConvert.capabilities()
Supported input formats: PostScript PDF SVG

The second function is the most important function, and performs the key task of converting an input image (in a format listed by grConvert.capabilities()) to an output image format of either PostScript or SVG (for grImport and grImport2 respectively).

> library(grConvert)

> # Convert a PS, PDF, SVG image to SVG
> # suitable for use with grImport2
> convertPicture("nzflag.ps", "nzflag-ps.svg")
> convertPicture("nzflag.pdf", "nzflag-pdf.svg")
> convertPicture("nzflag.svg", "nzflag-svg.svg")

> # Convert a PDF and SVG image to PS
> # suitable for use with grImport
> # (ignoring PS because grImport can already handle all PS inputs)
> convertPicture("nzflag.pdf", "nzflag-pdf.ps")
> convertPicture("nzflag.svg", "nzflag-svg.ps")

Documentation

As with any R package, the documentation is provided with the package. For more information on the convertPicture() function, type ?convertPicture into an R session.

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.