layer_static_mapbox: Make a static Mapbox ggplot2 layer or tmap basemap
In walkerke/mapboxapi: R Interface to 'Mapbox' Web Services

layer_static_mapbox

R Documentation

Make a static Mapbox ggplot2 layer or tmap basemap

Description

These functions wrap static_mapbox() and ggspatial::layer_spatial() or tmap::tm_rgb() to support the use of images from the Mapbox Static Maps API as ggplot2 or tmap basemaps.

Usage

layer_static_mapbox(
  location = NULL,
  buffer_dist = 1000,
  units = "m",
  style_id,
  username,
  style_url = NULL,
  overlay_sf = NULL,
  overlay_style = NULL,
  overlay_markers = NULL,
  width = NULL,
  height = NULL,
  scale = 0.5,
  scaling_factor = c("1x", "2x"),
  attribution = TRUE,
  logo = TRUE,
  before_layer = NULL,
  access_token = NULL,
  ...
)

tm_static_mapbox(
  location = NULL,
  buffer_dist = 1000,
  units = "m",
  style_id,
  username,
  style_url = NULL,
  overlay_sf = NULL,
  overlay_style = NULL,
  overlay_markers = NULL,
  width = NULL,
  height = NULL,
  scale = 0.5,
  scaling_factor = c("1x", "2x"),
  attribution = TRUE,
  logo = TRUE,
  before_layer = NULL,
  access_token = NULL,
  ...
)

Arguments

`location`	An input location for which you would like to request tiles. Can be a length-4 vector representing a bounding box, or an `sf` object. If an input `sf` object is supplied, use the `buffer_dist` argument to control how much area you want to capture around the layer. While the input `sf` object can be in an arbitrary coordinate reference system, if a length-4 bounding box vector is supplied instead it must represent WGS84 longitude/latitude coordinates and be in the order `c(xmin, ymin, xmax, ymax)`.
`buffer_dist`	The distance to buffer around an input `sf` object for determining static map, specified in units. If location is a POINT object of 2 rows or less and `buffer_dist` is 0 or `NULL`, a 1 unit buffer is applied to try to ensure the creation of a valid bounding box for the map area.
`units`	Units of `buffer_dist`; defaults to "m" (meters). If buffer_dist is a units class object, the units argument is ignored.
`style_id`	A style ID (required if style_url is `NULL`).
`username`	A Mapbox username (required if `style_url = NULL`).
`style_url`	A Mapbox style url; defaults to `NULL`.
`overlay_sf`	The overlay `sf` object (optional). The function will convert the `sf` object to GeoJSON then plot over the basemap style. Spatial data that are too large will trigger an error, and should be added to the style in Mapbox Studio instead.
`overlay_style`	A named list of vectors specifying how to style the sf overlay. Possible names are "stroke", "stroke-width" (or "stroke_width"), "stroke-opacity" (or "stroke_opacity"), "fill", and "fill-opacity" (or "fill_opacity"). The fill and stroke color values can be specified as six-digit hex codes or color names, and the opacity and width values should be supplied as floating-point numbers. If overlay_style is `NULL`, the style values can be pulled from columns with the same names in `overlay_sf`.
`overlay_markers`	The prepared overlay markers (optional). See the function prep_overlay_markers for more information on how to specify a marker overlay.
`width`, `height`	The map width and height; defaults to `NULL`
`scale`	ratio to scale the output image; `scale = 1` will return the largest possible image. defaults to 0.5
`scaling_factor`	The scaling factor of the tiles; either `"1x"` (the default) or `"2x"`
`attribution`	Controls whether there is attribution on the image. Defaults to `TRUE`. If `FALSE`, the watermarked attribution is removed from the image. You still have a legal responsibility to attribute maps that use OpenStreetMap data, which includes most maps from Mapbox. If you specify `attribution = FALSE`, you are legally required to include proper attribution elsewhere on the webpage or document.
`logo`	Controls whether there is a Mapbox logo on the image. Defaults to `TRUE`.
`before_layer`	A character string that specifies where in the hierarchy of layer elements the overlay should be inserted. The overlay will be placed just above the specified layer in the given Mapbox styles. List layer ids for a map style with `get_style(style_id = style_id, username = username, style_url = style_url, access_token = access_token)[["layers"]][["id"]]`
`access_token`	A Mapbox access token; which can be set with mb_access_token.
`...`	additional parameters passed to ggspatial::layer_spatial or tmap::tm_rgb

Details

This function uses a different approach than get_static_tiles(). Instead, layer_static_mapbox() is based largely on layer_mapbox() in the snapbox package (available under a MIT license. There are a few key differences between layer_static_mapbox() and layer_mapbox(). The "scale" parameter is equivalent to the "scale_ratio" parameter for snapbox. Setting scale_factor = "2x" is equivalent to setting retina = TRUE. Both functions return basemaps that are no larger than a single tile (a maximum of 1280 by 1280 pixels).

For tm_static_mapbox(), tmap::tm_shape is called with projection = 3857 and tmap::tm_rgb is called with max.value = 1.