elevatr (version 0.4.5)

get_elev_raster: Get Raster Elevation

Description

Several web services provide access to raster elevation. Currently, this function provides access to the Amazon Web Services Terrian Tiles and the Open Topography global datasets API. The function accepts a data.frame of x (long) and y (lat), an sp, or raster object as input. A raster object is returned.

Usage

get_elev_raster(
  locations,
  z,
  prj = NULL,
  src = c("aws", "gl3", "gl1", "alos", "srtm15plus"),
  expand = NULL,
  clip = c("tile", "bbox", "locations"),
  verbose = TRUE,
  neg_to_na = FALSE,
  override_size_check = FALSE,
  ...
)

Value

Function returns a RasterLayer in the projection specified by the prj argument.

Arguments

locations

Either a data.frame of x (long) and y (lat), an sp, sf, or raster object as input.

z

The zoom level to return. The zoom ranges from 1 to 14. Resolution of the resultant raster is determined by the zoom and latitude. For details on zoom and resolution see the documentation from Mapzen at https://github.com/tilezen/joerd/blob/master/docs/data-sources.md#what-is-the-ground-resolution. The z is not required for the OpenTopography data sources.

prj

A string defining the projection of the locations argument. The string needs to be an acceptable SRS_string for CRS-class for your version of PROJ. If a sf object, a sp object or a raster object is provided, the string will be taken from that. This argument is required for a data.frame of locations.

src

A character indicating which API to use. Currently supports "aws" and "gl3", "gl1", "alos", or "srtm15plus" from the OpenTopography API global datasets. "aws" is the default.

expand

A numeric value of a distance, in map units, used to expand the bounding box that is used to fetch the terrain tiles. This can be used for features that fall close to the edge of a tile or for retrieving additional area around the feature. If the feature is a single point, the area it returns will be small if clip is set to "bbox". Default is NULL.

clip

A character value used to determine clipping of returned DEM. The default value is "tile" which returns the full tiles. Other options are "bbox" which returns the DEM clipped to the bounding box of the original locations (or expanded bounding box if used), or "locations" if the spatials data (e.g. polygons) in the input locations should be used to clip the DEM. Locations are not used to clip input point datasets. Instead the bounding box is used.

verbose

Toggles on and off the note about units and coordinate reference system.

neg_to_na

Some of the data sources return large negative numbers as missing data. When the end result is a projected those large negative numbers can vary. When set to TRUE, only zero and positive values are returned. Default is FALSE.

override_size_check

Boolean to override size checks. Any download between 100 Mb and 500Mb report a message but continue. Between 500Mb and 3000Mb requires interaction and greater than 3000Mb fails. These can be overriden with this argument set to TRUE.

...

Extra arguments to pass to httr::GET via a named vector, config. See get_aws_terrain for more details.

Details

Currently, the get_elev_raster function utilizes the Amazon Web Services (https://registry.opendata.aws/terrain-tiles/) terrain tiles and the Open Topography Global Datasets API (https://opentopography.org/developers).

The AWS Terrain Tiles data is provided via x, y, and z tiles (see https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames for details.) The x and y are determined from the bounding box of the object submitted for locations argument, and the z argument must be specified by the user.

Examples

if (FALSE) {
data(lake)

loc_df <- data.frame(x = runif(6,min=sp::bbox(lake)[1,1], 
                               max=sp::bbox(lake)[1,2]),
                     y = runif(6,min=sp::bbox(lake)[2,1], 
                               max=sp::bbox(lake)[2,2]))
# Example for PROJ > 5.2.0
x <- get_elev_raster(locations = loc_df, prj = sp::wkt(lake) , z=10)

# Example for PROJ < 5.2.0 
x <- get_elev_raster(locations = loc_df, prj = sp::proj4string(lake) , z=10)
x <- get_elev_raster(lake, z = 12, serial = TRUE)
x <- get_elev_raster(lake, src = "gl3", expand = 5000)
}