README.md

# GTS2 Sentinel-2 downloader
Status
------
[![pipeline status](https://gitext.gfz-potsdam.de/gts2/gts2_client/badges/master/pipeline.svg)](https://gitext.gfz-potsdam.de/gts2/gts2_client/commits/master)
[![coverage report](https://gitext.gfz-potsdam.de/gts2/gts2_client/badges/master/coverage.svg)](https://gitext.gfz-potsdam.de/gts2/gts2_client/commits/master)
[![AUR](https://img.shields.io/aur/license/yaourt.svg)](https://gitext.gfz-potsdam.de/gts2/gts2_client/blob/master/LICENCE)


[Coverage report](http://gts2.gitext.gfz-potsdam.de/gts2_client/coverage/)

## Description
This program package downloads Sentinel-2 data from the GTS2
(GFZ Time Series System for Sentinel-2) cloud for a area of interest,
time of interest and wanted band combination and saves them to geotiff (.tiff)
 or alternatively as .json file or as netcdf (.nc) file.

## Requirements
1. Access to GTS2 API (username, password, port)
2. Python3
3. Python packages - check the requirements in [setup.py](./setup.py)

## Download package:
Clone the repository with:
<code>git clone https://gitext.gfz-potsdam.de/gts2/gts2_client.git
</code>

## Installation
### ... is easy (as long your python is compatible):
* Make sure your system meets all the requirements (see above)
* Install the package by running:
```
make install
make clean
```

### Install a compatible python:
The following instruction is only valid for Linux distributions but can be adapted on Windows machines.
Everything is based on bash shell.

#### EITHER: Use install script and follow instructions:
Run:
```
make install_conda_gts2_client
```

After providing the installation path, miniconda and all necessary packages as well as the gts2_client will be installed.
At the script will provide instructions which PATHs to add to your .bashrc.

#### OR: Per hand (expert modus):
* Download and install at least Miniconda with default settings:
```
wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh
chmod 755 Miniconda3-latest-Linux-x86_64.sh
./Miniconda3-latest-Linux-x86_64.sh -b
rm -f Miniconda3-latest-Linux-x86_64.sh
```
* Install necessary packages for gts2_client using **gts2_client_conda_install.yml**:
`conda env update -f gts2_client_conda_install.yml`


### Finally:
Create a credentials file in your home directory **credentials_gts2_client**
that contains the following structure:

```bash
{"user": "",
"password": "",
"port": ""}
```

Please fill in your credentials (provided by GFZ Potsdam, please contact gts2@gfz-potsdam.de).

### If you want to use docker
**!! Attention: Expert mode !! root access to computer is needed.**
You only have to run **docker_gts2_client/build_run_gts2_client_docker.sh**
It creates an image that is based on a Centos:7, performs all needed installation steps and starts a container.
You end up with a shell where you can run `gts2_client`.
The building of the image can take some time (up to 30 Minutes), but once it is done,
**docker_gts2_client/build_run_gts2_client_docker.sh** skips the build and only starts the container.


## Usage

### As command line tool:
```bash
gts2_client required_arguments [optional_arguments]
```

The list of arguments including their default values can be called from the command line with:
`gts2_client --help`

#### Arguments:
##### Required:
  * -o OUT_DIR, --out_dir OUT_DIR
    output_directory
  * -l LAT_LL, --lat_ll LAT_LL
    latitude lower left corner
  * -k LON_LL, --lon_ll LON_LL
    longitude lower left corner
  * -i LAT_UR, --lat_ur LAT_UR
    latitude upper right corner
  * -j LON_UR, --lon_ur LON_UR
     longitude upper right corner
  * -s START_DATE, --start_date START_DATE
     Startdate (e.g. 20160701)
  * -e END_DATE, --end_date END_DATE
     Enddate (e.g. 20160701)

##### Optional
  * -r OUT_PREFIX, --out_prefix OUT_PREFIX
    output_prefix for naming the output files
  * -b BANDS, --bands BANDS
     list of Bands (e.g. -b B02_B03)
  * -m OUT_MODE, --out_mode OUT_MODE
    output_mode, use 'json' for json-file,'single' for
    single tiffs or 'stack' for tiff band stack, 'nc' for netcdf-file
  * -a SENSOR, --sensor SENSOR
     sensor name  (e.g. S2A)
  * -t LEVEL, --level LEVEL
     processing level (e.g. L2A)
  * -v VERSION, --version VERSION
     version of atmospheric correction (e.g. 0.14 - recommended version)
  * -c COREG, --coreg COREG
     get coregistrated data with corrected pixel shifts (e.g. True)
     [pixel shifts between time steps were eliminated by coregistrating
     images with a reference image (currently only avalaible for Germany)]
  * -z MAX_CLOUDY, --max_cloudy MAX_CLOUDY
     maximal percentage of cloudyness of requested scene (e.g. 0.2)
  * -f MINIMUM_FILL, --minimum_fill MINIMUM_FILL
     minimal percentage of data in scene (e.g. 0.5)
  * -d UTM_ZONE, --utm_zone UTM_ZONE
    only return data for specific utm-zone (MGRS-tile, e.g. 33UUV)
  * -g STACK_RESOLUTION, --stack_resolution STACK_RESOLUTION
    spatial sampling [in meters] of the output stack file,
                        choose from [10,20])
  * -n RGB_EXTENSION, --rgb_extension RGB_EXTENSION
                        file extension of rgb files e.g.[jpg, png], default:
                        jpg (default: jpg)
  * -q RGB_BANDS_SELECTION, --rgb_bands_selection RGB_BANDS_SELECTION
                        band selection for rgb production, choose from:
                        realistic, nice_looking, vegetation,
                        healthy_vegetation_urban, snow, agriculture
                        (default: realistic)
  * -w MERGE_TIFS, --merge_tifs MERGE_TIFS
                        Merge tifs and RGBs if area in two or more MGRS tiles
                        per time step (True or False). (default: False)
  * -x MERGE_TILE, --merge_tile MERGE_TILE
                        Choose MGRS tile into which the merge of files is
                        performed (e.g. 33UUV). (default: None)

**Legend of RGB band selection:**


| Name | band selection |
| :---------  | :----------- |
| realistic | B04, B03, B02 |
| nice_looking | B11, B08, B03 |
| vegetation | B8A, B04, B03 |
| healthy_vegetation_urban | B8A, B11, B02 |
| snow |  B08, B11, B04|
| agriculture | B11, B08, B02 |

### As python package

Set out_mode to "to_python" in order to include the results of the client (dictionary) into
the local namespace:
```
from gts2_client import gts2_client
result = gts2_client.client(out_mode="python", **kwargs)
```

## Limitations:
  * Bands with spatial resolution 60m (Band 1) are not stacked.
  * Requests with areas larger than 0.2°x0.2° will probably not be processed
     if you also request a large time range this threshold can also be smaller