earthspy

earthspy is a wrapper around methods for the download of satellite data offered in the sentinelhub 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 NRT applications. Just like a spy!

Some useful capabilities:

• Data download in multiprocessing
• Data download at optimized resolutions with the Direct (D) download mode
• Data download at raw resolutions with the Split and Merge (SM) downlodad mode
• Data storage with efficient structure

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

Installation

Usage

At present earthspy can be run by users 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 few days in August 2019 using a True Color custom script available on Sentinel Hub’s custom script online repository.

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],
    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):

# 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];
    }

    """

# 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()

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 preliminary documentation of earthspy is hosted on readthedocs.