merge conflict resolved

sentinel-hub · Apr 16, 2018 · 5ac577f · 5ac577f
2 parents 7b043f7 + 285ffeb
commit 5ac577f
Show file tree

Hide file tree

Showing 56 changed files with 5,848 additions and 515 deletions.
diff --git a/Makefile b/Makefile
@@ -0,0 +1,9 @@
+# Makefile for creating a new release of the package and uploading it to PyPI
+# Before the release it resets the config.json file
+
+help:
+	@echo "Use 'make release' to upload the package to PyPi"
+
+release:
+	sentinelhub.config --instance_id "" --aws_access_key_id "" --aws_access_key_id "" --aws_secret_access_key ""
+	python setup.py sdist upload -r pypi
diff --git a/README.md b/README.md
@@ -7,13 +7,13 @@ The **sentinelhub** Python package allows users to make OGC (WMS and WCS)
 web requests to download and process satellite images within your Python
 scripts. It supports Sentinel-2 L1C and L2A, Sentinel-1, Landsat 8, MODIS and DEM data source.
 
-Version 1.0 is backwards compatible with previous releases,
-and therefore allows users to also download raw data from AWS to .SAFE
-format.
+The package also supports obtaining data from Amazon Web Service. It can either provide data from public bucket with
+Sentinel-2 L1C imagery or requester pays bucket with Sentinel-2 L2A imagery. If specified the downloaded data can be
+stored in ESA .SAFE format (all types of .SAFE format are supported).
 
 # Installation
 
-The package requires a Python version >= 3.5. The package is available on
+The package requires a Python version >= 3.5 and installed C/C++ compiler. The package is available on
 the PyPI package manager and can be installed with
 
 ```
@@ -40,29 +40,33 @@ Some of the major features introduced in version 1.0 are linked to one's [Sentin
  * 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.
+ image and data formats;
  * support for various data sources (new in version 1.1.0):
    * Sentinel-2 L1C,
    * Sentinel-2 L2A,
    * Sentinel-1,
    * Landsat 8,
    * MODIS,
-   * DEM
+   * DEM.
 
 
 ### 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.
+and reconstruct data into ESA .SAFE format.
 
 The following are implemented:
+ * support for Sentinel-2 L1C and Sentinel-2 L2A data;
  * 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;
  * adjustable threaded downloads, and optional redownloads of existing data (not default);
  * requires either S-2 product ID, or tile name and date of a product.
 
+In case of Sentinel-2 L2A data AWS access key is required.
+
+
 ### Documentation
 
 For more information on the package and to access the documentation, visit [readthedocs](http://sentinelhub-py.readthedocs.io/).
@@ -73,9 +77,10 @@ For more information on the package and to access the documentation, visit [read
 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/en/latest/aws_cli.html));
- * AWS data download using Jupyter notebook ([link](http://sentinelhub-py.readthedocs.io/en/latest/examples/aws_request.html));
- * Using OGC web services within Jupyter notebook ([link](http://sentinelhub-py.readthedocs.io/en/latest/examples/ogc_request.html)).
+ * Using OGC web services ([link](http://sentinelhub-py.readthedocs.io/en/latest/examples/ogc_request.html))
+ * Using utilities for large geographical areas ([link](http://sentinelhub-py.readthedocs.io/en/latest/examples/large_area_utilities.html))
+ * AWS data download ([link](http://sentinelhub-py.readthedocs.io/en/latest/examples/aws_request.html))
+ * AWS data download from command line in .SAFE format ([link](http://sentinelhub-py.readthedocs.io/en/latest/aws_cli.html))
 
 # License
 

diff --git a/docs/source/areas.rst b/docs/source/areas.rst
@@ -0,0 +1,14 @@
+areas
+=====
+
+Module for working with large geographical areas.
+
+.. module:: sentinelhub.areas
+.. autoclass:: AreaSplitter
+    :members:
+.. autoclass:: BBoxSplitter
+    :members:
+.. autoclass:: OsmSplitter
+    :members:
+.. autoclass:: TileSplitter
+    :members:
diff --git a/docs/source/aws_cli.rst b/docs/source/aws_cli.rst
@@ -1,7 +1,11 @@
+==========================================
 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.
+These examples show how to download Sentinel-2 data from Sentinel-2 on AWS to ESA SAFE format.
+
+Sentinel-2 L1C products
+***********************
 
 Download product and save to working directory::
 
@@ -31,11 +35,30 @@ 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
 
+Sentinel-2 L2A products
+***********************
+
+Sentinel-2 L2A products are located at AWS Requester Pays bucket. In order to download these products AWS access key has
+to be saved in the package configuration file as shown in `Configuration paragraph <configure.html#amazon-s3-capabilities>`_.
+
+The download of L2A products works the same as download of L1C products::
+
+$ sentinelhub.aws --product S2A_MSIL2A_20180402T151801_N0207_R068_T33XWJ_20180402T202222
+
+To download data by specifying the tile an additional flag has to be used::
+
+$ sentinelhub.aws --tile T33XWJ 2018-04-02 --l2a
+
+
 .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:
