Raster Images

Two-dimensional RasterLayer objects (from the raster package) can be turned into images and added to Leaflet maps using the addRasterImage function.

The addRasterImage function works by projecting the RasterLayer object to EPSG:3857 and encoding each cell to an RGBA color, to produce a PNG image. That image is then embedded in the map widget.

It’s important that the RasterLayer object is tagged with a proper coordinate reference system. Many raster files contain this information, but some do not. Here is how you’d tag a raster layer object “r” which contains WGS84 data:

crs(r) <- sp::CRS("+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs")

Large Raster Warning

Because the addRasterImage function embeds the image in the map widget, it will increase the size of the generated HTML proportionally. In order to avoid unacceptable download times and memory usage, addRasterImage will error when the PNG is beyond the size indicated by the maxBytes argument (defaults to 4 megabytes).

If you have a large raster layer, you can provide a larger number of bytes and see how it goes, or use raster::resample or raster::aggregate to decrease the number of cells.

Projection Performance

The addRasterImage function projects using raster::projectRaster, which can take a while on all but the smallest rasters. To improve performance, the first thing to do is install a new version of raster; version 2.4 includes optimizations that speed up bilinear projection by about 10X. This version has not yet been released to CRAN at the time of this writing (June 17, 2015) but can be installed directly from R-Forge:

install.packages('raster', repos = 'http://r-forge.r-project.org/', type = 'source')

If you have a large raster layer or expect to call addRasterImage on the same raster layer many times, you can perform the EPSG:3857 projection yourself (either using leaflet::projectRasterForLeaflet or using another GIS library or program) and call addRasterImage with project = FALSE.

Be sure that your pre-projected raster layer is tagged with an accurate extent and CRS, as these values are still needed to place the image in the proper position on the map.


In order to render the RasterLayer as an image, each cell value must be converted to an RGB(A) color. You can specify the color scale using the colors argument, which accepts a variety of color specifications:

  • The name of a Color Brewer 2 palette. If no colors argument is provided, then "Spectral" is the default.
  • A vector that represents the ordered list of colors to map to the data. Any color specification that is accepted by grDevices::col2rgb can be used, including "#RRGGBB" and "#RRGGBBAA" forms. Example: colors = c("#E0F3DB", "#A8DDB5", "#43A2CA").
  • A color scaling function, like those detailed in the Colors topic. For example: colors = colorBin("Greens", domain = NULL, bins = 5, na.color = "transparent").



r <- raster("nc/oisst-sst.nc")
pal <- colorNumeric(c("#0C2C84", "#41B6C4", "#FFFFCC"), values(r),
  na.color = "transparent")

leaflet() %>% addTiles() %>%
  addRasterImage(r, colors = pal, opacity = 0.8) %>%
  addLegend(pal = pal, values = values(r),
    title = "Surface temp")

The "leaflet" R package is copyright © 2014-2016 RStudio, Inc.
The Leaflet JavaScript library is © 2010–2016 Vladimir Agafonkin, 2010–2011 CloudMade.
Maps © OpenStreetMap contributors unless otherwise noted.

Fork me on GitHub