Version 1.0. Joint effort by EO research team @sentinel-hub.com.

sentinel-hub · Jan 15, 2018 · 276b8c9 · 276b8c9
1 parent b29f55d
commit 276b8c9
Show file tree

Hide file tree

Showing 68 changed files with 6,968 additions and 644 deletions.
diff --git a/.gitignore b/.gitignore
@@ -98,4 +98,7 @@ ENV/
 /site
 
 # mypy
-.mypy_cache/
+.mypy_cache/
+
+# Test output folder
+/TestOutputs
diff --git a/.travis.yml b/.travis.yml
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,8 +1,6 @@
 include requirements*.txt
 
 include README.md
-include CONTRIBUTING.md
-include CHANGELOG.md
-include COPYING
 include LICENSE
 include setup.py
+include sentinelhub/config.json
diff --git a/README.md b/README.md
@@ -1,111 +1,70 @@
-# Sentinel Hub Tools
-[![Join the chat at https://gitter.im/sinergise/Lobby](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/sinergise/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![Build Status](https://travis-ci.org/sinergise/sentinelhub.svg?branch=master)](https://travis-ci.org/sinergise/sentinelhub)
+# Description
 
-Python library of tools for easier use of Sentinel Hub products.
+The **sentinelhub** Python package allows users to make OGC (WMS and WCS)
+web requests to download and process Sentinel-2 images within your Python
+scripts.
 
-## Install
+Version 1.0 is backwards compatible with previous releases,
+and therefore allows users to also download raw data from AWS to .SAFE
+format.
 
-Library requires Python 2 version >=2.7 or Python 3. It can be installed using pip
-```
-pip install sentinelhub
-```
-or manually
-```
-cd sentinelhub
-python setup.py build
-python setup.py install
-```
+# Installation
 
-## Content
-
-### AWS to SAFE tool
-
-Tool for downloading Sentinel-2 data from [Sentinel-2 on AWS](http://sentinel-pds.s3-website.eu-central-1.amazonaws.com/) and reconstruction into ESA .SAFE format.
-
-**Overview:**
- * Supports old and new (i.e. compact) .SAFE formats.
- * Requires either S-2 product ID or name and date of one tile inside the product.
- * Can either download entire product or only return a map of a .SAFE file structure.
- * Supports command line entries.
- * Supports threaded download and redownloading existing data (not by default).
-
-**.SAFE format details**: </br>
-Files in reconstructed .SAFE format follow the rules of [ESA naming convention](https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi/naming-convention). Reconstructed format differs from the original only in the following:
- * Folders *HTML* and *rep_info* inside main product folder do not contain any data.
- * Auxiliary file inside *AUX_DATA* folder of every tile in old .SAFE format does not have original name. Instead it is named *AUX_ECMWFT* which is the same as in compact .SAFE format.
-
-**Functions:**
- * Function for downloading .SAFE format
- ```
- download_safe_format(product_id=None, tile=None, folder='.', redownload=False, threaded_download=False, entire_product=False)
- ```
- It can either take ID name of a product or name and date of a tile in form ```tile=(name, date)``` (e.g. ```tile=('T38TML','2015-12-19')```). </br>
- In case ```tile``` is specified and ```entire_product=True``` it will download entire product corresponding to that tile. Otherwise it will download only the tile.
- * Function for returning map structure of .SAFE format
- ```
- get_safe_format(product_id=None, tile=None, entire_product=False)
- ```
- It returns map in a form ```{'folder_name' : { 'subfolder_name' : { ... {'file_name': 'url_of_file_on_aws', ...}... }...}...}```.
-
-**Examples:**
- * Download product
-```
-With Python
->>> sentinelhub.download_safe_format('S2A_MSIL1C_20170414T003551_N0204_R016_T54HVH_20170414T003551')
-or with command line
-$ sentinelhub.aws --product S2A_MSIL1C_20170414T003551_N0204_R016_T54HVH_20170414T003551
-```
+The package requires a Python 3.\* version. The package is available on
+the PyPI package manager and can be installed with
 
- * Get .SAFE structure
 ```
-With Python
->>> sentinelhub.get_safe_format('S2A_MSIL1C_20170414T003551_N0204_R016_T54HVH_20170414T003551')
-or with command line
-$ sentinelhub.aws --product S2A_MSIL1C_20170414T003551_N0204_R016_T54HVH_20170414T003551 -i
+$ pip install -U sentinelhub
 ```
 
- * Download tile
- ```
- With Python
- >>> sentinelhub.download_safe_format(tile=('T38TML', '2015-12-19'))
- or with command line
- $ sentinelhub.aws --tile T54HVH 2017-04-14
- ```
- *(Please note that this specification is not always unique as there might be multiple tiles with the same name and date.)*
-
- * Download entire product corresponding to tile
- ```
- With Python
- >>> sentinelhub.download_safe_format(tile=('T38TML', '2015-12-19'), entire_product=True)
- or with command line
- $ sentinelhub.aws --tile T54HVH 2017-04-14 -e
- ```
- *(Please note that this specification is not always unique as there might be multiple tiles with the same name and date.)*
-
- * For more functionalities check:
+To install the package manually, clone the repository and
 ```
-$ sentinelhub.aws --help
+$ python setup.py build
+$ python setup.py install
 ```
 
-### Custom download tool
-Tool for downloading data from any URL address into file with specified name.
+The package is backward compatible with the previous version.
 
-**Functions:**
-```
-sentinelhub.download_data(requstList, redownload=False, threaded_download=False)
-```
-where ```requestList = (url, filename)``` or ``` requestList = [(url1, filename1), (url2, filename2), ...]```
+# Content
 
-**Examples:**
- * Download an image from AWS using Python
-```
-With Python
->>> sentinelhub.download_data(('http://sentinel-s2-l1c.s3.amazonaws.com/tiles/54/H/VH/2017/4/14/0/B01.jp2', 'MyFolder/TestImage.jp2'))
-or with command line
-$ sentinelhub.download http://sentinel-s2-l1c.s3.amazonaws.com/tiles/54/H/VH/2017/4/14/0/B01.jp2 MyFolder/TestImage.jp2 -rt
-```
+A summary of the package content is provided below. For more information
+on the package and to access the documentation, visit the [docs](http://sentinelhub-py.readthedocs.io/).
+
+### OGC web service
+
+Some of the major features introduced in version 1.0 are linked to one's [Sentinel-Hub account](https://services.sentinel-hub.com/oauth/subscription):
+ * support for Web Map Service (WMS) and Web Coverage Service (WCS) requests using your Sentinel-Hub account;
+ * support for standard and custom multi-spectra layers, such as unprocessed
+ bands, true color imagery, or NDVI;
+ * support for multi-temporal requests;
+ * support for cloud coverage filtering;
+ * support for different Coordinate Reference Systems;
+ * support to read and write downloaded data to disk in the most common
+ image and data formats.
+
+
+### AWS data download
+
+The package allows to download Sentinel-2 data from Sentinel-2 on AWS
+and reconstruct data into ESA .SAFE format. Sentinel-Hub account is not required to use this functionality.
+
+The following are implemented:
+ * support of old and new (i.e. compact) .SAFE format;
+ * support for downloading of either entire product, or a map of the .SAFE
+ structure only;
+ * support of command lines entries;
+ * support of threaded downloads, and redownloads of existing data (not default);
+ * requires either S-2 product ID, or tile name and date of a product.
+
+# Examples
+
+Jupyter notebooks on how to use the modules to execute OGC requests, or
+download raw data from AWS in .SAFE format can be found in the [examples](examples/)
+folder, or viewed in the [docs](http://sentinelhub-py.readthedocs.io/):
+ * AWS data download cli ([link](http://sentinelhub-py.readthedocs.io/));
+ * AWS data download using Jupyter notebook ([link](http://sentinelhub-py.readthedocs.io/));
+ * Using OGC web services within Jupyter notebook ([link](http://sentinelhub-py.readthedocs.io/)).
 
-## License
+# License
 
-See [LICENSE.md](https://github.com/sinergise/sentinelhub/blob/master/LICENSE.md)
+See [LICENSE](LICENSE.md).
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,24 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python3 -msphinx
+SPHINXPROJ    = sentinelhub
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile 
+	cp -vr ../examples source/
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	rm -r source/examples
+
+
diff --git a/docs/source/aws.rst b/docs/source/aws.rst
@@ -0,0 +1,12 @@
+aws
+===
+
+Module for obtaining data from Amazon Web Service.
+
+.. module:: sentinelhub.aws
+.. autoclass:: AwsService
+    :members:
+.. autoclass:: AwsProduct
+    :members:
+.. autoclass:: AwsTile
+    :members:
diff --git a/docs/source/aws_cli.rst b/docs/source/aws_cli.rst
@@ -0,0 +1,41 @@
+How to download AWS data from command line
+==========================================
+
+These examples show how download Sentinel-2 data from Sentinel-2 on AWS to ESA SAFE format. Download uses multiple threads.
+
+Download product and save to working directory::
+
+$ sentinelhub.aws --product S2A_MSIL1C_20170414T003551_N0204_R016_T54HVH_20170414T003551
+
+Get .SAFE structure only::
+
+$ sentinelhub.aws --product S2A_MSIL1C_20170414T003551_N0204_R016_T54HVH_20170414T003551 -i
+
+Download product and save to specific directory::
+
+$ sentinelhub.aws --product S2A_MSIL1C_20170414T003551_N0204_R016_T54HVH_20170414T003551 -f /home/ESA_Products
+
+Download specified bands only::
+
+$ sentinelhub.aws --product S2A_MSIL1C_20170414T003551_N0204_R016_T54HVH_20170414T003551 --bands B08,B11
+
+Download tile::
+
+$ sentinelhub.aws --tile T54HVH 2017-04-14
+
+Download entire product corresponding to tile::
+
+$ sentinelhub.aws --tile T54HVH 2017-04-14 -e
+
+Download an image from AWS::
+
+$ sentinelhub.download http://sentinel-s2-l1c.s3.amazonaws.com/tiles/54/H/VH/2017/4/14/0/metadata.xml home/example.xml
+
+.SAFE format details
+--------------------
+
+Files in reconstructed .SAFE format follow the rules of ESA naming convention. Reconstructed format differs from the original only in the following:
+
+* Folders HTML and rep_info inside main product folder do not contain any data.
+* Auxiliary file inside AUX_DATA folder of every tile in old .SAFE format does not have original name. Instead it is named AUX_ECMWFT which is the same as in compact .SAFE format.
+
diff --git a/docs/source/aws_safe.rst b/docs/source/aws_safe.rst
@@ -0,0 +1,11 @@
+aws_safe
+========
+
+Module for creating .SAFE structure with data from AWS.
+
+.. module:: sentinelhub.aws_safe
+.. autoclass:: SafeProduct
+    :members:
+.. autoclass:: SafeTile
+    :members:
+.. autofunction:: edit_name
diff --git a/docs/source/commands.rst b/docs/source/commands.rst
@@ -0,0 +1,6 @@
+commands
+========
+
+.. module:: sentinelhub.commands
+.. autofunction:: aws
+.. autofunction:: download
diff --git a/docs/source/common.rst b/docs/source/common.rst
@@ -0,0 +1,11 @@
+common
+======
+
+Module implementing classes common to all modules of the package (such as the bounding box class).
+
+Available classes:
+* BBox, represent a bounding box in a given CRS
+
+.. module:: sentinelhub.common
+.. autoclass:: BBox
+    :members: