Title:	Access Elevation Data from Various APIs
Version:	0.99.0
URL:	https://github.com/jhollist/elevatr/
BugReports:	https://github.com/jhollist/elevatr/issues/
Maintainer:	Jeffrey Hollister <hollister.jeff@epa.gov>
Description:	Several web services are available that provide access to elevation data. This package provides access to many of those services and returns elevation data either as an 'sf' simple features object from point elevation services or as a 'raster' object from raster elevation services. In future versions, 'elevatr' will drop support for 'raster' and will instead return 'terra' objects. Currently, the package supports access to the Amazon Web Services Terrain Tiles https://registry.opendata.aws/terrain-tiles/, the Open Topography Global Datasets API https://opentopography.org/developers/, and the USGS Elevation Point Query Service https://apps.nationalmap.gov/epqs/.
Depends:	R (≥ 3.5.0)
Imports:	httr, jsonlite, progressr, sf, terra, future, furrr, purrr, units, slippymath, curl, raster, methods
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.2.3
Suggests:	testthat, knitr, rmarkdown, formatR, progress
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2023-09-12 11:22:36 UTC; JHollist
Author:	Jeffrey Hollister [aut, cre], Tarak Shah [ctb], Jakub Nowosad [ctb], Alec L. Robitaille [ctb], Marcus W. Beck [rev], Mike Johnson [ctb]
Repository:	CRAN
Date/Publication:	2023-09-12 21:00:02 UTC

Assumes geographic projection sf bbox to poly

Description

Assumes geographic projection sf bbox to poly

Usage

bbox_to_sf(bbox, prj = 4326)

Arguments

function to clip the DEM

Description

function to clip the DEM

Usage

clip_it(rast, loc, expand, clip)

Access elevation data from the web

Description

This package provides tools to access and download elevation data available from the Mapzen elevation and Mapzen terrain service.

Estimate download size of DEMs

Description

Estimate download size of DEMs

Usage

estimate_raster_size(locations, prj, src, z = NULL)

Arguments

Get point elevation data from the AWS Terrain Tiles

Description

Function for accessing elevation data from AWS and extracting the elevations

Usage

get_aws_points(
  locations,
  z = 5,
  units = c("meters", "feet"),
  verbose = TRUE,
  ...
)

Arguments

Value

a list with a SpatialPointsDataFrame or sf POINT or MULTIPOINT object with elevation added to the data slot and a character of the elevation units

Get a digital elevation model from the AWS Terrain Tiles

Description

This function uses the AWS Terrain Tile service to retrieve an elevation raster from the geotiff service. It accepts a sf::st_bbox object as input and returns a single raster object covering that extent.

Usage

get_aws_terrain(
  locations,
  z,
  prj,
  expand = NULL,
  ncpu = future::availableCores() - 1,
  serial = NULL,
  ...
)

Arguments

Source

Attribution: Mapzen terrain tiles contain 3DEP, SRTM, and GMTED2010 content courtesy of the U.S. Geological Survey and ETOPO1 content courtesy of U.S. National Oceanic and Atmospheric Administration. https://github.com/tilezen/joerd/tree/master/docs

Get Point Elevation

Description

This function provides access to point elevations using either the USGS Elevation Point Query Service (US Only) or by extracting point elevations from the AWS Terrain Tiles. The function accepts a data.frame of x (long) and y (lat) or a sf POINT or MULTIPOINT object as input. A sf POINT or MULTIPOINT object is returned with elevation and elevation units as an added data.frame.

Usage

get_elev_point(
  locations,
  prj = NULL,
  src = c("epqs", "aws"),
  overwrite = FALSE,
  ...
)

Arguments

Value

Function returns an sf object in the projection specified by the prj argument.

Examples

## Not run: 
library(elevatr)
library(sf)
library(terra)

mts <- data.frame(x = c(-71.3036, -72.8145), 
                  y = c(44.2700, 44.5438), 
                  names = c("Mt. Washington", "Mt. Mansfield"))
ll_prj <- 4326
mts_sf <- st_as_sf(x = mts, coords = c("x", "y"), crs = ll_prj)
#Empty Raster
mts_raster <- rast(mts_sf, nrow = 5, ncol = 5)
# Raster with cells for each location
mts_raster_loc <- terra::rasterize(mts_sf, rast(mts_sf, nrow = 10, ncol = 10))

