i.sentinel.download - GRASS GIS manual

NAME

i.sentinel.download - Downloads Sentinel satellite data from Copernicus Open Access Hub using sentinelsat library.

KEYWORDS

SYNOPSIS

i.sentinel.download

i.sentinel.download --help

i.sentinel.download [-lb] settings=name [output=name] [footprints=name] [map=name] [area_relation=string] [clouds=integer] [producttype=string] [start=string] [end=string] [limit=integer] [query=string] [uuid=string[,string,...]] [sort=string[,string,...]] [order=string] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-l: List filtered products and exit
-b: Use the borders of the AOI polygon and not the region of the AOI
--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:

settings=name [required]: Full path to settings file (user, password); '-' for standard input
output=name: Name for output directory where to store downloaded Sentinel data
footprints=name: Name for output vector map with footprints
map=name: Name of input vector map to define Area of Interest (AOI); If not given then current computational extent is used
area_relation=string: Spatial reation of footprint to AOI; Options: Intersects, Contains, IsWithin; Default: Intersects
clouds=integer: Maximum cloud cover percentage for Sentinel scene
producttype=string: Sentinel product type to filter; Options: SLC, GRD, OCN, S2MSI1C, S2MSI2A, S2MSI2Ap; Default: S2MSI2A
start=string: Start date ('YYYY-MM-DD')
end=string: End date ('YYYY-MM-DD')
limit=integer: Limit number of Sentinel products
query=string: Extra search keywords to use in the query
uuid=string[,string,...]: List of UUID to download
sort=string[,string,...]: Sort by values in given order; Options: ingestiondate, cloudcoverpercentage, footprint; Default: cloudcoverpercentage,ingestiondate,footprint
order=string: Sort order (see sort parameter); Options: asc, desc; Default: asc

DESCRIPTION
NOTES
EXAMPLES
REQUIREMENTS
SEE ALSO
AUTHOR

DESCRIPTION

The i.sentinel.download allows downloading Sentinel products from Copernicus Open Access Hub.

The following product types (parameter producttype) are currently supported:

Sentinel-1 (SAR) products:
- SLC: Single Look Complex (Level-1)
- GRD: Ground Range Detected (Level-1)
- OCN: Ocean products for wind, wave and currents applications (Level-2)
Sentinel-2 (optical) products:
- S2MSI2A: operational Bottom-Of-Atmosphere reflectances in cartographic geometry Level-2A)
- (S2MSI2Ap: pilot products of Bottom-Of-Atmosphere reflectances in cartographic geometry Level-2A), until March 2018)
- S2MSI1C: Top-Of-Atmosphere reflectances in cartographic geometry (Level-1C)

To connect to the Copernicus Open Access Hub both a user name and password are required; see Register new account page for signing up.

i.sentinel.download reads user credentials from settings file. The file must contain at least two lines:

myusername
mypassword

Optionally on third line custom API URL can be defined. Note that empty lines in settings file are silently skipped.

NOTES

User credentials can be also defined interactively when settings=- is given. Note that interactive prompt does not work in GUI.

