t.import.hrsi - GRASS GIS manual

NAME

t.import.hrsi - Download and import Copernicus High Resolution Snow and Ice Monitoring data as a Space Time Raster Dataset

KEYWORDS

temporal, download, import, raster, time, copernicus, cryosphere, snow, ice

SYNOPSIS

t.import.hrsi

t.import.hrsi --help

t.import.hrsi [-elfpgmow] [output=name] [output_directory=string] product_type=Product type to search and download [cloud_cover=memory in MB] [aoi=Input GeoJSON file with area of interest (AOI)] [start_time=string] [end_time=string] [batch_size=integer] [credits_file=Input file with user credits for HRSI (can also be provided as environment variables)] [memory=memory in MB] [nprocs=Number of cores] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-e: Extend existing STRDS (requires overwrite flag)
-l: Link the raster files using r.external
-f: Link the raster files in a fast way, without reading metadata using r.external
-p: Print info on search results (no download)
-g: Print info on search results in shell script style (no download)
-m: Start and end time are publication time (modification)
-o: Override projection check
-w: Write a log-file to the output directory
--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:

output=name: Name of the output space time raster dataset
output_directory=string: Path to the output directory where downloaded raw data are stored (default is the current directory); Default: ./
product_type=Product type to search and download [required]: Product type to search and download; Options: FractionalSnowCover, GapfilledFractionalSnowCover, PersistentSnowArea, PersistentSnowArea_LAEA, RiverandLakeIceExtent_S1, RiverandLakeIceExtent_S2, RiverandLakeIceExtent_S1_S2, AggregatedRiverandLakeIceExtent, SARWetSnow, WetDrySnow
cloud_cover=memory in MB: Maximum cloud cover in products to download; Maximum cloud cover in products to download
aoi=Input GeoJSON file with area of interest (AOI): Input GeoJSON file with area of interest (AOI)
start_time=string: Earliest timestamp of temporal extent to include in the output; Timestamp in ISO format: "YYYY-MM-DD HH:MM:SS"
end_time=string: Latest timestamp of temporal extent to include in the output; Timestamp in ISO format: "YYYY-MM-DDTHH:MM:SS"
batch_size=integer: Size of batches of files to download; Default: 500
credits_file=Input file with user credits for HRSI (can also be provided as environment variables): Input file with user credits for HRSI (can also be provided as environment variables)
memory=memory in MB: Maximum memory to be used (in MB); Cache size for raster rows; Default: 300
nprocs=Number of cores: Number of cores to use during import; Default: 1

DESCRIPTION
EXAMPLES
- Download fractional snow cover data
REFERENCES
SEE ALSO
AUTHOR

DESCRIPTION