get_elev_point(locations = mts, prj = ll_prj)
get_elev_point(locations = mts, units="feet", prj = ll_prj)
get_elev_point(locations = mts_sf)
get_elev_point(locations = mts_raster)
get_elev_point(locations = mts_raster_loc)


# Code to split into a loop and grab point at a time.
# This is usually faster for points that are spread apart 
 
library(dplyr)

elev <- vector("numeric", length = nrow(mts))
for(i in seq_along(mts)){
elev[i]<-get_elev_point(locations = mts[i,], prj = ll_prj, src = "aws", 
                        z = 10)$elevation}
mts_elev <- cbind(mts, elev)
mts_elev

## End(Not run)

Get Raster Elevation

Description

Several web services provide access to raster elevation. Currently, this function provides access to the Amazon Web Services Terrain Tiles and the Open Topography global datasets API. The function accepts a data.frame of x (long) and y (lat), an sf, or terra object as input. A RasterLayer object is returned. In subsequent versions, a SpatRaster will be 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,
  ...
)

Arguments

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.

Value

Function returns a RasterLayer in the projection specified by the prj argument or in the projection of the provided locations. In subsequent versions, a SpatRaster will be returned.

Examples

## Not run: 
library(elevatr)
library(sf)
data(lake)
lake_buff  <- st_buffer(lake, 1000)
loc_df <- data.frame(x = runif(6,min=sf::st_bbox(lake)$xmin, 
                               max=sf::st_bbox(lake)$xmax),
                     y = runif(6,min=sf::st_bbox(lake)$ymin, 
                               max=sf::st_bbox(lake)$ymax))
                               
x <- get_elev_raster(locations = loc_df, prj = st_crs(lake) , z=10)
x <- get_elev_raster(lake, z = 12)
x <- get_elev_raster(lake, src = "gl3", expand = 5000)
x <- get_elev_raster(lake_buff, z = 10, clip = "locations")

## End(Not run)

Get point elevation data from the USGS Elevation Point Query Service

Description

Function for accessing elevation data from the USGS epqs

Usage

get_epqs(
  locations,
  units = c("meters", "feet"),
  ncpu = future::availableCores() - 1,
  serial = NULL
)

Arguments

Value

a list with a SpatialPointsDataFrame or sf POINT or MULTIPOINT object with elevation added to the data slot and a character of the elevation units

Get a digital elevation model from the Open Topography SRTM Version 3

Description

This function uses the Open Topography SRTM Version 3 files.

Usage

get_opentopo(locations, src, prj, expand = NULL, ...)

Arguments

Source

Attribution: Details here

OpenTopo Key

Description

The OpenTopography API now requires an API Key. This function will grab your key from an .Renviron file

Usage

get_opentopo_key()

function to get a data.frame of all xyz tiles to download

Description

function to get a data.frame of all xyz tiles to download

Usage

get_tilexy(bbx, z)

SpatialPolygonsDataFrame of Lake Sunapee

Description

This example data is a SpatialPolygonsDataFrame of a single lake, Lake Sunapee. Used for examples and tests.

Format

SpatialPolygonDataframe with 1 lakes, each with 13 variables

function to convert lat long to xyz tile with decimals rounding to tile occurs in get_tilexy

Description

function to convert lat long to xyz tile with decimals rounding to tile occurs in get_tilexy

Usage

latlong_to_tilexy(lon_deg, lat_deg, zoom)

function to check input type and projection. All input types convert to a SpatialPointsDataFrame for point elevation and bbx for raster.

Description

function to check input type and projection. All input types convert to a SpatialPointsDataFrame for point elevation and bbx for raster.

Usage

loc_check(locations, prj = NULL)

Merge Rasters

Description

Merge multiple downloaded raster files into a single file. The input 'target_prj' describes the projection for the new grid.

Usage

merge_rasters(
  raster_list,
  target_prj,
  method = "bilinear",
  returnRaster = TRUE
)

Arguments

function to project bounding box and if needed expand it

Description

function to project bounding box and if needed expand it

Usage

proj_expand(locations, prj, expand)

Small data frame of xy locations

Description

Example data frame of locations for use in examples and text

Format

A data.frame with two columns, x(long) and y(lat)

Store OpenTopography Key

Description

This function stores an OpenTopgrapy key in a local .Renviron file. If the .Renviron file exists, the key will be appended. This will typically only need to be done once per machine.

Usage

set_opentopo_key(key)

Arguments

A sf POINT dataset of random points

Description

This sf POINT dataset is 250 uniform random points to be used for examples and tests

Format

A sf POINT object