Metadata-Version: 2.1
Name: sentinelloader
Version: 1.1.1
Summary: Sentinel-2 satellite tiles images downloader from Copernicus
Home-page: https://github.com/flaviostutz/sentinelloader.git
Author: Flávio Stutz
Author-email: Flavio Stutz <flaviostutz@gmail.com>
License: MIT License
        
        Copyright (c) 2019 Flavio Stutz
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/flaviostutz/sentinelloader
Project-URL: Bug Tracker, https://github.com/flaviostutz/sentinelloader/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE

# 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

