basemap {basemaps}

Get a spatial basemap

Description

These functions (down)load and cache a basemap of a defined extent ext, map_service and map_type and return it as an object of the defined class. Alternatively to defining the following arguments, set_defaults can be used to define basemap preferences once for the running session.

Usage

basemap(
  ext = NULL,
  map_service = NULL,
  map_type = NULL,
  map_res = NULL,
  map_token = NULL,
  map_dir = NULL,
  class = "plot",
  force = FALSE,
  ...,
  verbose = TRUE
)

basemap_plot(
  ext = NULL,
  map_service = NULL,
  map_type = NULL,
  map_res = NULL,
  map_token = NULL,
  map_dir = NULL,
  force = NULL,
  ...,
  verbose = TRUE
)

basemap_magick(
  ext = NULL,
  map_service = NULL,
  map_type = NULL,
  map_res = NULL,
  map_token = NULL,
  map_dir = NULL,
  force = NULL,
  ...,
  verbose = TRUE
)

basemap_png(
  ext = NULL,
  map_service = NULL,
  map_type = NULL,
  map_res = NULL,
  map_token = NULL,
  map_dir = NULL,
  force = NULL,
  ...,
  verbose = TRUE
)

basemap_geotif(
  ext = NULL,
  map_service = NULL,
  map_type = NULL,
  map_res = NULL,
  map_token = NULL,
  map_dir = NULL,
  force = NULL,
  ...,
  verbose = TRUE
)

basemap_terra(
  ext = NULL,
  map_service = NULL,
  map_type = NULL,
  map_res = NULL,
  map_token = NULL,
  map_dir = NULL,
  force = NULL,
  ...,
  verbose = TRUE
)

basemap_raster(
  ext = NULL,
  map_service = NULL,
  map_type = NULL,
  map_res = NULL,
  map_token = NULL,
  map_dir = NULL,
  force = NULL,
  ...,
  verbose = TRUE
)

basemap_stars(
  ext = NULL,
  map_service = NULL,
  map_type = NULL,
  map_res = NULL,
  map_token = NULL,
  map_dir = NULL,
  force = NULL,
  ...,
  verbose = TRUE
)

basemap_ggplot(
  ext = NULL,
  map_service = NULL,
  map_type = NULL,
  map_res = NULL,
  map_token = NULL,
  map_dir = NULL,
  force = NULL,
  ...,
  verbose = TRUE
)

basemap_gglayer(
  ext = NULL,
  map_service = NULL,
  map_type = NULL,
  map_res = NULL,
  map_token = NULL,
  map_dir = NULL,
  force = NULL,
  ...,
  verbose = TRUE
)

basemap_mapview(
  ext = NULL,
  map_service = NULL,
  map_type = NULL,
  map_res = NULL,
  map_token = NULL,
  map_dir = NULL,
  force = NULL,
  ...,
  verbose = TRUE
)

Arguments

ext

extent to be covered by the basemap as any spatial class supported by st_bbox.

map_service

character, a map service, either "osm", "carto" or "mapbox". Default is "osm".

map_type

character, a map type, e.g. "streets". For a full list of available map types, see get_maptypes.

map_res

numeric, resolution of base map in range from 0 to 1.

map_token

character, authentication token for services that require registration, which are "osm_stamen", "osm_stadia", "osm_thunderforest" and "mapbox". Register at https://stadiamaps.com/ (for stamen and stadia), https://www.thunderforest.com/ and/or https://www.mapbox.com/ to get tokens. Ignored for all other map services.

map_dir

character, cache directory where downloaded basemap tiles will be stored. By default, a temporary directory is used, which is destroyed when the session is terminated.

class

character, output class, either either plot (default), magick, png, geotif or if suggested packages are installed, terra, raster, stars, ggplot, gglayer or mapview.

force

logical, whether to force download over cached files or not. Default is FALSE.

...

additional arguments, including

• browse, logical, for class = "png" and interactive sessions only. Whether to open the png file in the system's default PNG viewer or not. Default is TRUE.

• col, character vector of colours for transforming single-layer basemaps into RGB, if class = "png" or class = "magick". Default is topo.colors(25).

• dpi, numeric vector of length 1 or 2 specifying the resolution of the image in DPI (dots per inch) for x and y (in that order) - it is recycled to length 2.

• etc. (see ?gg_raster for valid arguments when using class = "gglayer" or class = "ggplot", including maxpixels to control resolution of ggplot outputs

verbose

logical, if TRUE, messages and progress information are displayed on the console (default).

Value

A basemap of the defined class in Web/Pseudo Mercator Projection (EPSG: 3857)

Note

See get_maptypes for available map services and their sources.

The use of the map services "osm_thunderforest" and "mapbox" require registration to obtain an API token/key which can be supplied to map_token. Register at https://www.thunderforest.com/ and/or https://www.mapbox.com/ to get a token.

Examples

library(basemaps)

# example extent
data(ext)

# view all available maps
get_maptypes()

# set defaults for the basemap
set_defaults(map_service = "osm", map_type = "terrain_bg")
# for "osm_stamen", "osm_stadia", osm "thunderforest" and "mapbox" maps, you need a API token. 
# Register for free at stadiamaps.com, thunderforest.com and mapbox.com to get tokens.

## Not run: 
# load and return basemap map as raster (default)
map <- basemap(ext)

# or explicitely as different classes such as:
basemap_magick(ext)
basemap_raster()
basemap_stars()

# or as files:
basemap_geotif()
basemap_png()

# or as plots:
basemap_plot(ext)
basemap_mapview()

# including ggplot2:
basemap_ggplot(ext)

# or as ggplot2 layer:
library(ggplot2)
ggplot() + 
  basemap_gglayer(ext) +
  scale_fill_identity() + 
  coord_sf()

# or, when combined with an sf vector object,
# make sure to use Web/Pseudo Mercator (EPSG 3857), as this is
# the CRS in which all basemaps are returned (see "Value"):
library(sf)
ext <- st_transform(ext,  crs = st_crs(3857))
ggplot() + 
  basemap_gglayer(ext) + 
  geom_sf(data = ext, color = "red", fill = "transparent") +
  coord_sf() +
  scale_fill_identity()
 
## End(Not run)