earthspy.earthspy

@authors: Adrien Wehrlé (EO-IO), Antsalacia

Classes

EarthSpy

class earthspy.earthspy.EarthSpy(CLIENT_credentials_file)[source]

Bases: object

Monitor and study any place on Earth and in Near Real-Time (NRT) using the SentinelHub services.

__init__(CLIENT_credentials_file)[source]
Parameters:

CLIENT_credentials_file (str) – full path to file containing credentials with User’s OAuth client ID (1st row) secret (2nd row).

configure_connection()[source]

Build a shb configuration class for the connection to Sentinel Hub services.

Returns:

sentinelhub-py package configuration class.

Return type:

shb.SHConfig

convert_bounding_box_coordinates()[source]

Convert bounding box coordinates to a Geodetic Parameter Dataset (EPSG) in meter unit, default to EPSG:3413 (NSIDC Sea Ice Polar Stereographic North).

Returns:

Bounding box coordinates in target projection.

Return type:

list

extract_sentinelhub_responses(folders)[source]

Extract all members of a Tape ARchive produced by the Sentinel Hub API.

Parameters:

folders (list) – List of folders containing outputs.

Return type:

None

get_available_data()[source]

Search for available data with STAC REST API before download.

Return type:

list

get_bounding_box(bounding_box)[source]

Get bounding box for data download depending on user specifications.

Parameters:

bounding_box (Union[list, str]) – Area footprint with the format [min_x, min_y, max_x, max_y]. An area name stored in a JSON database can also be passed.

Returns:

Area footprint as a Sentinelhub BBox geometry.

Return type:

sentinelhub.geometry.BBox

get_data_collection()[source]

Get Sentinel Hub DataCollection object from data collection name.

Returns:

DataCollection object containing all information needed for download (such as bands, sensor type…).

Return type:

shb.DataCollection

get_date_range(time_interval)[source]

Get date range for data download depending on user specifications.

Parameters:

time_interval (Union[int, list]) – Number of days from present date or beginning and end date strings.

Returns:

Data range (can be one-day long).

Return type:

pd.core.indexes.datetimes.DatetimeIndex

get_evaluation_script(evaluation_script)[source]

Get custom script for data download depending on user specifications.

Parameters:

evaluation_script (Union[None, str]) – Custom script (preferably evalscript V3) or URL to a custom script on https://custom-scripts.sentinel-hub.com/. If not specified, a default script is used.

Returns:

Custom script.

Return type:

str

Get evaluation script from URL pointing to the Sentinel Hub collection of custom scripts.

Parameters:

evaluation_script (Union[None, str]) – URL to a custom script on https://custom-scripts.sentinel-hub.com/.

Returns:

Custom script.

Return type:

str

get_max_resolution()[source]

Get maximum resolution reachable in Direct Download mode.

Raises:

IndexError – Estimated resolution above 10 kilometers.

Returns:

Resolution in meters to use for data download.

Return type:

Union[int, None]

get_optimal_box_split()[source]

Get the minimum number of bounding boxes to achieve maximum resolution in SM download mode.

Returns:

Minimum number of boxes in x and y directions (1st and 2nd values, respectively).

Return type:

Tuple[int, int]

get_raster_compression(raster_compression)[source]

Get raster compression based on rasterio’s available methods

Returns:

Raster compression method

Return type:

Union[None, str]

get_raw_data_collection_resolution()[source]

Get lowest raw data collection resolution possible (then refined at the download stage).

Returns:

Data collection resolution.

Return type:

int

get_satellite_name()[source]

Extract satellite name from data collection.

Returns:

Satellite name.

Return type:

str

get_split_boxes()[source]

Build secondary bounding boxes used for the SM download mode.

Returns:

Secondary bounding boxes matching the initial bounding box when merged.

Return type:

list

get_store_folder(store_folder)[source]

Get folder path for data storage depending on user specifications.

Parameters:

store_folder (str) – Local path to folder where data will be store, defaults to None. If not specified, path set to local ~/Downloads/earthspy.

Returns:

Local path to folder where data will be store.

Return type:

str

merge_rasters()[source]

Merge raster files downloaded in SM download mode using GDAL merge capability. A “mosaic” code is added to the name of the file in which the different rasters have been merged.

Return type:

None

rename_output_files()[source]

Reorganise the default folder structure and file naming of Sentinel Hub services. Files are renamed using the acquisition date and the data collection. If download in SM mode, then the different rasters with the same date are numbered after the acquisition date.

Return type:

None

send_sentinelhub_requests()[source]

Send the Sentinel Hub API request depending on user specifications (mainly download mode and multithreading).

Return type:

list

sentinelhub_request(date, loc_bbox)[source]

Send the Sentinel Hub API request with settings depending on the multithreading strategy.

If parallelized on split_boxes, then date_range is run in sequence for each split box. If parallelized on date_range, then split_boxes are run in sequence (all split boxes for one date run on the same CPU).

Parameters:

date (pd._libs.tslibs.timestamps.Timestamp) – Date to process.

Returns:

List of the Sentinel Hub requests run in sequence

Return type:

list

set_correct_resolution()[source]

Set download resolution based on a combination of download mode and user specifications.

Returns:

Resolution in meters to use for data download.

Return type:

int

set_number_of_cores(nb_cores)[source]

Set number of cores if not specified by user.

Returns:

Number of cores to use in multithreading.

Return type:

int

set_query_parameters(bounding_box, time_interval, data_collection, evaluation_script=None, resolution=None, store_folder=None, multithreading=True, nb_cores=None, download_mode='SM', remove_splitboxes=True, verbose=True, raster_compression=None)[source]

Define a set of parameters used for the API request.

Parameters:

  • bounding_box (Union[list, str]) – Area footprint with the format [min_x, min_y, max_x, max_y]. An area name stored in a JSON database can also be passed.

  • time_interval (Union[int, tuple]) – Number of days from present date or beginning and end date strings.

  • evaluation_script (str) – Custom script (preferably evalscript V3) or URL to a custom script on https://custom-scripts.sentinel-hub.com/. If not specified, a default script is used.

  • data_collection (str) – Data collection name. Check shb.DataCollection.get_available_collections() for a list of all collections currently available.

  • resolution (Union[None, int], optional) – Resolution in meters to use for data download, defaults to None. If not specified, the raw data collection resolution is used.

  • store_folder (Union[None, str], optional) – Local path to folder where data will be store, defaults to None. If not specified, path set to local ~/Downloads/earthspy.

  • multithreading (bool, optional) – Whether or not to download in multithreading, defaults to True.

  • nb_cores (Union[None, int], optional) – Number of cores to use in multithreading, defaults to None. If not specified, set to the number of cores available minus 2 (to avoid CPU overload).

  • download_mode (bool, optional) – Whether to perform a Direct (D) or Split and Merge (SM) download, defaults to “SM”. D uses the maximum resolution achievable keeping the 2500*2500 pixels maximum size set by Sentinel Hub services. SM breaks the initial area in as many bounding boxes needed to achieve specified (or raw) resolution.

  • remove_splitboxes (bool) – Whether to remove rasters of split boxes after merge (mosaic creation) or not.

  • verbose (bool, optional) – Whether to print processing status or not, defaults to True.

  • raster_compression (Union[None, str], optional) – Raster compression to apply following methods available in rasterio, defaults to None.

Return type:

None

set_split_boxes_ids()[source]

Set split boxes ids as simple integers to be accessed anytime in random order (mostly for multithreading).

Return type:

dict