README.md

earthspy 🛰️ 🌍 🌎 🌏

earthspy is a wrapper around methods for the download of satellite data offered in the sentinelhub-py Python package. This tool makes the monitoring and study of any place on Earth simple, ready to use and easily deployable for operational purposes and automated Near-Real Time (NRT) applications.

As earthspy is built on top of the Sentinel Hub services, it includes e.g. the data pre-processing through custom scripts allowing the user to process and download only the products needed (such as high-level indices) therefore optimizing download time and local storage.

Table of Contents

• earthspy
• Installation
• Usage
• Operational Near Real-Time (NRT) deployment
• Documentation
• Contributing

Installation

It is recommended to install earthspy via Github, with conda and pip:

# clone repository
git clone git@github.com:AdrienWehrle/earthspy.git

# move into earthspy directory
cd earthspy

# create conda environment
conda env create -f environment.yml

# activate conda environment
conda activate earthspy

# install earthspy
pip install -e .

• Using pip together with conda is usually a bad idea, but here conda installs all the dependencies and pip only sets up the associated paths, that's all! 👍
• Installation can be sped up using the fast cross-platform package manager mamba (reimplementation of the conda package manager in C++), simply use mamba instead of conda in the instructions above!

Usage

At present earthspy can be run within a couple of lines of Python code that execute three main tasks:

• set up a Sentinel Hub connection (for a given Sentinel Hub account)
• set query parameters including Sentinel Hub API variables and earthspy additional ones (mainly for download efficiency)
• send request

Below is presented a simple application of earthspy for the download of Sentinel-2 data download around Ilulissat, Greenland for a few days in August 2019 using a True Color custom script available on Sentinel Hub's custom script online repository. All other available data collections can be found here.

import earthspy.earthspy as es

# auth.txt should contain username and password (first and second row)
job = es.EarthSpy("/path/to/auth.txt")

# as simple as it gets
job.set_query_parameters(
    bounding_box=[
        -51.13,
        69.204,
        -51.06,
        69.225,
    ],  # format from doc: [min_x, min_y, max_x, max_y]
    time_interval=["2019-08-03", "2019-08-10"],
    evaluation_script="https://custom-scripts.sentinel-hub.com/custom-scripts/sentinel-2/true_color/script.js",
    data_collection="SENTINEL2_L2A",
)

# and off it goes!
job.send_sentinelhub_requests()

Homemade custom evalscripts can also be passed without effort to e.g. compute high-level indices (NDVI, NDSI...). Below is presented an example with the default evaluation script used above (to keep it short):

import earthspy.earthspy as es

# Sentinel-2 default True Color script
example_evalscript = """
    //VERSION=3
    function setup(){
      return{
        input: ["B02", "B03", "B04", "dataMask"],
        output: {bands: 4}
      }
    }

    function evaluatePixel(sample){
      // Set gain for visualisation
      let gain = 2.5;
      // Return RGB
      return [sample.B04 * gain, sample.B03 * gain, sample.B02 * gain, sample.dataMask];
    }

    """

# auth.txt should contain username and password (first and second row)
job = es.EarthSpy("/path/to/auth.txt")

# pass string to evaluation_script
job.set_query_parameters(
    bounding_box=[-51.13, 69.204, -51.06, 69.225],
    time_interval=["2019-08-03", "2019-08-10"],
    evaluation_script=example_evalscript,
    data_collection="SENTINEL2_L2A",
)

# and off it goes!
job.send_sentinelhub_requests()

GEOJSON files containing a polygon corresponding to a given region of interest and its associated name can also be created at geojson.io and stored in ./data. In this way, the name of the region can be directly passed to the bounding_box query parameter. See below for a simple example with the ilulissat.geojson example file.

import earthspy.earthspy as es

# auth.txt should contain username and password (first and second row)
job = es.EarthSpy("/path/to/auth.txt")

# as simple as it gets
job.set_query_parameters(
    bounding_box="Ilulissat",
    time_interval=["2019-08-03", "2019-08-10"],
    evaluation_script="https://custom-scripts.sentinel-hub.com/custom-scripts/sentinel-2/true_color/script.js",
    data_collection="SENTINEL2_L2A",
)

# and off it goes!
job.send_sentinelhub_requests()

Operational Near Real-Time (NRT) deployment

earthspy can be easily deployed for NRT monitoring. The setup is as simple as wrapping the query parameters in a short python script such as earthspy_NRT.py and including it in a cron job. See an example below where Sentinel-2 images of Ilulissat, Greenland acquired over the past three days are downloaded everyday at noon.

# m h  dom mon dow   command
00 12 * * * /bin/bash -c "/path/to/earthspy_NRT.py" > /path/to/log/log_earthspy_NRT.txt

Documentation

The documentation of earthspy is hosted on readthedocs.

Contributing

Contributions to earthspy are more than welcome! Guidelines are presented in CONTRIBUTING.md.