tmaptools: bb – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

bb

Bounding box generator

Description

Swiss army knife for bounding boxes. Modify an existing bounding box or create a new bounding box from scratch. See details.

Usage

bb(
  x = NA,
  ext = NULL,
  cx = NULL,
  cy = NULL,
  width = NULL,
  height = NULL,
  xlim = NULL,
  ylim = NULL,
  relative = FALSE,
  asp.limit = NULL,
  current.projection = NULL,
  projection = NULL,
  output = c("bbox", "matrix", "extent")
)

Arguments

`x`	One of the following: A shape from class `sf`, `stars`, `sp`, or `raster`. A bounding box (`st_bbox`, `Extent` (`raster` package, which will no longer be supported in the future versions), numeric vector of 4 (default order: xmin, ymin, xmax, ymax), or a 2x2 matrix). Open Street Map search query. The bounding is automatically generated by querying `x` from Open Street Map Nominatim. See `geocode_OSM` and https://wiki.openstreetmap.org/wiki/Nominatim. If `x` is not specified, a bounding box can be created from scratch (see details).
`ext`	Extension factor of the bounding box. If 1, the bounding box is unchanged. Values smaller than 1 reduces the bounding box, and values larger than 1 enlarges the bounding box. This argument is a shortcut for both `width` and `height` with `relative=TRUE`. If a negative value is specified, then the shortest side of the bounding box (so width or height) is extended with `ext`, and the longest side is extended with the same absolute value. This is especially useful for bounding boxes with very low or high aspect ratios.
`cx`	center x coordinate
`cy`	center y coordinate
`width`	width of the bounding box. These are either absolute or relative (depending on the argument `relative`).
`height`	height of the bounding box. These are either absolute or relative (depending on the argument `relative`).
`xlim`	limits of the x-axis. These are either absolute or relative (depending on the argument `relative`).
`ylim`	limits of the y-axis. See `xlim`.
`relative`	boolean that determines whether relative values are used for `width`, `height`, `xlim` and `ylim` or absolute. If `x` is unspecified, `relative` is set to `"FALSE"`.
`asp.limit`	maximum aspect ratio, which is width/height. Number greater than or equal to 1. For landscape bounding boxes, `1/asp.limit` will be used. The returned bounding box will have an aspect ratio between `1/asp.limit` and `asp.limit`.
`current.projection`	projection that corresponds to the bounding box specified by `x`.
`projection`	projection to transform the bounding box to.
`output`	output format of the bounding box, one of: `"bbox"` a `sf::bbox` object, which is a numeric vector of 4: xmin, ymin, xmax, ymax. This representation used by the `sf` package. `"matrix"` a 2 by 2 numeric matrix, where the rows correspond to x and y, and the columns to min and max. This representation used by the `sp` package. `"extent"` an `raster::extent` object, which is a numeric vector of 4: xmin, xmax, ymin, ymax. This representation used by the `raster` package.

Details

An existing bounding box (defined by x) can be modified as follows:

Using the extension factor ext.
Changing the width and height with width and height. The argument relavitve determines whether relative or absolute values are used.
Setting the x and y limits. The argument relavitve determines whether relative or absolute values are used.

A new bounding box can be created from scratch as follows:

Using the extension factor ext.
Setting the center coorinates cx and cy, together with the width and height.
Setting the x and y limits xlim and ylim

Value

bounding box (see argument output)

Examples

if (require(tmap) && packageVersion("tmap") >= "2.0") {

    ## load shapes
    data(NLD_muni)
    data(World)

    ## get bounding box (similar to sp's function bbox)
    bb(NLD_muni)

    ## extent it by factor 1.10
    bb(NLD_muni, ext=1.10)

    ## convert to longlat
    bb(NLD_muni, projection=4326)

    ## change existing bounding box
    bb(NLD_muni, ext=1.5)
    bb(NLD_muni, width=2, relative = TRUE)
    bb(NLD_muni, xlim=c(.25, .75), ylim=c(.25, .75), relative = TRUE)

}

## Not run: 
if (require(tmap)) {
    bb("Limburg", projection = "rd")
    bb_italy <- bb("Italy", projection = "eck4")

    tm_shape(World, bbox=bb_italy) + tm_polygons()
    # shorter alternative: tm_shape(World, bbox="Italy") + tm_polygons()
}
## End(Not run)

tmaptools

Thematic Map Tools

v3.1-1

GPL-3

Authors

Martijn Tennekes [aut, cre]

Initial release

2021-01-19

bb