Client/Fusion#

class core.Client(id=None, backend_url=None, api_key=None)[source]#

Class that allows you to interact with SpaceSense backend. This is the access point to the major SpaceSense processes such as searching for satellite and catalog scenes and data fusion. You can interact with this class to change the result options, such as CRS, resolution, and if and where to save the result.

__init__(id=None, backend_url=None, api_key=None)[source]#

Create an instance of the Client

Parameters
  • id (str, optional) – Unique id of your client instance used to organize results and track usage. If not specified, automatically generates a unique ID

    Default: None

  • backend_url (str, optional) – For development purposes only

    Default: None

set_output_crs(output_crs)[source]#

Set the desired output CRS.

Parameters

output_crs (int) – Desired output CRS number. Default: '4326'

Set self.output_crs to a specified EPSG code as an int. self.output_crs will define the EPSG of the output returned by Client.compute_ard() and Client.fuse()

set_output_resolution(resolution)[source]#

Set the desired output pixel size (resolution).

Parameters

resolution (int) – desired output resolution.

Set self.output_resolution to a specified output resolution in meters²/pixel. Default value is 10m²/pixel. self.output_resolution will define the resolution of the output returned by Client.fuse()

Catalog Data

Type

Description

Native Resolution

Sentinel-1

Satellite (SAR)

Sentinel-1 Interferometric Wide swath (IW) mode of level 1 Ground Range Detected (GRD) data

10m²/pixel

Sentinel-2

Satellite (Optical and NIR)

Level 2A atmospherically corrected data

10m²/pixel

Please keep these native resolution in mind when up or downscaling the output resolution.

enable_local_output(local_output_path='./generated')[source]#

Enables the local output option. Saves the fused result to a netCDF file in the ./generated folder with the client ID as a sub-directory.

Parameters

local_output_path (str, optional) – path to local directory.

Default: './generated'

Sets self.save_to_local to True and sets self.local_output_path to the desired local output path string. The output will be saved in the specified directory.

disable_local_output()[source]#

Disables the local output option.

Sets self.save_to_local to False The output will no longer be saved in the specified local directory.

Search for Sentinel-1 scenes in a given area of interest. Currently, single AOIs are limited to a total size of 250km2 or smaller.

Parameters
  • aoi (geojson) – A GeoJSON polygon

  • start_date (str or datetime) – Start date of the search

  • end_date (str or datetime) – End date of the search

  • query_filters (dict, optional) – Filters to apply to the search query

    Default: {}

  • data_coverage (int, optional) – Minimum percent of the AOI covered by valid (i.e. non NaN) S1 data

    Default: 100

Return type

models.Sentinel1SearchResult

Returns

models.Sentinel1SearchResult object, continaing a pandas dataframe with the resulting S1 scenes from the search

The following S1 scene parameters are usable in the query_filter parameter:

  • orbitdirection

  • relativeorbitnumber

  • lastrelativeorbitnumber

  • orbitnumber

  • lastorbitnumber

  • polarizationmode

Note

s1_search by default returns ALL S1 scenes meeting the date and query_filter parameters. This means there can be single dates with more than one S1 observation in the search result (e.g. overlapping tiles). As mosaicing is not yet supported, only a single observation per date is currently allowed by the fuse function, so one can use the “filter_duplicate_dates” function of the search result to automatically take the observation with the best coverage.

Warning

The duration of the search is limited in this interactive search mode. Searching for more than 2 years of Sentinel-1 or Sentinel-2 data in a single “s1_search” or “s2_search” may result in errors or non-response from our backend.

If you wish to search for more than 2 years, we recommend using multiple, ideally yearly, searches and concatenating them with the models.Sentinel1SearchResult.concat() or models.Sentinel2SearchResult.concat() methods.

SpaceSense considers it best practice to use 1 year as the maximum search duration.

Example

>>> query_filters = {"orbitdirection" : "DESCENDING", "lastrelativeorbitnumber" : "52"}
>>> client.s1_search(aoi = aoi,
                     start_date = start_date,
                     end_date = end_date,
                     query_filters = query_filters)

For more examples, please see the Search S1 and S2 and Search and filter S1 and S2 data.

Search for Sentinel-2 scenes in a given area of interest. Currently, single AOIs are limited to a total size of 250km2 or smaller.

Parameters
  • aoi (geojson) – A GeoJSON polygon

  • start_date (str or datetime) – Start date of the search

  • end_date (str or datetime) – End date of the search

  • query_filters (dict, optional) – Filters to apply to the search query

    Default: None

Return type

models.Sentinel2SearchResult

Returns

models.Sentinel2SearchResult object, continaing a pandas dataframe with the resulting S2 scenes from the search

The following S2 scene parameters are usable in the query_filter parameter:

  • valid_pixel_percentage

  • swath_coverage_percentage

  • no_data

  • cloud_shadows

  • vegetation

  • not_vegetated

  • water

  • cloud_medium_probability

  • cloud_high_probability

  • thin_cirrus

  • snow

Note

s2_search by default returns ALL S2 scenes meeting the date and query_filter parameters. This means there can be single dates with more than one S2 observation in the search result (e.g. overlapping tiles). As mosaicing is not yet supported, only a single observation per date is currently allowed by the fuse function, so one can use the “filter_duplicate_dates” function of the search result to automatically take the observation with the best coverage.

Warning