Insert username: myusername
Insert password: 
Insert API URL (leave empty for https://scihub.copernicus.eu/dhus):

By default Sentinel products are sorted by cloudcoverpercentage and ingestiondate (see sort option). By default, only products which footprint intersects current computation region extent (area of interest, AOI) are filtered. The AOI can be optionally defined also by vector map. In addition the spatial relation between AOI and the footprint (area_relation) can be set to

Contains: to only return scenes where the AOI is contained inside the footprint
IsWithin: to only return scenes where the footprint is contained inside the AOI
Intersects: to return all scenes where the footprint intersects the AOI (default)

Filtered products can be reduced by limit option.

i.sentinel.download limits the default search for products to the last 60 days; an exact date range can be defined by start and end parameters to search beyond that.

Sentinel products can be also filtered by producttype or, in case of Sentinel-2 data, maximum clouds cover percentage.

Extra search keywords can be specified with query. Multiple keywords can be listed separated with comma (e.g. 'polarisationmode=VV,orbitdirection=Ascending'). Note that ESA maintains a list of valid search keywords that can be used with query.

In case a Sentinel data download was interrupted, i.sentinel.download will continue to download once the command is restarted and the partially downloaded file (with .incomplete file extention) still present.

The output directory is created if not yet available.

The query string sent to ESA can be shown with --verbose.

EXAMPLES

List filtered products

Find all atmospherically corrected Sentinel-2 L2A products (S2MSI2) in 2018 (area in Italy as an example):

g.region n=42 w=12 s=41 e=13 res=0:01 -p

i.sentinel.download -l settings=credentials.txt producttype=S2MSI2A start=2018-01-01 end=2018-12-31

357 Sentinel product(s) found
379e2896-408d-4642-bc6f-ee941e395c32 2018-04-19T10:10:31Z  0% S2MSI2A
0e3e361d-e8e0-4e71-a10d-c1faf1640beb 2018-04-19T10:10:31Z  0% S2MSI2A
72ed25c8-5a36-40a5-97ce-e0b4d6347c7f 2018-04-06T10:00:31Z  0% S2MSI2A
eee28af8-aaa6-4e59-9902-dd5cbfc08bab 2018-04-06T10:00:31Z  0% S2MSI2A
e2a9d80d-da35-44bd-ab88-76bad398da41 2018-07-18T10:10:31Z  0% S2MSI2A
...

Sort products by ingestiondate, limit cloud coverage to 3% per scene:

g.region n=42 w=12 s=41 e=13 res=0:01 -p
i.sentinel.download -l settings=credentials.txt producttype=S2MSI2A start=2018-01-01 end=2018-12-31 sort=ingestiondate order=desc clouds=3

191 Sentinel product(s) found
1b0ee27e-c51a-49d9-b2a4-78db128a49f9 2018-12-27T10:04:19Z  0% S2MSI2A
8da04aa9-5d8b-42bc-abb3-d2c9b61c5ee4 2018-12-27T10:04:19Z  1% S2MSI2A
e4f324f4-8e98-440c-9141-ae3d24cd1faa 2018-12-27T10:04:19Z  1% S2MSI2A
be507500-8538-44f0-969c-d6d45a16beea 2018-12-27T10:04:19Z  0% S2MSI2A
1ab5dd20-4845-4325-bd71-5d0596f4d11d 2018-12-27T10:04:19Z  0% S2MSI2A
...

Create a vector map of footprints of S-2 scenes with clouds limited to 3% per scene (note that topological errors will be shown since some footprint overlap):

g.region n=42 w=12 s=41 e=13 res=0:01 -p
i.sentinel.download -l settings=credentials.txt producttype=S2MSI2A start=2018-01-01 end=2018-12-31 clouds=1 footprints=s2_scenes_footprints

131 Sentinel product(s) found
Writing footprints into <s2_scenes_footprints>...
...
379e2896-408d-4642-bc6f-ee941e395c32 2018-04-19T10:10:31Z  0% S2MSI2A
0e3e361d-e8e0-4e71-a10d-c1faf1640beb 2018-04-19T10:10:31Z  0% S2MSI2A
...

Find Sentinel-2 L1C products (S2MSI1C) of last 60 days (default) covering current computation region extent:

g.region n=42 w=12 s=41 e=13 res=0:01 -p
i.sentinel.download -l settings=credentials.txt producttype=S2MSI1C sort=ingestiondate

57 Sentinel product(s) found
c5f6e871-3cd9-471f-a022-712f5e10a43a 2018-11-10T10:12:39Z 15% S2MSI1C
a83ad139-c420-4433-bd21-f7ed35536e69 2018-11-10T10:12:39Z 14% S2MSI1C
6a4f093a-3fa7-466e-8ec9-77718d7b8eac 2018-11-12T10:02:41Z  8% S2MSI1C
9a668bfa-1a7e-4d92-8c51-ed2024415e6a 2018-11-15T10:12:51Z  6% S2MSI1C
5f3d19a2-eddb-42eb-ab6d-67f0fdd18c58 2018-11-15T10:12:51Z  5% S2MSI1C
...

Find Sentinel-1 products by one or several specified UUIDs:

i.sentinel.download -l settings=credentials.txt uuid=a45d5bbe-6919-49fc-84fd-72a7634d2035
a45d5bbe-6919-49fc-84fd-72a7634d2035 2018-06-04T05:26:01Z cloudcover_NA SLC

Find Sentinel-1 products with date range filter and query filter limit to a specific polarisation mode (see here for query details):

i.sentinel.download -l settings=credentials.txt producttype=SLC start=2018-01-01 end=2018-12-31 query='polarisationmode=VV'
34 Sentinel product(s) found
047db83e-db60-45f3-a6d2-3a32588dac01 2018-01-10T23:14:05Z cloudcover_NA SLC
fc6107a5-9daf-45cc-a40a-0e5502c464b6 2018-01-22T23:14:05Z cloudcover_NA SLC
4ad9b650-2954-4ff5-977b-90aedbed6514 2018-02-03T23:14:05Z cloudcover_NA SLC
[...]

Download Sentinel products

Download first (limit=1) S2MSI2A product found into the data directory:

g.region n=42 w=12 s=41 e=13 res=0:01 -p
i.sentinel.download settings=credentials.txt producttype=S2MSI2A start=2018-05-01 end=2018-05-31 limit=1 output=s2_L2A_may2018/

The downloaded Sentinel data can subsequently be easily imported into GRASS GIS using i.sentinel.import module.

Download Sentinel products by UUID

i.sentinel.download also allows downloading of Sentinel products by specifying a (list of) UUID. This operation is performed by the uuid option. Note that this option is mutually exclusive with all other filtering options.

Example of downloading a single Sentinel product by UUID:

i.sentinel.download settings=credentials.txt uuid=6a10da0f-7777-4818-bc2c-4680e82297ac output=s2_data/

Download Sentinel products by scene name

i.sentinel.download also allows downloading of Sentinel products by specifying a (list of) scene names (name of the SAFE.zip file). This operation is performed by the query option. Note that this option is mutually exclusive with all other filtering options.

Example of downloading a single Sentinel product by scene names (name of the SAFE.zip file). Importantly, the producttype, start and end date need to be specified to override the default settings (otherwise no product will be found):

# North Carolina sample dataset example
i.sentinel.download settings=credentials.txt \
  query='filename=S2A_MSIL1C_20180822T155901_N0206_R097_T17SPV_20180822T212023.SAFE' \
  producttype=S2MSI1C start=2018-01-01 end=2018-12-31 output=s2_data/

REQUIREMENTS

AUTHOR

Martin Landa, GeoForAll Lab, CTU in Prague, Czech Republic with support of OpenGeoLabs company

SOURCE CODE

Available at: i.sentinel.download source code (history)