t.stac.item - GRASS GIS manual

NAME

t.stac.item - Downloads and imports data from a STAC API server.

KEYWORDS

SYNOPSIS

t.stac.item

t.stac.item --help

t.stac.item [-miadp] url=string collection_id=string [request_method=string] [settings=name] [max_items=integer] [limit=integer] [ids=string] [bbox=float[,float,...]] [intersects=name] [datetime=string] [query=string] [filter=string] [asset_keys=string[,string,...]] [item_roles=string[,string,...]] [filter_lang=string] [sortby=string] [format=string] [strds_output=name] [items_vector=string] [method=string] [resolution=string] [resolution_value=float] [extent=string] [nprocs=integer] [memory=memory in MB] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-m: Collection Search Item Summary
-i: Item metadata
-a: Asset metadata
-d: Dowload and import assets
-p: Pretty print the JSON output
--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:

url=string [required]: STAC API Client URL
collection_id=string [required]: Collection Id.
request_method=string: The HTTP method to use when making a request to the service.; Options: GET, POST; Default: POST
settings=name: Full path to settings file (user, password); '-' for standard input
max_items=integer: The maximum number of items to return from the search, even if there are more matching results.; Default: 1000
limit=integer: A recommendation to the service as to the number of items to return per page of results. Defaults to 100.; Default: 100
ids=string: List of one or more Item ids to filter on.
bbox=float[,float,...]: The bounding box of the request in WGS84 (example [-72.5,40.5,-72,41]). (default is current region)
intersects=name: Name of input vector map; Results filtered to only those intersecting the geometry.
datetime=string: Datetime Filter; Either a single datetime or datetime range used to filter results.
query=string: List or JSON of query parameters as per the STAC API query extension.
filter=string: JSON of query parameters as per the STAC API filter extension
asset_keys=string[,string,...]: Asset Keys; List of one or more asset keys to filter item downloads.
item_roles=string[,string,...]: Item roles; List of one or more item roles to filter by.
filter_lang=string: Language variant used in the filter body. If filter is a dictionary or not provided, defaults to cql2-json. If filter is a string, defaults to cql2-text.; Options: cql2-json, cql2-text
sortby=string: A single field or list of fields to sort the response by
format=string: Output format; Options: json, plain; Default: json
strds_output=name: STRDS Output; Spatial Temporal Raster Dataset Registration File
items_vector=string: Name of vector containing STAC item boundaries and metadata.
method=string: Resampling method to use for reprojection (required if location projection not longlat); Options: nearest, bilinear, bicubic, lanczos, bilinear_f, bicubic_f, lanczos_f; Default: nearest; 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
resolution=string: Resolution of output raster map (default: estimated); Options: estimated, value, region; Default: estimated; estimated: estimated resolution; value: user-specified resolution; region: current region resolution
resolution_value=float: Resolution of output raster map (use with option resolution=value)
extent=string: Output raster map extent; Options: input, region; Default: input; input: extent of input map; region: extent of current region
nprocs=integer: Number of threads for parallel computing; Default: 1
memory=memory in MB: Maximum memory to be used (in MB); Cache size for raster rows; Default: 300

DESCRIPTION
NOTES
REQUIREMENTS
EXAMPLES
AUTHENTICATION
SEE ALSO
AUTHORS
Sponsors

DESCRIPTION

t.stac.item is a tool for exploring and importing SpatioTemporal Asset Catalog item metadata and assets into GRASS GIS. The tool is based on the PySTAC_Client (0.8) library and allows you to search items in a STAC Catalog. The search can be done by specifying the item ID, collection ID, datatime or by using a search query. The full list of search parameters and documentation can be found at PySTAC_Client ItemSearch.

NOTES

The t.stac.item tool is part of the t.stac temporal data processing framework. The tool requries that the data provider has implement the STAC API and conforms to Item Search specification.

REQUIREMENTS

PySTAC (1.10.x)
PySTAC_Client (0.8)
tqdm (4.66.x)
numpy (1.26.x)

EXAMPLES

Get the item metadata from a STAC API.


    t.stac.catalog url="https://earth-search.aws.element84.com/v1/"
    t.stac.collection url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a"
    t.stac.item -i url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a" item_id="S2B_36QWD_20220301_0_L2A"

Get the asset metadata from a STAC API.


    t.stac.catalog url="https://earth-search.aws.element84.com/v1/"
    t.stac.collection url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a"
    t.stac.item -a url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a" item_id="S2B_36QWD_20220301_0_L2A"