The duration of the search is limited in this interactive search mode. Searching for more than 2 years of Sentinel-1 or Sentinel-2 data in a single “s1_search” or “s2_search” may result in errors or non-response from our backend.

If you wish to search for more than 2 years, we recommend using multiple, ideally yearly, searches and concatenating them with the models.Sentinel1SearchResult.concat() or models.Sentinel2SearchResult.concat() methods.

SpaceSense considers it best practice to use 1 year as the maximum search duration.

Example

>>> query_filters = {"valid_pixel_percentage" : {">=": 50}, "cloud_medium_probability" : {"<=": 50}})
>>> res_S2 = client.s2_search(aoi = aoi,
                              start_date = start_date,
                              end_date = end_date,
                              query_filters = query_filters)

For more examples, please see the Search S1 and S2 and Search and filter S1 and S2 data.

fuse(catalogs_list, fuse_id=None, aoi=None, to_fuse=[], additional_info=None, output_resolution=None, output_crs=None)[source]#

Fuses catalog search results with any provided georeferenced raster and/or vector files.

If only one catalog data type (Sentinel-1 or Sentinel-2) and no custom raster or vector files are provided, the fusion simply obtains and temporally fuses the satellite data.

In general, fusion applies the following steps:
  • Reproject all data to the same CRS (if different)

  • Rasterize any vector objects

  • Clip all data to the same extent

  • Resample all data to the same pixel size

  • Co-register all data to the same grid

  • Stack all data into a single, time-enabled object

In order to change the behavior of this method you can use other methods of Client.

Note

Resampling is performed using a nearest neighbor resampling technique. For this initial version, there is no way to change the resampling type, however this feature is coming soon.

Parameters
  • catalogs_list (List[Union[Sentinel1SearchResult, Sentinel2SearchResult]]) – List containing catalog search result objects.

  • to_fuse (List[Union[Raster, Vector]], optional) – List containing Raster and/or Vector objects.

    Default: []

  • aoi (Any, optional) – Geojson feature or feature collection dictionary containing a polygon, overriding AOI provided in search result objects.

    Default: None

  • additional_info (dict, optional) – Dictionary containing any additional information to fuse into the resulting attributes.

    Default: None

  • output_resolution (int, optional) – Pixel size desired for all layers of the fused object, overriding client resolution.

    Default: None

  • output_crs (int, optional) – CRS in EPSG format desired for all layers of the fused object, overriding client CRS.

    Default: None

  • fuse_id (str, optional) – Numeric identifier of the fuse process.

    Default: None

Return type

FuseResult

Raises

ValueError – input is invalid.

Example

>>> client = Client()
>>> # Change the output CRS
>>> client.set_output_crs(3857)
>>> # Change the output resolution
>>> client.set_output_resolution(8)
>>> # Enable saving the result to a local file
>>> client.enable_local_output()
>>> # Fused data will be in CRS 3857 and
>>> # at a resolution of 8 meters²/pixel
>>> # Results will be saved at the default "./generated" directory
>>> output = client.fuse([S1_search_results, S2_search_results])
get_job(id, experiment_id=None)[source]#

Load a job from its id.

Specifying an experiment id is optional, but recommended,

if you are not using the same experiment id as the one used to start the job. you will need to specify the experiment id used for the job

Parameters
  • id – ID generated when starting a job,

  • experiment_id (str, optional) – ID of the experiment

    Default: None

Returns

Job

get_job_list(experiment_id=None, workflow_id=None)[source]#

get the list of all your jobs

Parameters
  • experiment_id (str, optional) – (optional) filter the job list by experiment, by default, will look in every experiment.

    Default: None

  • workflow_id (str, optional) – (optional) filter the job list by workflow, by default, will look in every workflow.

    Default: None

Returns

Job

run_job(name, workflow, input={})[source]#

execute the selected experiment with the selected Job

static load_fusion(id, root_dir='./generated')[source]#

Load a previous fusion computation result from local disk.

Parameters
  • id (str) – previously computed fusion id.

  • root_dir (str, optional) – root directory where the fusion computation results are stored.

    Default: './generated'

Returns

FuseResult

Search for Weather data given area of interest. The data is computed from ERA5 reanalysis : ERA5 Copernicus Climate Data Store

Parameters
  • aoi (geojson) – A GeoJSON polygon

  • start_date (str or datetime) – Start date of the search

  • end_date (str or datetime) – End date of the search

  • variables (list, optional) – Weather variables desired

    Default: None

Return type

models.WeatherSearchResult

Returns

models.WeatherSearchResult object, continaing a pandas dataframe with the resulting weather data

The following weather parameter are usable in the variables parameter:

  • “MAXTEMP”: 2m_temperature maximum

  • “MINTEMP”: 2m_temperature minimum

  • “AVGTEMP”: 2m_temperature average

  • “PREC”: total_precipitation

  • “VWIND”: 10m_v_component_of_wind

  • “UWIND”: 10m_u_component_of_wind

  • “LAILOW”: leaf_area_index_low_vegetation

  • “LAIHIGH”: leaf_area_index_high_vegetation

  • “DEWTEMP”: 2m_dewpoint_temperature

Note

weather_search by default returns average 2m temperature and total precipitation only.

Example

>>> weather_variables = ["laihigh", "prec", "avgtemp", "dewtemp"]
>>> weather_df = client.weather_search(aoi = aoi,
                                start_date = start_date,
                                end_date = end_date,
                                variables = weather_variables)

For more examples, please see the Fusion with Weather