Client/Fusion#

class core.Client(id=None, backend_url=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)[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.

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 only one scene per date matching the date and query_filter parameters. The default selection between multiple scenes for the same date chooses the latest observation to return. This behavior is currently fluid and will change to reflect that of s2_search in upcoming versions.

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.

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. Please note this behaviour is currently different than that of s1_search.

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.

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