Dpwnload the asset from a STAC API.


    t.stac.catalog url="https://earth-search.aws.element84.com/v1/"
    t.stac.collection url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a"
    t.stac.item -d url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a" item_id="S2B_36QWD_20220301_0_L2A"

GRASS Jupyter Notebooks can be used to visualize the catalog metadata.


    from grass import gs
    catalog = gs.parse_command('t.stac.catalog', url="https://earth-search.aws.element84.com/v1/")

    print(catalog)

    # Output
    {'conformsTo': ['https://api.stacspec.org/v1.0.0/core',
                'https://api.stacspec.org/v1.0.0/collections',
                'https://api.stacspec.org/v1.0.0/ogcapi-features',
                'https://api.stacspec.org/v1.0.0/item-search',
                'https://api.stacspec.org/v1.0.0/ogcapi-features#fields',
                'https://api.stacspec.org/v1.0.0/ogcapi-features#sort',
                'https://api.stacspec.org/v1.0.0/ogcapi-features#query',
                'https://api.stacspec.org/v1.0.0/item-search#fields',
                'https://api.stacspec.org/v1.0.0/item-search#sort',
                'https://api.stacspec.org/v1.0.0/item-search#query',
                'https://api.stacspec.org/v0.3.0/aggregation',
                'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core',
                'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30',
                'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson'],
 'description': 'A STAC API of public datasets on AWS',
 'id': 'earth-search-aws',
 'stac_version': '1.0.0',
 'title': 'Earth Search by Element 84',
 'type': 'Catalog'}

STAC Catalog plain text metadata


t.stac.catalog url=https://earth-search.aws.element84.com/v1/ format=plain

# Output
    Client Id: earth-search-aws
    Client Title: Earth Search by Element 84
    Client Description: A STAC API of public datasets on AWS
    Client STAC Extensions: []
    Client Extra Fields: {'type': 'Catalog', 'conformsTo': ['https://api.stacspec.org/v1.0.0/core', 'https://api.stacspec.org/v1.0.0/collections', 'https://api.stacspec.org/v1.0.0/ogcapi-features', 'https://api.stacspec.org/v1.0.0/item-search', 'https://api.stacspec.org/v1.0.0/ogcapi-features#fields', 'https://api.stacspec.org/v1.0.0/ogcapi-features#sort', 'https://api.stacspec.org/v1.0.0/ogcapi-features#query', 'https://api.stacspec.org/v1.0.0/item-search#fields', 'https://api.stacspec.org/v1.0.0/item-search#sort', 'https://api.stacspec.org/v1.0.0/item-search#query', 'https://api.stacspec.org/v0.3.0/aggregation', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson']}
    Client catalog_type: ABSOLUTE_PUBLISHED
    ---------------------------------------------------------------------------
    Collections: 9
    sentinel-2-pre-c1-l2a: Sentinel-2 Pre-Collection 1 Level-2A
    Sentinel-2 Pre-Collection 1 Level-2A (baseline < 05.00), with data and metadata matching collection sentinel-2-c1-l2a
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2015-06-27T10:25:31.456000Z', None]]}}
    License: proprietary
    ---------------------------------------------------------------------------
    cop-dem-glo-30: Copernicus DEM GLO-30
    The Copernicus DEM is a Digital Surface Model (DSM) which represents the surface of the Earth including buildings, infrastructure and vegetation. GLO-30 Public provides limited worldwide coverage at 30 meters because a small subset of tiles covering specific countries are not yet released to the public by the Copernicus Programme.
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2021-04-22T00:00:00Z', '2021-04-22T00:00:00Z']]}}
    License: proprietary
    ---------------------------------------------------------------------------
    naip: NAIP: National Agriculture Imagery Program
    The [National Agriculture Imagery Program](https://www.fsa.usda.gov/programs-and-services/aerial-photography/imagery-programs/naip-imagery/) (NAIP) provides U.S.-wide, high-resolution aerial imagery, with four spectral bands (R, G, B, IR).  NAIP is administered by the [Aerial Field Photography Office](https://www.fsa.usda.gov/programs-and-services/aerial-photography/) (AFPO) within the [US Department of Agriculture](https://www.usda.gov/) (USDA).  Data are captured at least once every three years for each state.  This dataset represents NAIP data from 2010-present, in [cloud-optimized GeoTIFF](https://www.cogeo.org/) format.
    Extent: {'spatial': {'bbox': [[-160, 17, -67, 50]]}, 'temporal': {'interval': [['2010-01-01T00:00:00Z', '2022-12-31T00:00:00Z']]}}
    License: proprietary
    ---------------------------------------------------------------------------
    cop-dem-glo-90: Copernicus DEM GLO-90
    The Copernicus DEM is a Digital Surface Model (DSM) which represents the surface of the Earth including buildings, infrastructure and vegetation. GLO-90 provides worldwide coverage at 90 meters.
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2021-04-22T00:00:00Z', '2021-04-22T00:00:00Z']]}}
    License: proprietary
    ---------------------------------------------------------------------------
    landsat-c2-l2: Landsat Collection 2 Level-2
    Atmospherically corrected global Landsat Collection 2 Level-2 data from the Thematic Mapper (TM) onboard Landsat 4 and 5, the Enhanced Thematic Mapper Plus (ETM+) onboard Landsat 7, and the Operational Land Imager (OLI) and Thermal Infrared Sensor (TIRS) onboard Landsat 8 and 9.
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['1982-08-22T00:00:00Z', None]]}}
    License: proprietary
    ---------------------------------------------------------------------------
    sentinel-2-l2a: Sentinel-2 Level-2A
    Global Sentinel-2 data from the Multispectral Instrument (MSI) onboard Sentinel-2
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2015-06-27T10:25:31.456000Z', None]]}}
    License: proprietary
    ---------------------------------------------------------------------------
    sentinel-2-l1c: Sentinel-2 Level-1C
    Global Sentinel-2 data from the Multispectral Instrument (MSI) onboard Sentinel-2
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2015-06-27T10:25:31.456000Z', None]]}}
    License: proprietary
    ---------------------------------------------------------------------------
    sentinel-2-c1-l2a: Sentinel-2 Collection 1 Level-2A
    Sentinel-2 Collection 1 Level-2A, data from the Multispectral Instrument (MSI) onboard Sentinel-2
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2015-06-27T10:25:31.456000Z', None]]}}
    License: proprietary
    ---------------------------------------------------------------------------
    sentinel-1-grd: Sentinel-1 Level-1C Ground Range Detected (GRD)
    Sentinel-1 is a pair of Synthetic Aperture Radar (SAR) imaging satellites launched in 2014 and 2016 by the European Space Agency (ESA). Their 6 day revisit cycle and ability to observe through clouds makes this dataset perfect for sea and land monitoring, emergency response due to environmental disasters, and economic applications. This dataset represents the global Sentinel-1 GRD archive, from beginning to the present, converted to cloud-optimized GeoTIFF format.
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2014-10-10T00:28:21Z', None]]}}
    License: proprietary
    ---------------------------------------------------------------------------

Basic STAC catalog metadata


    t.stac.catalog url=https://earth-search.aws.element84.com/v1/ format=plain -b

    # Output
    Client Id: earth-search-aws
    Client Title: Earth Search by Element 84
    Client Description: A STAC API of public datasets on AWS
    Client STAC Extensions: []
    Client Extra Fields: {'type': 'Catalog', 'conformsTo': ['https://api.stacspec.org/v1.0.0/core', 'https://api.stacspec.org/v1.0.0/collections', 'https://api.stacspec.org/v1.0.0/ogcapi-features', 'https://api.stacspec.org/v1.0.0/item-search', 'https://api.stacspec.org/v1.0.0/ogcapi-features#fields', 'https://api.stacspec.org/v1.0.0/ogcapi-features#sort', 'https://api.stacspec.org/v1.0.0/ogcapi-features#query', 'https://api.stacspec.org/v1.0.0/item-search#fields', 'https://api.stacspec.org/v1.0.0/item-search#sort', 'https://api.stacspec.org/v1.0.0/item-search#query', 'https://api.stacspec.org/v0.3.0/aggregation', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson']}
    Client catalog_type: ABSOLUTE_PUBLISHED
    ---------------------------------------------------------------------------

AUTHENTICATION

The t.stac.catalog tool supports authentication with the STAC API using the GDAL's virtual fie system /vsi/.

Basic Authentication


    t.stac.catalog url="https://earth-search.aws.element84.com/v1/" settings="user:password"

SOURCE CODE

Available at: t.stac.item source code (history)

Latest change: Monday Sep 23 17:27:16 2024 in commit: 96a6bd1bc83c1da5c4e06222e11966c96d5aef0e