r.in.usgs - GRASS GIS manual

NAME

r.in.usgs - Download user-requested products through the USGS TNM API

KEYWORDS

SYNOPSIS

r.in.usgs

r.in.usgs --help

r.in.usgs [-ik] product=string output_name=name output_directory=name [ned_dataset=string] [input_srs=string] [resolution=float] [title_filter=string] [resampling_method=string] [memory=integer] [nprocs=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-i: Return USGS data information without downloading files
-k: Keep extracted files after GRASS import and patch
--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

product=string [required]: USGS data product; Available USGS data products to query; Options: ned, naip, lidar
output_name=name [required]: Name for output raster map
output_directory=name [required]: Directory for USGS data download and processing
ned_dataset=string: NED dataset; Available NED datasets to query; Options: ned1sec, ned13sec, ned19sec; Default: ned1sec; ned1sec: NED 1 arc-second; ned13sec: NED 1/3 arc-second; ned19sec: NED 1/9 arc-second
input_srs=string: Input lidar dataset projection (WKT or EPSG, e.g. EPSG:4326); Override input lidar dataset coordinate system using EPSG code or WKT definition
resolution=float: Resolution of lidar-based DSM
title_filter=string: Filter available lidar tiles by their title (e.g. use "Phase4"); To avoid combining lidar from multiple years, use first -i flag and filter by tile title.
resampling_method=string: Resampling method to use; Options: default, nearest, bilinear, bicubic, lanczos, bilinear_f, bicubic_f, lanczos_f; Default: default; default: default method based on product; nearest: nearest neighbor; bilinear: bilinear interpolation; bicubic: bicubic interpolation; lanczos: lanczos filter; bilinear_f: bilinear interpolation with fallback; bicubic_f: bicubic interpolation with fallback; lanczos_f: lanczos filter with fallback
memory=integer: Maximum memory to be used (in MB); Cache size for raster rows during import and reprojection; Default: 300
nprocs=integer: Number of processes which will be used for parallel import and reprojection; Default: 1

DESCRIPTION
NOTES
EXAMPLE
REFERENCES
SEE ALSO
AUTHORS

DESCRIPTION

r.in.usgs downloads and patches selected USGS datasets (NED, NAIP, lidar) to the current GRASS computational region and coordinate reference system. Associated parameters are automatically passed to The National Map Access API, downloaded to a user-specified local directory, then imported and patched. r.in.usgs supports the following datasets:

ned: National Elevation Dataset
naip: NAIP orthoimagery
lidar: Lidar Point Clouds (LPC)

National Land Cover Dataset (NLCD) is no longer available through the API.

NOTES

NED data are available at resolutions of 1 arc-second (about 30 meters), 1/3 arc-second (about 10 meters), and in limited areas at 1/9 arc-second (about 3 meters).

NAIP is available at 1 m resolution.

Lidar data is available only for part of the US but there can be multiple spatially overlapping datasets from different years. All point clouds will be imported as points using v.in.pdal and then patched and interpolated with v.surf.rst. In some cases, lidar point clouds do not have SRS information, use input_srs to specify it (e.g. "EPSG:2264"). If multiple tiles from different years are available, use title_filter to filter by their titles (e.g. "Phase1"). Use i flag to list the tiles first.

If the i flag is set, only information about data meeting the input parameters is displayed without downloading the data.

By default, downloaded files are kept in the specified output_direcory, so that they can be reused in case different computational region is required. However, unzipped files and imported rasters before patching are removed. If the k flag is set, extracted files from compressed archives are also kept within the download directory after the import.

By default, resampling method is chosen based on the nature of the dataset, bilinear for NED and nearest for NAIP. This can be changed with option resampling_method.

EXAMPLE

We will download NED 1/9 arc-second digital elevation model in the extent of raster 'elevation'. First, we just list the files to be downloaded (change output directory depending on the operating system):

g.region raster=elevation
r.in.usgs product=ned ned_dataset=ned19sec output_directory=/tmp output_name=ned -i

USGS file(s) to download:
-------------------------
Total download size:	826.95 MB
Tile count:	4
USGS SRS:	wgs84
USGS tile titles:
USGS NED ned19_n35x75_w078x75_nc_statewide_2003 1/9 arc-second 2012 15 x 15 minute IMG
USGS NED ned19_n36x00_w078x75_nc_statewide_2003 1/9 arc-second 2012 15 x 15 minute IMG
USGS NED ned19_n35x75_w079x00_nc_statewide_2003 1/9 arc-second 2012 15 x 15 minute IMG
USGS NED ned19_n36x00_w079x00_nc_statewide_2003 1/9 arc-second 2012 15 x 15 minute IMG
-------------------------
To download USGS data, remove i flag, and rerun r.in.usgs.

We proceed with the download:

r.in.usgs product=ned ned_dataset=ned19sec output_directory=/tmp output_name=ned
r.colors map=ned_small color=grey

We change the computational region to a smaller extent and create a new DEM, downloaded files will be used.

g.region n=224649 s=222000 w=633000 e=636000
r.in.usgs product=ned ned_dataset=ned19sec output_directory=/tmp output_name=ned_small

For a different extent we download NAIP imagery:

g.region n=224649 s=222000 w=636000 e=639000
r.in.usgs product=naip output_directory=/tmp output_name=ortho

Figure: Downloaded NED (large and small extent), NAIP orthoimagery, and NLCD land cover (NLCD is not available since 2020 through the API)

REFERENCES

TNM Access API Guide
National Elevation Dataset
National Land Cover Dataset

AUTHORS

Zechariah Krautwurst, 2017 MGIST Candidate, North Carolina State University
(initial version, Google Summer of Code 2017, mentors: Anna Petrasova, Vaclav Petras)

Anna Petrasova, NCSU GeoForAll Lab
Vaclav Petras, NCSU GeoForAll Lab

SOURCE CODE

Available at: r.in.usgs source code (history)