Usage
Usage of the Python API
To use S2Downloader in a project:
import os
import s2downloader
from s2downloader.s2downloader import s2DataDownloader
from s2downloader.config import loadConfiguration, Config
config_file = os.path.abspath("../data/default_config.json")
config = loadConfiguration(path=config_file)
Config(**config)
s2DataDownloader(config_dict=config)
Note:
Since version 1.0.0 s2Downloader uses the new version of element84’s catalog for querying through the downloadable data. If you want to use the old version of the catalog (v0) for any reason, fall back to version 0.4.3 of s2Downloader. More information about the catalog changes.
Command line utilities
s2downloader_cli.py
At the command line, S2Downloader provides the s2downloader_cli.py. Run with relative or absolute path to config json file:
S2Downloader --filepath "path/to/config.json"
Input and Output
Expected Input Configuration
The package expects a configuration file in json format, like the default_config.json in the repository. A valid configuration for downloading data might look like follows:
{
"user_settings": {
"tile_settings": {
"platform": {
"in": [
"sentinel-2b",
"sentinel-2a"
]
},
"s2:nodata_pixel_percentage": {
"lte": 100
},
"mgrs:utm_zone": {},
"mgrs:latitude_band": {},
"mgrs:grid_square": {},
"eo:cloud_cover": {
"lte": 100
},
"bands": [
"coastal",
"blue",
"rededge1"
]
},
"aoi_settings": {
"bounding_box": [
13.058397,
52.376620,
13.073049,
52.383835
],
"apply_SCL_band_mask": true,
"SCL_filter_values": [
3,
7,
8,
9,
10
],
"aoi_min_coverage": 90,
"SCL_masked_pixels_max_percentage": 20,
"valid_pixels_min_percentage": 10,
"resampling_method": "cubic",
"date_range": [
"2021-09-04",
"2021-09-05"
]
},
"result_settings": {
"results_dir": "data/data_output/",
"target_resolution": 10,
"download_data": true,
"download_thumbnails": false,
"download_overviews": false,
"logging_level": "INFO"
}
},
"s2_settings": {
"collections": [
"sentinel-2-l2a"
],
"tiles_definition_path": "data/sentinel_2_index_shapefile_attr.zip"
}
}
Simplified example for using a Polygon instead of a bounding box. The bounding_box option has to stay as empty list when a polygon is added.
{
"user_settings": {
"aoi_settings": {
"bounding_box": [],
"polygon": {
"coordinates": [[
[13.015460350735339,52.37318812959998],
[13.065452289464673,52.36922264156371],
[13.064008952650568,52.39609286789508],
[13.015460350735339,52.37318812959998]]],
"type": "Polygon"},
"apply_SCL_band_mask": true
},
},
}
In the following, the parameter configuration is described in detail:
User Settings
Tile Settings
Note: To get the correct UTM zone, latitude band and grid square for downloading complete tiles either the tile grid sentinel_2_index_shapefile_attr.zip can be displayed in a GIS or this web map can be used.
Parameter |
Description |
Examples |
|---|---|---|
|
Which satellite to use. Default: both A and B. |
|
|
Defines how many pixels of a requested Sentinel-2 tile have NoData values. Leave empty to only validate the AOI for data coverage. |
|
|
UTM zone. Must be a list with one or more integers from 1 to 60 or empty if AOI is provided. Example: “32” for tile 32UQC. |
|
|
The latitude band of a preferred UTM zone. Empty if AOI is provided. Example: “U” for tile 32UQC. |
|
|
The grid square to specify the tile. Empty if AOI is provided. Example: “QC” for tile 32UQC. |
|
|
The amount of clouds that are allowed at the entire Sentinel-2 scene. Leave empty to only validate the AOI for cloud coverage. |
|
|
Defines which Sentinel-2 bands to download. You may choose from these options: [“coastal”, “blue”, “green”, “red”, “rededge1”, “rededge2”, “rededge3”, “nir”, “nir08”, “nir09”, “cirrus”, “swir16”, “swir22”]. See the table below for more information about the bands. |
|
Sentinel-2 Bands
Band Name |
Description |
Wavelength (µm) |
Resolution (m) |
|---|---|---|---|
coastal |
Coastal aerosol (band 1) |
0.433 |
60 |
blue |
Blue (band 2) |
0.49 |
10 |
green |
Green (band 3) |
0.56 |
10 |
red |
Red (band 4) |
0.665 |
10 |
rededge1 |
Vegetation red edge 1 (band 5) |
0.704 |
20 |
rededge2 |
Vegetation red edge 2 (band 6) |
0.74 |
20 |
rededge3 |
Vegetation red edge 3 (band 7) |
0.783 |
20 |
nir |
NIR 1 (band 8) |
0.842 |
10 |
nir08 |
Narrow NIR (band 8A) |
0.865 |
20 |
nir09 |
Water vapour (band 9) |
0.945 |
60 |
cirrus |
SWIR - Cirrus (band 10) |
1.3735 |
60 |
swir16 |
SWIR 1 (band 11) |
1.61 |
20 |
swir22 |
SWIR 2 (band 12) |
2.19 |
20 |
Note: Please make sure that you either provide only a Bounding Box or an AOI. A Bounding Box will always be four coordinates, a rectangle and in parallel with lon/lat. A polygon can have multiple shapes and orientations.
Parameter |
Description |
Examples |
|---|---|---|
|
The BoundingBox in lon/lat format. |
|
|
A polygon which defines an AOI to which the results are cropped. The format is one geometry feature of a geojson in lon/lat coordinates. |
|
|
Boolean Variable. If set to true the SCL band of Sentinel-2 is used to mask out pixels. The SCL band is saved along to an extra file. |
|
|
List of integer-Values corresponding to the SCL classes. It’s default classes are: cloud shadow (class 3), clouds (classes 7, 8, 9) and thin cirrus (class 10). |
|
|
User defined threshold for noData values inside the AOI. It may happen due to Sentinel-2 data tile structure that parts of the AOI have noData values. Here the user can define a percentage value of minimum valid pixels inside the AOI. |
|
|
User defined threshold for the SCL masked values inside the AOI. Here the user can define a percentage value of maximum masked pixels after masking in order to save the image. As an example, allow at most 20% cloud coverage in the image. |
|
|
If cloud masking based on the SCL band is applied, it may happen that images are saved which contain only very few valid pixels. Here the user can define a percentage value of minimum valid pixels that should be left over after masking in order to save the image. |
|
|
User definition of the resampling method that should be used. Currently, these options are supported: nearest, bilinear, cubic. |
|
|
The period of time data should be looked for, defined by starting and end date. It is also possible to provide just a single day. |
|
Parameter |
Description |
Examples |
|---|---|---|
|
Output directory to which the downloaded data should be saved to. |
|
|
The spatial resolution the output tif file(s) should have in meters. It should be either 10, 20 or 60. |
|
|
Boolean variable, If set to true the scenes are downloaded. If set to false only a list of available data is saved as a JSON file but no data is downloaded. |
|
|
Boolean variable. If this parameter is set to true the thumbnail for each available scenes is downloaded. |
|
|
Boolean variable. If this parameter is set to true the overview for each available scenes is downloaded. |
|
|
Logging level, it should be one of: DEBUG, INFO, WARN, or ERROR. |
|
Note: The S2 settings are not to be altered by the user!
Parameter |
Description |
Examples |
|---|---|---|
|
The Sentinel-2 preprocessing level of data to be downloaded. Currently only the S2 L2A download is tested. |
|
|
Path to the tile grid of Sentinel-2 data. |
|
The following files are saved within the defined output folder:
- <date_sensor_band>.tif
- <date_sensor>_SCL.tif
- <sensor_tile_date>_0_L2A_TCI.tif
- <sensor_tile_date>_0_L2A_thumbnail.jpg
- s2DataDownloader.log
- scenes_info_<daterange>.json
date_sensor_band.tif The tif file of each band. Example: 20210905_S2B_coastal.tif for date 2021-09-05, sensor B and band 1.
date_sensor_SCL.tif The tif file for the scl band of the according date. Example: 20210905_S2B_SCL.tif
sensor_tile_date_0_L2A_L2A_PVI.tif If “download_overviews” is set to true this file contains the overview per sensor, tile and date. Example: S2B_33UUU_20210908_0_L2A_TCI.tif
sensor_tile_date_0_L2A_preview.jpg If “download_thumbnails” is set to true this file contains the thumbnail per sensor, tile and date. Example: S2B_33UUU_20210908_0_L2A_thumbnail.jpg
s2DataDownloader.log The log file containing all logs. The logging level can be set in the result settings in the config.json.
scenes_info_daterange.json The information about the scenes for a certain date range. Example: scenes_info_2021-09-04_2021-09-05.json.
{
"20210905": {
"item_ids": [
{
"id": "S2B_33UUU_20210905_0_L2A"
}
],
"nonzero_pixels": [
100.0
],
"valid_pixels": [
100.0
],
"data_available": [
true
],
"error_info": [
""
]
}
}
For each date the following information is saved:
item_ids: The items (scenes) found at aws for that date.
nonzero_pixels: Percentage of pixels with non zero values.
valid_pixels: Percentage of pixels with valid data.
data_available: If false no data for this date was found.
error_info: If any error occurred during the download the error message will be saved here.
The difference when downloading complete tiles is that they are sorted in multiple folders with the following structure:
<utm_zone>
<latitude_band>
<grid_square>
<year>
<month>
<platform>_<product_level>_<time>_<processing_baseline_number>_<relative_orbit_number>_<tile_number>_<product_id>
<band_number>.tif