Florian-Katerndahl / callusgs

callusgs Aims To Be A Complete Implementation Of USGS's machine-to-machine API (v1.5.0)
https://callusgs.readthedocs.io/en/latest/
GNU General Public License v2.0
0 stars 0 forks source link
api cli download earth-explorer eros geodata gis landsat machine-to-machine remote-sensing usgs

callusgs

Documentation Status DOI FAIR checklist badge

callusgs aims to be a complete and (mostly) typed implementation of USGS's machine-to-machine API (v1.5.0). In addition, callusgs provides a suite of command line tools that can be used to query and download scenes, use the geocoding service provided by the USGSS and convert WRS 1/2 coordinates to geographic coordinates.

Features

callusgs is both a Python package and a suite of command line tools that allows

  1. Downloading of select products (see table below)
  2. Access to the USGS geocoding API
  3. Conversion between the WRS1 and WRS2 grids to geographic coordinates and
  4. clean up of download order queues (mainly as utility functionality)

Currently supported products for download are:

Product string Prodcut Name
landsat_em_c2_l1 Landsat 4/5 Collection 2 Level 1
landsat_em_c2_l2 Landsat 4/5 Collection 2 Level 2
landsat_etm_c2_l1 Landsat 7 Collection 2 Level 1
landsat_etm_c2_l2 Landsat 7 Collection 2 Level 2
landsat_ot_c2_l1 Landsat 8/9 Collection 2 Level 1
landsat_ot_c2_l2 Landsat 8/9 Collection 2 Level 2
landsat_ba_tile_c2 Landsat Burned Area Product
landsat_dswe_tile_c2 Landsat Dynamic Surface Water Extent
landsat_fsca_tile_c2 Landsat Fractional Snow Covered Area
gmted2010 GMTED 2010 DEM

Installation

Install the package together with the respective command line applications from pip.

pip install callusgs

Alternatively, if you're only interested in the CLI functionality of this tool the best choice is probably to use pipx for installation.

pipx install callusgs

Usage

For more detailed usage instructions and/or examples, please refer to the documentation or see the section below.

Prerequisites

To fully use the package's/the API's functionality you need (1) an account at USGS and (2) access to M2M MACHINE role. While the first one is mandatory, the functionality without access to the M2M MACHINE role is restricted (see table below). The account credentials need to be passed to the command line tools via CLI arguments or by setting the environment variables USGS_USERNAME and USGS_AUTH.

Feature/Functionality Usable Note
Searching for scenes Yes
Creating scene lists out of search results Yes
Generate orders from scene searches or scene lists No Downloading orders from list, when order was placed via webinterface is possible
Geocoding Yes
WRS1/WRS2 to coordinate transformation Yes

Command Line Tool Examples

Download

The snippet below queries the EarthExplorer catalogue for Landsat 8/9 Collection 2 Level 2 scenes between June 1st, 2020 and July 25th, 2024 for a small part of the southwest of Berlin, Germany. Additionally, only scenes for August and September are returned and they must have a cloudcover of no more than 15%. Results are stored in a directory called download. The user set the logging level to INFO with the -v flag.

callusgs -v download --product landsat_etm_c2_l2 \
    --date 2020-06-01 2024-07-25 --month aug sep \
    --cloudcover 0 15 --aoi-coordinates 52.5 13.4 52.5 13.2 52.7 13.2 52.5 13.4 -- download

The snippet below queries the EarthExplorer catalogue for Landsat 7 Collection 2 Level 1 scenes between January 1st, 2005 and January 1st, 2020 for Lima, Peru, and its surrounding region. For the given polygon, the minimum bound recatangle is build and used for the query. No further restrictions regarding the obervation months or cloudcouver are posed. Results would be stored in a directory called download, but as a dry run is requested, only the number of available scenes and their download size is reported. The user requested extended debug output with the -vv flag.

callusgs -vv --dry-run download --product landsat_etm_c2_l1 \
    --date 2005-01-01 2020-01-01 --aoi-type Mbr \
    --aoi-coordinates -11.99 -77.13 -11.97 -77.00 -12.01 -76.88 -12.07 -76.88 -12.13 -76.89 -12.07 -77.16 -11.99 -77.13 -- \
    download

Geocode

The USGS supplies a simplistic geocoding/POI-search endpoint which can be queries using the geocode sub-program. The snippet below queries all U.S. features whos placename attribute matches "New York".

[!WARNING] Right now, the placename endpoint, which is called under the hood, does not return any results for features of type "world"!

callusgs geocode --feature-type US "New York"

Grid2ll

Get either centroids or polygons of the WRS2 or WRS2 coordinate system based on geographic coordinates in WGS84 (EPSG:4326) inputs. The snipped below queries the centroid coordinates for three points in the WRS2 system.

callusgs grid2ll --response-shape point 52,11 32,5 89,69

Clean

The clean subprogram is used to delete dangeling product/scene orders.

callusgs -v clean

Known Limitations

Documentation

See the docs folder for raw documentation or visit callusgs.readthedocs.io.

License

Citation

If you use this software, please use the bibtex entry below or refer to the citation file.

@software{Katerndahl2024,
author = {Katerndahl, Florian},
doi = {10.5281/zenodo.13351646},
version = {v0.1.3},
month = {8},
title = {callusgs},
url = {https://github.com/Florian-Katerndahl/callusgs},
year = {2024}
}

Acknowledgments