r.in.usgs

Download user-requested products through the USGS TNM API

Command linePython (grass.script)

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

Example:

r.in.usgs product=string output_name=name cache_size_tolerance=20

grass.script.run_command("r.in.usgs", product, output_name=None, ned_dataset="ned1sec", input_srs=None, resolution=None, title_filter=None, resampling_method="default", memory=300, nprocs=1, cache_size_tolerance=20, output_directory=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.in.usgs", product="string", output_name="name", cache_size_tolerance=20)

Parameters

Command linePython (grass.script)

product=string [required]
    USGS data product
    Available USGS data products to query
    Allowed values: ned, naip, lidar
output_name=name
    Name for output raster map
ned_dataset=string
    NED dataset
    Available NED datasets to query
    Allowed values: 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 tiles by their title (e.g. use "Phase4")
    To avoid combining tiles from multiple years, use first -i flag and filter by tile title.
resampling_method=string
    Resampling method to use
    Allowed values: 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
cache_size_tolerance=integer [required]
    Tolerance for file size difference between cached file and stated download size
    The size difference is used to recognize failed downloads and corrupted files, but some difference occurs naturally
    Default: 20
output_directory=name
    Cache directory for download and processing
    Defaults to system user cache directory (e.g., .cache)
-i
    Return USGS data information without downloading files
-d
    Download files only
-k
    Keep imported tiles in the mapset after patch
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

product : str, required
    USGS data product
    Available USGS data products to query
    Allowed values: ned, naip, lidar
output_name : str, optional
    Name for output raster map
    Used as: output, raster, name
ned_dataset : str, optional
    NED dataset
    Available NED datasets to query
    Allowed values: ned1sec, ned13sec, ned19sec
    ned1sec: NED 1 arc-second
    ned13sec: NED 1/3 arc-second
    ned19sec: NED 1/9 arc-second
    Default: ned1sec
input_srs : str, optional
    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, optional
    Resolution of lidar-based DSM
title_filter : str, optional
    Filter available tiles by their title (e.g. use "Phase4")
    To avoid combining tiles from multiple years, use first -i flag and filter by tile title.
resampling_method : str, optional
    Resampling method to use
    Allowed values: default, nearest, bilinear, bicubic, lanczos, bilinear_f, bicubic_f, lanczos_f
    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
    Default: default
memory : int, optional
    Maximum memory to be used (in MB)
    Cache size for raster rows during import and reprojection
    Default: 300
nprocs : int, optional
    Number of processes which will be used for parallel import and reprojection
    Default: 1
cache_size_tolerance : int, required
    Tolerance for file size difference between cached file and stated download size
    The size difference is used to recognize failed downloads and corrupted files, but some difference occurs naturally
    Default: 20
output_directory : str, optional
    Cache directory for download and processing
    Defaults to system user cache directory (e.g., .cache)
    Used as: input, dir, name
flags : str, optional
    Allowed values: i, d, k
    i
        Return USGS data information without downloading files
    d
        Download files only
    k
        Keep imported tiles in the mapset after patch
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

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 local cache directory, then imported, and patched together. 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. If the d flag is set, data is downloaded but not imported and processed.

By default, downloaded files are kept in a user cache directory according to the operating system standards. These files can be reused in case a different, but overlapping, 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 cache directory after the import. The location of the cache directory depends on the operating system. You can clear the cache by deleting the directory. Where this directory is depends on operating system, for example on Linux, it is under ~/.cache, on macOS under ~/Library/Caches, and on Microsoft Windows under the Application Data directory. If you have limited space or other special needs, you can set output_directory to a custom directory, e.g., /tmp on Linux. The custom directory needs to exist before calling this module.

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:

g.region raster=elevation
r.in.usgs product=ned ned_dataset=ned19sec 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_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_name=ned_small

For a different extent we download NAIP imagery and we use a custom cache directory (replace /tmp by an existing path suitable for your operating system and needs):

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)
Latest change: Monday Apr 07 11:20:56 2025 in commit de46f6a