Image Processing Library Based on 'CImg'

Fast image processing for images in up to 4 dimensions (two spatial dimensions, one time/depth dimension, one colour dimension). Provides most traditional image processing tools (filtering, morphology, transformations, etc.) as well as various functions for easily analysing image data using R. The package wraps 'CImg', <>, a simple, modern C++ library for image processing.

Linux Build Status CRAN Version

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.

Imager is on CRAN, so


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:


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


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.


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.


To build under Linux make sure you have the headers for libX11 and libfftw3 (optionally, libtiff as well). On my Ubuntu system this seems to be enough:

sudo apt-get install libfftw3-dev libX11-dev libtiff-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:

parrots <- load.example("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); 
#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)")

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!


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's collection.


imager 0.41 Major release

  • Functions based on plyr are gradually being phased out in favour of ones based on purrr and dplyr. plyr is no longer loaded by default, which solves some conflicts, but may break existing code! If that's the case just add require(plyr) somewhere.

  • new functions imeval and imchange. These create custom execution environments for functions, and simplify image pipelines: for example, imeval(boats,~ xs*.) is equivalent to: (Xc(boats)/width(boats))*boats and creates a fading effect. imchange(boats,~ c==1,~ xs*.) is the same thing but applied only to the first colour channel (R)

  • (experimental feature) quick-and-dirty interactive interfaces are now easy to program using the interact() function. Use it to explore filter parameters, interactive segmentation. For more sophisticated needs, use e.g. shiny.

  • (experimental feature) as.igraph methods for images and pixsets convert images into graph representations. Nodes are pixels, and edges are drawn between neighbouring pixels. On pixsets, this allows some interesting morphological operations, e.g. contour tracing. On images, it could be used for various graph-based image processing algorithms, like spectral graph clustering

    • new function "inpaint", which fills in missing parts of an image with a weighted avg. of the neighbours. Useful for salt-and-pepper-ish noise, e.g:
    im <- boats
    im[sample(nPix(im),1e4)] <- NA
    inpaint(im,1) %>% imlist(im,.) %>%
                setNames(c("before","after")) %>% 
  • isoblur now has optional na.rm argument, and can ignore missing values.

  • new function: colorise, to fill in regions with a certain colour. Also comes with a formula interface, just like imeval. Ex: highlight central region in image colorise(boats,~ sqrt(xc^2+yc^2) < 140,"blue",alpha=.2) %>% plot see ?colorise for more.

  • new function: load.dir, to load all images in a directory

  • new function: Hough transforms for circles and lines are now available, see hough_circle and hough_line

  • most functions that take a colour argument now accept colour names, e.g.: imfill(10,10,val="red") or autocrop(im,col="black")

  • fixed problem with recent versions of ImageMagick that weren't detected properly

imager 0.40.2 Minor release

* added crop.bbox for cropping image to the bounding box of a pixset
* updated CImg: fixes issues with Intel C compiler and libtiff giving pop-up warnings on Windows 
* threshold now has an "adjust" argument, to adjust the auto-thresholding
* switched to C++11 

imager 0.40.1 Minor release

* Updated CImg, imager should now compile on Solaris
* Fixed memory access bug in px.flood

imager 0.40 Major release

  • added pixset class to represent sets of pixels in an image (implemented as binary images). A test on an image (e.g., im > 0) results in a pixset object. Pixsets come with many convenience functions for plotting, manipulation, morphology, etc. They are described in the "pixsets" vignette.
  • improved reductions (parmax, parmin, etc.). Most are now implemented in C++ and some run in parallel using OpenMP. A median combine operation (parmedian) has been added.
  • added,, functions. Loading and saving videos used to be a bit fragile and platform-dependent, it should now be easier and more robust (also slower, sorry). It's now possible to load individual frames from a video. You still need ffmpeg.
  • to load images from URLs imager now uses the downloader package, which is more robust than the previous solution
  • it's now possible to import images from the raster package and from the magick package.
  • unified RGB representations so that every function expects RGB values to be in the [0-1] range. There used to be a conflict in expectations here, with R expecting [0-1] and CImg [0-255]. This might break existing code (albeit in minor ways).
  • new function implot, lets you draw on an image using R's base graphics.
  • improved interactive functions for grabbing image regions (grabRect, grabLine, etc.)
  • improved grayscale conversion
  • improved plotting. The default is now to have a constant aspect ratio that matches the aspect ratio of the image.
  • save.image now accepts a quality argument when saving JPEGs.
  • native support for TIFF, now supports non-integer values in TIFF files
  • rm.alpha removes alpha channel, flatten.alpha flattens it
  • imfill now accepts colour names, e.g. imfill(10,10,val='red')
  • improved documentation and examples
  • added functions for conversion to/from CIELAB

imager 0.31 Minor release

  • fixed inline C++ plugin, this time for OS X systems
  • added interpolation option to plot.cimg (to prevent systematic antialiasing when plotting small images)

imager 0.30 Major release.

  • new S3 class imlist improves support for image lists
  • enabled OpenMP. Many CImg primitives now run in parallel.
  • experimental support for CImg's DSL via imeval, patch_summary.
  • improved as.raster,plot. Now support palettes via colourscale argument.
  • new interactive functions for selecting image regions (grabRect,grabPoint,grabLine)
  • new patchstat function for fast extraction of patch statistics
  • new patchmatch function
  • cleaned up the API, improved the documentation
  • fixed bug in inline C++ plugin, should now work on Windows.
  • improved configure script. FFTW3 is now optional (should be less confusing to OSX users)

imager 0.20. Major release

  • added a tutorial (vignette), which includes a worked-out example of multi-scale blob detection
  • new functions:
    • iminfo gives you information on an image file (uses ImageMagick)
    • load.example loads test images
    • crop.borders (self-explanatory)
  • long computations can now be interrupted thanks to update in CImg
  • the array subset operator is now more intelligent: you do not have to specify flat dimensions, i.e. imfill(10,10)[3,1] does what you'd expect (i.e., the same as imfill(10,10)[3,1,1,1])
  • improvements and bugs fixed in print.cimg, as.cimg, imresize, frame, plot.cimg, subim, as.raster, renorm
  • improved documentation and examples

imager 0.16. Bugfix + minor features

  • now has optional "wide" formats
  • load.image now uses readbitmap by default (should work better on Windows)
  • Made the test for ImageMagick more stringent, which fixes a bug in load.image on certain machines
  • Added new reductions which.parmax, which.parmin

imager 0.15: Substantial update

  • User-visible changes:
    • the threshold function now supports auto-thresholding (based on k-means)
    • new accessor functions: imrow, imcol
    • new replacement functions: channel(im,1) <-, R(im) <- , etc.
    • new reduction function: enorm (Euclidean norm of a list of images)
    • improved as.cimg.function, pixel.grid
    • subim is now called imsub for greater consistency (imsub still available as alias)
    • improved documentation
  • Other:
    • Reorganised R code into separate files for clarity

0.14 Minor update

  • Build system now uses configure
  • Fixed paths in Makevars
  • Hopeful bugfix in load.image for Windows 7 users

0.13 Initial release on CRAN

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


0.42.10 by Shota Ochi, 5 months ago,

Report a bug at

Browse source code at

Authors: Simon Barthelme [aut] , David Tschumperle [ctb] , Jan Wijffels [ctb] , Haz Edine Assemlal [ctb] , Shota Ochi [cre]

Documentation:   PDF Manual  

LGPL-3 license

Imports Rcpp, methods, stringr, png, jpeg, readbitmap, grDevices, purrr, downloader, igraph

Depends on magrittr

Suggests knitr, rmarkdown, ggplot2, dplyr, scales, testthat, OpenMPController, raster, spatstat.geom, magick, Cairo

Linking to Rcpp

System requirements: fftw3,libtiff,C++11,X11

Imported by AcuityView, CropDetectR, ForestTools, IMak, Irescale, LARGB, MtreeRing, RPPASPACE, Rbgs, SPUTNIK, TooManyCellsR, WSGeometry, boundingbox, colocr, epca, fmriqa, fractD, lidaRtRee, mand, materialmodifier, multifluo, patternize, sketcher, smpic, wal.

Depended on by BoneProfileR, ImaginR, imagerExtra, redR.

Suggested by CoOL, ProFound, dynaSpec, fieldRS, gsignal, magicaxis, pavo, pbixr, pda, rwavelet, specklestar, wiad.

See at CRAN