tmap (version 3.3-4)

tm_basemap: Draw a tile layer

Description

Creates a tmap-element that draws a tile layer. This feature is only available in view mode. For plot mode, a tile image can be retrieved by read_osm. The function tm_basemap draws the tile layer as basemap (i.e. as bottom layer), whereas tm_tiles draws the tile layer as overlay layer (where the stacking order corresponds to the order in which this layer is called). Note that basemaps are shown by default (see details).

Usage

tm_basemap(server = NA, group = NA, alpha = NA, tms = FALSE)
tm_tiles(server, group = NA, alpha = 1, zindex = NA, tms = FALSE)

Arguments

server

name of the provider or an URL. The list of available providers can be obtained with providers (tip: in RStudio, type providers$ to see the options). See https://leaflet-extras.github.io/leaflet-providers/preview/ for a preview of those. When a URL is provided, it should be in template format, e.g. "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png". Use NULL in tm_basemap to disable the basemaps.

group

name of the group to which this layer belongs in view mode. Each group can be selected or deselected in the layer control item. Set group = NULL to hide the layer in the layer control item. By default, it will be set to the name of the shape (specified in tm_shape). Tile layers generated with tm_basemap will be base groups whereas tile layers generated with tm_tiles will be overlay groups.

alpha

alpha

tms

is the provided tile server defined according to the TMS protocol? By default FALSE.

zindex

zindex of the pane in view mode. By default, it is set to the layer number plus 400. By default, the tmap layers will therefore be placed in the custom panes "tmap401", "tmap402", etc., except for the base tile layers, which are placed in the standard "tile". This parameter determines both the name of the pane and the z-index, which determines the pane order from bottom to top. For instance, if zindex is set to 500, the pane will be named "tmap500".

Details

When tm_basemap is not specified, the default basemaps are shown, which can be configured by the basemaps arugument in tmap_options. By default (for style "white") three basemaps are drawn: c("Esri.WorldGrayCanvas", "OpenStreetMap", "Esri.WorldTopoMap"). To disable basemaps, add tm_basemap(NULL) to the plot, or set tmap_options(basemaps = NULL). Similarly, when tm_tiles is not specified, the overlay maps specified by the overlays argument in in tmap_options are shown as front layer. By default, this argument is set to NULL, so no overlay maps are shown by default. See examples.

Examples

if (FALSE) {
current.mode <- tmap_mode("view")

data(World, metro)

tm_basemap(leaflet::providers$Stamen.Watercolor) +
tm_shape(metro, bbox = "India") + tm_dots(col = "red", group = "Metropolitan areas") +
tm_tiles(paste0("http://services.arcgisonline.com/arcgis/rest/services/Canvas/",
    "World_Light_Gray_Reference/MapServer/tile/{z}/{y}/{x}"), group = "Labels")


# Use tmap options to set the basemap and overlay map permanently during the R session:
opts <- tmap_options(basemaps = c(Canvas = "Esri.WorldGrayCanvas", Imagery = "Esri.WorldImagery"),
    overlays = c(Labels = paste0("http://services.arcgisonline.com/arcgis/rest/services/Canvas/",
                                 "World_Light_Gray_Reference/MapServer/tile/{z}/{y}/{x}")))
	
	qtm(World, fill = "HPI", fill.palette = "RdYlGn")

# restore options
tmap_options(opts)

# restore current mode
tmap_mode(current.mode)
}