t.import.hrsi downloads High Resolution Snow & Ice (HRSI) data from Copernicus Land Monitoring Services API (available online at: https://cryo.land.copernicus.eu/finder/ and imports the files into an output-SpaceTimeRasterDataset.

Filter parameters

Users can filter what data to download according to query parameters of the underlying REST API. The following filter parameters are supported:

Product types

In the productType option, users can choose which product types to download.

PersistentSnowArea
PersistentSnowArea_LAEA
RiverandLakeIceExtent_S1
RiverandLakeIceExtent_S2
RiverandLakeIceExtent_S1_S2
AggregatedRiverandLakeIceExtent (vector data, currently not supported for import)
SARWetSnow
WetDrySnow
FractionalSnowCover - Sentinel-2 Fractional Snow Cover (FSC) 20m
The Fractional Snow Cover (FSC) product is generated in NRT for the entire EEA38+UK based on optical satellite data from the S2 constellation. The product provides the fraction of the surface covered by snow at the top of canopy and on ground per pixel as a percentage (0% - 100%) with a spatial resolution of 20 m x 20 m.
mission S2
resolution: 20m
subdatasets:
- CLD: (Presence of clouds and cloud shadows)
- FSCOG: On-ground fractional snow cover
- FSCTOC: Top of canopy fractional snow cover
- NDSI: Normalised difference snow index (NDSI)
- QCFLAGS: Expert flags providing quality information obtained during the processing of FSCTOC and FSCOG
- QCOG: Confidence level of the FSCOG layer
- QCTOC: Confidence level of the FSCTOC layer
GapfilledFractionalSnowCover - Sentinel-1 + Sentinel-2 Daily cumulative Gap-filled Fractional Snow Cover (GFSC) 60m
The daily cumulative Gap-filled Fractional Snow Cover (GFSC) product is generated in NRT for the entire EEA38+UK domain based on SAR data from the S1 constellation and optical data from the S2 constellation. The product merges the latest observations available to form a spatially complete overview of snow conditions. The product provides the extent of the snow cover per pixel as a percentage (0% - 100%) with a spatial resolution of 60 m x 60 m. The product uses FSC, WDS and SWS products as input to form a spatially complete composite of snow conditions, to reduce observational gaps due to clouds and lack of sensor coverage on a daily basis. The product applies the on-ground FSC (FSCOG) and SWS and presents the combined information as FSC.
mission: S1-S2
resolution: 60m
subdatasets:
- AT: Sensing start date, seconds from Unix time
- GF: Fractional snow cover (%) and associated information
- QC: Quality layer providing basic assessment of FSC, WDS or SWS quality
- QCFLAGSi: Expert quality flags related to GFSC product quality
PersistentSnowArea: - Sentinel-2 Persistent Snow Area (PSA) 20m
The PSA product is an annual product that is derived from the top of canopy Fractional Snow Cover (FSCTOC) product for the entire EEA38+UK. We refer users to section 2 regarding the description of the algorithm and the content of FSC products. Each PSA product gives access to the persistent snow cover during a particular hydrological year at the resolution of 20 m x 20 m. mission: S2
resolution": 20m
subdatasets:
- PSA: Persistent snow area
- QC: Confidence level of the PSA layer
PersistentSnowArea_LAEA": - Sentinel-2 Persistent Snow Area (PSA) 20m
The PSA product is an annual product that is derived from the top of canopy Fractional Snow Cover (FSCTOC) product for the entire EEA38+UK. We refer users to section 2 regarding the description of the algorithm and the content of FSC products. Each PSA product gives access to the persistent snow cover during a particular hydrological year at the resolution of 20 m x 20 m.
mission: S2
resolution: 20m
subdatasets:
- PSA: Persistent snow area
- QC: Confidence level of the PSA layer
RiverandLakeIceExtent_S1 - Sentinel-1 River and Lake Ice Extent S1 (RLIE S1) 20m
The S1 River and Lake Ice Extent (RLIE S1) product is generated in NRT for the entire EEA38+UK based on synthetic aperture radar data from the S1 constellation. The product focuses on the surface water areas defined by the EU-Hydro database and provides information about river and lake areas covered by snow-covered or snow-free ice, at a spatial resolution of 20 m x 20 m. For the sake of consistency across RLIE products, the RLIE S1 product is delivered on the S2 Level-1C tiling grid, with a pixel size of 20 m x 20 m.
mission: S1
resolution: 20n
subdatasets:
- RLIE: Sentinel-1 River and Lake Ice Extent (RLIE S1)
- QCQuality layer providing basic assessment of RLIE S1 quality
- QCFLAGS: Quality flags related to RLIE product quality
RiverandLakeIceExtent_S2 - Sentinel-2 River and Lake Ice Extent (RLIE S2) 20m
The S2 River and Lake Ice Extent (RLIE S2) product is generated in NRT for the entire EEA38+UK based on optical satellite data from the S2 constellation. The product focuses on the surface water areas defined by the EU-Hydro database and provides the river and lake area covered by snow-covered or snow-free ice, at a spatial resolution of 20 m x 20 m.
mission: S2
resolution: 20m
subdatasets:
- RLIE: Sentinel-2 River and Lake Ice Extent (RLIE S2)
- QC: Quality layer providing basic assessment of RLIE S2 quality
- QCFLAGS: Quality flags related to RLIE product quality
RiverandLakeIceExtent_S1_S2: - Sentinel-1 + Sentinel-2 River and Lake Ice Extent S1+S2 (RLIE S1+S2) 20m
S1 and S2 River and Lake Ice Extent (RLIE S1+S2) is a product generated in delayed-time for the entire EEA38+UK according to RLIE S1 and RLIE S2 overlap. The RLIE S1+S2 is computed as a combination of RLIE S1 and RLIE S2 products acquired on the same date. The product focuses on the surface water areas defined by the EU-Hydro database and provides river and lake areas covered by ice, at a spatial resolution of 20 m x 20 m on the S2 tiling grid.
resolution: 20m
mission: S1-S2
subdatasets:
- RLIE: Sentinel-1 + Sentinel-2 River and Lake Ice Extent (RLIE S1+S2)
- QC: Quality layer providing basic assessment of RLIE S1+S2 quality
- QCFLAGS: Quality flags related to RLIE product quality
AggregatedRiverandLakeIceExtent - Vector data, currently not implemented
SARWetSnow - Sentinel-1 + Sentinel-2 SAR Wet Snow in high mountains (SWS) 60m
The S1 based SAR Wet Snow (SWS) classification is applicable for high-mountain areas within selected S2 tiles of the EEA38+UK domain. For the SWS product generation, 'high mountains' means areas above a certain elevation where no human activities such as tilling agricultural areas are affecting the SAR signal. The SWS product is generated in NRT based on C-band SAR satellite data from the S1 constellation. The product provides binary information on the wet snow extent and the snow free or patchy snow or dry snow extent in high mountain areas. The SWS product is provided with a grid spacing of 60 m by 60 m.
mission: S1
resolution: 60m
subdatasets:
- WSM: Wet Snow classification in high Mountains areas (WSM)
- QCWSM: Quality layer providing basic assessment of WSM quality
WetDrySnow - Sentine-1 + Sentinel-2 Wet/Dry Snow (WDS) 60m
The Wet / Dry Snow (WDS) product provides information on the snow state (wet or dry) by combining S1 based wet snow maps within the snow cover extent observed by means of S2 data (cf. Section 2). The WDS product is provided for each S2 tile with a grid spacing of 60 m by 60 m.
mission: S1
resolution: 60m
subdatasets:
- SSC: Snow State Classification (SSC)
- QCSSC: Quality layer providing basic assessment of the wet snow state classification

Data quality

Product types that are based on Sentinel-2 data can be further filtered using the cloudCover parameter, that limits download of data to scenes that have cloud cover percent less or equal to the given number in percent (0-100).

Temporal filter

Data download can be limited using the start_time and end_time time stamp in ISO format

With the m-flag, the temporal filter parameters start and end refer to modification (publication) time.

Spatial filter

The data download can be spatially filtered either using the bounding box of the computational region or using an input GeoJSON file with one geometry given in the aoi option.

Output

Downloaded data is stored in the output_directory and either linked to the GRASS GIS database (with the l-flag or f-flag, using r.external) or imported using r.in.gdal.

Metadata for the downloaded data is - as far as possibel - stored in the resulting output SpaceTimeRasterDataset as well as in the individual maps. Here, especially the title, description, and if relevant categories are assigned according to the chosen product type.

The module can also be used to update and extend an existing SpaceTimeRasterDataset with newly downloaded data if the e-flag is set.

This module is not sensitive to a possibly existing mask.

Download

Parallel processing is supported, depending on the number of specified parallel processes (nprocs) and the number of input product datasets to download and register.

The download API requires login information which can be either provided with a credits_file, .cryo_land with the same content in the users HOME directory or using environment variebles HRSI_USERNAME and HRSI_PASSWORD.

The batch_size options controls how many datasets are put together in one batch. In general, downloading data in larger batches is slightly faster. However, during larger downloads, the token used internally for authentication can expire, causing the download to fail. Thus, batch size should be set depending on the download speed. The default is set relatively low in order to avoid download errors.

EXAMPLES

Download fractional snow cover data

t.import.hrsi product_type=SARWetSnow aoi=/c/data/aoi.geojson start_time="2023-04-05T00:00:00" \
  end_time="2023-04-05T23:59:59" nprocs=7 memory=2048 output=SARWetSnow --o --v

t.info SARWetSnow
+-------------------- Space Time Raster Dataset -----------------------------+
|                                                                            |
+-------------------- Basic information -------------------------------------+
| Id: ........................ SARWetSnow@PERMANENT
| Name: ...................... SARWetSnow
| Mapset: .................... PERMANENT
| Creator: ................... stbl
| Temporal type: ............. absolute
| Creation time: ............. 2023-06-07 14:19:46.661012
| Modification time:.......... 2023-06-07 14:19:47.197596
| Semantic type:.............. mean
+-------------------- Absolute time -----------------------------------------+
| Start time:................. 2023-04-05 05:55:46
| End time:................... 2023-04-05 17:11:27
| Granularity:................ 40541 seconds
| Temporal type of maps:...... point
+-------------------- Spatial extent ----------------------------------------+
| North:...................... 6933060.0
| South:...................... 6804060.0
| East:.. .................... 198180.0
| West:....................... -21300.0
| Top:........................ 0.0
| Bottom:..................... 0.0
+-------------------- Metadata information ----------------------------------+
| Raster register table:...... raster_map_register_d38496b143274cf58e7c53fd1f408146
| North-South resolution min:. 60.0
| North-South resolution max:. 60.0
| East-west resolution min:... 60.0
| East-west resolution max:... 60.0
| Minimum value min:.......... 1.0
| Minimum value max:.......... 110.0
| Maximum value min:.......... 240.0
| Maximum value max:.......... 255.0
| Aggregation type:........... None
| Number of semantic labels:.. 2
| Semantic labels:............ wet_snow_classes_quality,wet_snow_classes
| Number of registered maps:.. 8
|
| Title:
| Sentinel-1 + Sentinel-2 SAR Wet Snow in high mountains (SWS) 60m
| Description:
| The S1 based SAR Wet Snow (SWS) classification is applicable for high-mountain areas withinselected S2 tiles of the EEA38+UK domain. For the SWS product generation, "high mountains" means areas above a certain elevation where no human activities such as tilling agricultural areas are affecting the SAR signal. The SWS product is generated in NRT based on C-band SAR satellite data from the S1 constellation. The product provides binary information on the wet snow extent and the snow free or patchy snow or dry snow extent in high mountain areas. The SWS product is provided with a grid spacing of 60 m by 60 m.
| Command history:
| # 2023-06-07 14:19:46
| t.create type="strds" temporaltype="absolute"
|     semantictype="mean"
|     title="Sentinel-1 + Sentinel-2 SAR Wet Snow in high mountains (SWS) 60m"
|     description="The S1 based SAR Wet Snow (SWS) classification is applicable for high-mountain areas withinselected S2 tiles of the EEA38+UK domain. For the SWS product generation,  high mountains  means areas above a certain elevation where no human activities such as tilling agricultural areas are affecting the SAR signal. The SWS product is generated in NRT based on C-band SAR satellite data from the S1 constellation. The product provides binary information on the wet snow extent and the snow free or patchy snow or dry snow extent in high mountain areas. The SWS product is provided with a grid spacing of 60 m by 60 m."
|     output="SARWetSnow" --v
|
+----------------------------------------------------------------------------+