# sentinelloader
Sentinel-2 satellite tiles images downloader from Copernicus. 

With this utility you can specify the desired polygon, image resolution, band name and aproximate dates and it will do the best effort to find all tiles needed to satisfy your requirement. Then it will download minimal data by selecting just the needed .jp2 files inside Products, combine downloaded tiles, crop the combined tiles image to the polygon and cache the results, returning a GeoTIFF image with raster for the selected area.

All API calls are in ESP:4326 reference.

# Background

Granules are packages containing data taken from Sentinel-2 satellite for a region on the globe in a specific time. They contain a lot of data for that area (13 bands in different resolutions and other derived bands and quality data). Level-2A products, for example, have ~1GB of data for a single tile (100km2 x 100km2). 

With this utility you can select which bands/resolutions to download. For example, if you need only the TCI band (true color) tile at 60m resolution, you will can use the utility to download just ~3MB of data (instead of 1GB!). For max resolution(10m), each band will have ~120MB. Some caching will be applied to avoid re-downloading of data that is already present in disk.

* For more information on Sentinel-2 satellite product data, go to https://sentinel.esa.int/documents/247904/685211/Sentinel-2-Products-Specification-Document

* If you want to download whole Granules (instead of only some files inside Granules), you can go to https://github.com/sentinelsat/sentinelsat or https://scihub.copernicus.eu/twiki/do/view/SciHubUserGuide/BatchScripting?redirectedfrom=SciHubUserGuide.8BatchScripting


## Usage

### Docker example

* Create docker-compose.yml

```yml
version: '3.3'
services:
  sentinelloader:
    image: flaviostutz/sentinelloader
    environment:
      - COPERNICUS_USER=auser
      - COPERNICUS_PASSWORD=apass
    ports:
      - 8686:8888
```

* Create an account in Copernicus and change info in docker-compose.yml accordingly

* Run ```docker-compose up -d```

* Open your browser at http://localhost:8686/

* Open Jupyter notebook "example.ipynb" and press "Run"

* You should see something like [this](/notebooks/example.ipynb)

### Python example

```shell
pip install git+https://github.com/flaviostutz/sentinelloader
```

```python
import logging
import os
from osgeo import gdal
import matplotlib.pyplot as plt
from sentinelloader import Sentinel2Loader
from shapely.geometry import Polygon

sl = SentinelLoader('/notebooks/data/output/sentinelcache', 
                    'mycopernicususername', 'mycopernicuspassword',
                    apiUrl='https://scihub.copernicus.eu/apihub/', showProgressbars=True, loglevel=logging.DEBUG)

area = Polygon([(-47.873796, -16.044801), (-47.933796, -16.044801),
        (-47.933796, -15.924801), (-47.873796, -15.924801)])

geoTiffs = sl.getRegionHistory(area, 'TCI', '60m', '2019-01-06', '2019-01-30', daysStep=5)
for geoTiff in geoTiffs:
    print('Desired image was prepared at')
    print(geoTiff)
    os.remove(geoTiff)
)
```

For a Jupyter example, [click here](notebooks/example.ipynb)

### API

```python
def getRegionHistory(self, geoPolygon, bandOrIndexName, resolution, dateFrom, dateTo, daysStep=5, ignoreMissing=True, minVisibleLand=0, visibleLandPolygon=None, keepVisibleWithCirrus=False, interpolateMissingDates=False):
        """Gets a series of GeoTIFF files for a region for a specific band and resolution in a date range. It will make the best effort to get images near the desired dates and filter out images that have poor land visibility due to cloudy days"""
```

minVisibleLand - a value from 0 to 1 indicating the percentage of land that must be visible on the image (according to cloud coverage at the time)

sl = SentinelLoader('/notebooks/data/output/sentinelcache', 
                    'mycopernicususername', 'mycopernicuspassword',
                    apiUrl='https://scihub.copernicus.eu/apihub/', showProgressbars=True, loglevel=logging.DEBUG)

desired_region = Polygon([(-47.873796, -16.044801), (-47.933796, -16.044801),(-47.933796, -15.924801), (-47.873796, -15.924801)])

geoTiffs = sl.getRegionHistory(desired_region, 'TCI', '60m', '2019-01-06', '2019-01-30', daysStep=5)

* In this example, sentinelloader will connect to Coperrnicus with your account and try to get various images in the band "TCI" of the desired region at a resolution of 60m fom 2019-01-06 to 2019-01-30 (if still available in Copernicus Hub) each 5 days (it will try to get the closes image to the days selected, because not every day we have images for every places).

* Supported band names

  * All bands that are part of Sentinel 2 products at Copernicus Hub (SCL, TCI, B01-08, B1A etc)
  * Sintetic indexes implemented by this tool: NDVI, NDWI, NDWI_MacFeeters or NDMI
   * If you implement a newer one, please send a PR with it!

## Publishing package to pypi

```sh
python3 -m pip install --upgrade build

python3 -m build

python3 -m twine upload --repository sentinelloader dist/*
```

https://packaging.python.org/en/latest/tutorials/packaging-projects/#uploading-the-distribution-archives