+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.
+* Some products created in October 2017 might miss quality report files (`FORMAT_CORRECTNESS.xml`, `GENERAL_QUALITY.xml`, `GEOMETRIC_QUALITY.xml`, `RADIOMETRIC_QUALITY.xml` and `SENSOR_QUALITY.xml`).
 
+If you notice any other difference please raise an issue at
+`GitHub page <https://github.com/sentinel-hub/sentinelhub-py/issues>`_.
diff --git a/docs/source/aws_safe.rst b/docs/source/aws_safe.rst
@@ -8,4 +8,3 @@ Module for creating .SAFE structure with data from AWS.
     :members:
 .. autoclass:: SafeTile
     :members:
-.. autofunction:: edit_name
diff --git a/docs/source/config.rst b/docs/source/config.rst
@@ -4,5 +4,5 @@ config
 Module to collect configuration data from config.json.
 
 .. module:: sentinelhub.config
-.. autoclass:: SGConfig
+.. autoclass:: SHConfig
     :members:
diff --git a/docs/source/configure.rst b/docs/source/configure.rst
@@ -0,0 +1,38 @@
+*************
+Configuration
+*************
+
+The package contains a configuration file ``config.json``. After the package is installed you can check the initial
+configuration parameters in command line::
+
+$ sentinelhub.config --show
+
+Sentinel Hub Capabilities
+*************************
+
+The ``instance_id`` parameter will be empty. In case you would like to use any capabilities of the package that
+interact with `Sentinel Hub services`_ you can set your Sentinel Hub instance ID with::
+
+$ sentinelhub.config --instance_id <your instance id>
+
+By doing so the package will use this instance ID to interact with Sentinel Hub unless you purposely specify a
+different one in the code.
+
+Amazon S3 Capabilities
+**********************
+
+The ``aws_access_key_id`` and ``aws_secret_access_key`` will also be empty. In case you would like package to access
+Sentinel-2 L2A data from `Amazon S3`_ service you can set these values using your AWS access key::
+
+$ sentinelhub.config --aws_access_key_id <your access key> --aws_secret_access_key <your secret access key>
+
+Other
+*****
+
+For more configuration options check::
+
+$ sentinelhub.config --help
+
+
+.. _`Sentinel Hub services`: https://www.sentinel-hub.com/develop/documentation/api/ogc_api/
+.. _`Amazon S3`: https://aws.amazon.com/s3/
diff --git a/docs/source/docs.rst b/docs/source/docs.rst
@@ -1,23 +1,25 @@
-sentinelhub
-===========
+***************
+Package content
+***************
 
 Content of the **sentinelhub** package.
 
 Modules
 ~~~~~~~
 
 .. toctree::
-   aws
-   aws_safe
-   common
-   config
-   constants
-   data_request
-   download
-   geo_utils
-   geopedia
-   io_utils
-   ogc
-   opensearch
-   os_utils
-   time_utils
+    areas
+    aws
+    aws_safe
+    common
+    config
+    constants
+    data_request
+    download
+    geo_utils
+    geopedia
+    io_utils
+    ogc
+    opensearch
+    os_utils
+    time_utils
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -1,9 +1,11 @@
+********
 Examples
-========
+********
 
 .. toctree::
     :maxdepth: 4
 
     examples/ogc_request.ipynb
+    examples/large_area_utilities.ipynb
     examples/aws_request.ipynb
     aws_cli
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -14,12 +14,13 @@ EO service `Sentinel-Hub <http://www.sentinel-hub.com/>`_.
 The code is available on `GitHub <https://github.com/sentinel-hub/sentinelhub-py/>`_.
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+    :maxdepth: 3
+    :caption: Contents:
 
-   install
-   docs
-   examples
+    install
+    configure
+    examples
+    docs
 
 Indices and tables
 ==================

diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -15,4 +15,5 @@ or manually::
 $ python setup.py build
 $ python setup.py install
 
+
 .. _Github: https://github.com/sentinel-hub/sentinelhub-py
diff --git a/examples/aws_request.ipynb b/examples/aws_request.ipynb
@@ -20,7 +20,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Imports"
+    "## Imports"
    ]
   },
   {
@@ -57,7 +57,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Aws Tile"
+    "## Aws Tile"
    ]
   },
   {
@@ -203,7 +203,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Aws Product"
+    "## Aws Product"
    ]
   },
   {
@@ -236,7 +236,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Data into .SAFE structure"
+    "## Data into .SAFE structure"
    ]
   },
   {
@@ -303,7 +303,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.2"
+   "version": "3.5.3"
   }
  },
  "nbformat": 4,