Imager is an image/video processing package for R, based on CImg, a C++ library by David Tschumperlé. CImg provides an easy-to-use and consistent API for image processing, which imager largely replicates. CImg supports images in up to four dimensions, which makes it suitable for applications like video processing/hyperspectral imaging/MRI.

Installing the package

Imager is on CRAN, so

install.packages("imager")

should do the trick. You may also want to install ImageMagick and ffmpeg, see "External Dependencies" below.

The version of CRAN will often lag the one on github. If you'd like to install the latest version, you'll have to build the package from source.

Install the devtools package if you haven't already. Run:

devtools::install_github("asgr/imager")

If that doesn't work then you're probably missing a build environment or a library, see below.

OS X

Install XQuartz if you haven't already (it's required for the interactive functions). You'll need Xcode (OS X's development environment) to compile source packages. The FFTW library is needed, and the easiest way to install it is via Homebrew. Install Homebrew, then run:

brew install fftw

Optionally, install libtiff for better support of TIFF files.

Windows

Building R packages on Windows is a bit of a pain so you're probably better off with the binary package (which may not be up-to-date). If you need the latest version of imager, you'll have to:

• Install Rtools
• Install additional libraries for Rtools. You want the package that's called "local tree". Put those libraries somewhere gcc can find them.

Linux

To build imager from source under Linux, make sure you have the headers for libfftw3, libx11 (if not using Wayland), and optionally libtiff installed. To determine a complete list of all required system dependencies (incl. transitive ones), you can query the SystemRequirements database via the R package sysreqs.

On Ubuntu (or Debian) Linux you would install them via

sudo apt install libfftw3-dev libtiff-dev libxml2-dev libicu-dev libgmp-dev libpng-dev libglpk-dev

External dependencies

OS X users need XQuartz. On its own imager supports JPEG, PNG, TIFF and BMP formats. If you need support for other file types install ImageMagick. To load and save videos you'll need ffmpeg, no file formats are supported natively.

Getting started

Here's a small demo that actually demonstrates an interesting property of colour perception:

library(imager)
library(purrr)
parrots <- load.example("parrots")
plot(parrots)
#Define a function that converts to YUV, blurs a specific channel, and converts back
bchan <- function(im,ind,sigma=5) { 
    im <- RGBtoYUV(im)
    channel(im,ind) <- isoblur(channel(im,ind),sigma); 
    YUVtoRGB(im)
}
#Run the function on all three channels and collect the results as a list
blurred <- map_il(1:3,~ bchan(parrots,.))
names(blurred) <- c("Luminance blur (Y)","Chrominance blur (U)","Chrominance blur (V)")
plot(blurred)

We're much more sensitive to luminance edges than we are to colour edges.

Documentation is available here. To get a list of all package functions, run:

ls(pos = "package:imager")

Important warning on memory usage

All images are stored as standard R numeric vectors (i.e., double-precision), meaning that they take up a lot of memory. It's easy to underestimate how much storage you need for videos, because they take up so little space in a compressed format. Before you can work on it in R a video has to be fully decompressed and stored as double-precision floats. To get a sense of the size, consider a low-resolution (400x300), colour video lasting 120 sec. The video might take up a few MBs when compressed. To store it in memory, you'll need: (400x300) x (25x120) x 3 values, corresponding to (space)x(time)x(colour). In addition, each value costs 8 bytes of storage, for a grand total of 8GB of memory.

For out-of-memory processing of videos, see the experimental package imagerstreams.

Current status

Imager is fully functional but still young, so the API might change. Open an issue on Github or email me if you've found a bug or would like to suggest a feature.

Contributing to imager

If you want to add features or fix a bug, just fork this repository and send me a pull request (they're welcome). Consider contributing documentation too: imager has got quite large over time, and it's in need of more how-to's and tutorials!

Contributors

The package's author is Simon Barthelmé (Gipsa-lab, CNRS). The following people have gracefully contributed code, bug fixes or testing:

• Stefan Roediger
• Aaron Robotham
• Martin Roth
• Jan Wijffels
• Hong Ooi

Let me know if you're missing from the list!

Test pictures

Imager ships with four test pictures and a video. Two (parrots and boats) come from the Kodak set. Another is a sketch of birds by Leonardo, from Wikimedia. Also from Wikimedia: the Hubble Deep field. The test video comes from xiph.org's collection.