The goal of ceramic is to obtain web map tiles. Use a spatial object to define the region of interest.

We can use raster, sp, or sf objects to define an extent. This provides a very easy way to obtain imagery or elevation data for any almost any region using our own data.

Even if the data uses a map projection it will be converted into a region to match the Mercator extents used by Mapbox image servers.

There are basic heuristics to decide if data is projected or just in “longitude,latitude” in the usual raster package way.

Raster elevation data is also available.

north <- nz[nz$Island == "North", ]
dem_nz <- cc_elevation(north)
#> Preparing to download: 15 tiles at zoom = 7 from 
#> https://api.mapbox.com/v4/mapbox.terrain-rgb/


## plot elevation data for NZ north
dem_nz[!dem_nz > 0] <- NA
raster::plot(dem_nz, col = grey(seq(0, 1, length = 51)), breaks = quantile(raster::values(dem_nz), seq(0, 1, length = 52), na.rm = TRUE), legend = FALSE)
plot(st_transform(st_cast(north, "MULTILINESTRING")["Name"], raster::projection(dem_nz)), add = TRUE, lwd = 5)

Providers

The default map provider is Mapbox, but ceramic is written for general usage and also provides access to the joerd AWS tiles via the type = "elevation-tiles-prod" argument.

Use max_tiles or zoom to increase or decrease resolution.

im1 <- cc_location(im_nz, debug = TRUE)
#> Preparing to download: 12 tiles at zoom = 6 from 
#> https://api.mapbox.com/v4/mapbox.satellite/
#> [1] "/perm_storage/home/mdsumner/.cache/.ceramic/api.mapbox.com/v4/mapbox.satellite/6/61/38.jpg"
#> [1] "/perm_storage/home/mdsumner/.cache/.ceramic/api.mapbox.com/v4/mapbox.satellite/6/62/38.jpg"
#> [1] "/perm_storage/home/mdsumner/.cache/.ceramic/api.mapbox.com/v4/mapbox.satellite/6/63/38.jpg"
#> [1] "/perm_storage/home/mdsumner/.cache/.ceramic/api.mapbox.com/v4/mapbox.satellite/6/61/39.jpg"
#> [1] "/perm_storage/home/mdsumner/.cache/.ceramic/api.mapbox.com/v4/mapbox.satellite/6/62/39.jpg"
#> [1] "/perm_storage/home/mdsumner/.cache/.ceramic/api.mapbox.com/v4/mapbox.satellite/6/63/39.jpg"
#> [1] "/perm_storage/home/mdsumner/.cache/.ceramic/api.mapbox.com/v4/mapbox.satellite/6/61/40.jpg"
#> [1] "/perm_storage/home/mdsumner/.cache/.ceramic/api.mapbox.com/v4/mapbox.satellite/6/62/40.jpg"
#> [1] "/perm_storage/home/mdsumner/.cache/.ceramic/api.mapbox.com/v4/mapbox.satellite/6/63/40.jpg"
#> [1] "/perm_storage/home/mdsumner/.cache/.ceramic/api.mapbox.com/v4/mapbox.satellite/6/61/41.jpg"
#> [1] "/perm_storage/home/mdsumner/.cache/.ceramic/api.mapbox.com/v4/mapbox.satellite/6/62/41.jpg"
#> [1] "/perm_storage/home/mdsumner/.cache/.ceramic/api.mapbox.com/v4/mapbox.satellite/6/63/41.jpg"
im2 <- cc_location(im_nz, zoom = 7)
#> Preparing to download: 35 tiles at zoom = 7 from 
#> https://api.mapbox.com/v4/mapbox.satellite/

im1
#> class      : RasterBrick 
#> dimensions : 736, 548, 403328, 3  (nrow, ncol, ncell, nlayers)
#> resolution : 2445.985, 2445.985  (x, y)
#> extent     : 18533228, 19873627, -5845904, -4045659  (xmin, xmax, ymin, ymax)
#> crs        : +proj=merc +a=6378137 +b=6378137 
#> source     : memory
#> names      : layer.1, layer.2, layer.3 
#> min values :       0,       4,       0 
#> max values :     255,     255,     255

im2
#> class      : RasterBrick 
#> dimensions : 1470, 1095, 1609650, 3  (nrow, ncol, ncell, nlayers)
#> resolution : 1222.992, 1222.992  (x, y)
#> extent     : 18534451, 19873627, -5844681, -4046882  (xmin, xmax, ymin, ymax)
#> crs        : +proj=merc +a=6378137 +b=6378137 
#> source     : memory
#> names      : layer.1, layer.2, layer.3 
#> min values :       0,       5,       0 
#> max values :     255,     255,     255

Installation

Install ceramic from CRAN with:

install.packages("ceramic")

You can install the development version of ceramic from Github.

Set your mapbox API key with

Sys.setenv(MAPBOX_API_KEY = "<yourkey>")

Example

This complete example gets tiled imagery that we can use as real data.

The code here

  • generates a bounding box in longitude-latitude
  • uses slippymath to find sensible tiles for the region
  • downloads them to a local cache
  • georeferences them and merges the tiles into a sensible raster object

Local caching of tiles

A key feature of ceramic is caching, all data is downloaded in a systematic way that is suitable for later re-use. Many tools for imagery services treat the imagery as transient, but here we take control over the raw data itself. All file names match exactly the address URL of the original source data.

There is a helper function to find existing tiles.

and every row has the extent values useable directly by raster:

Another example

my_bbox <-
  st_bbox(c(xmin = 144,
            xmax = 147.99,
            ymin = -44.12,
            ymax = -40),
          crs = st_crs("+proj=longlat +ellps=WGS84"))
im <- cc_location(cbind(145.5, -42.2), buffer = 5e5)
#> Preparing to download: 6 tiles at zoom = 6 from 
#> https://api.mapbox.com/v4/mapbox.satellite/
plotRGB(im)
plot(st_transform(ozmaps::abs_lga$geometry, projection(im)), add = TRUE, lwd = 2, border = "white")

An internal function sets up a plot of tiles at particular zoom levels.

tile plot

tile plot

And we can add the tiles to an existing plot.

plotRGB(im)
ceramic::plot_tiles(ceramic_tiles(zoom = 7), add = TRUE)
tile add plot

tile add plot

Future improvements

See the Issue tab and please make suggestions and give feedback!


Please note that the ‘ceramic’ project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.