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
Landsat	Satellite (Optical and NIR)	Level 2 atmospherically corrected data	30m²/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.

s1_search(aoi, start_date, end_date, query_filters={}, data_coverage=100)[source]#

Search for Sentinel-1 scenes in a given area of interest. Currently, single AOIs are limited to a total size of 250km² 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.

s2_search(aoi, start_date, end_date, query_filters=None)[source]#

Search for Sentinel-2 scenes in a given area of interest. Currently, single AOIs are limited to a total size of 250km² 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

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.

landsat_search(aoi, start_date, end_date, query_filters=None)[source]#

Search for Landsat scenes in a given area of interest. Currently, single AOIs are limited to a total size of 250km² 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.LandsatSearchResult

Returns

models.LandsatSearchResult object, continaing a pandas dataframe with the resulting Landsat scenes from the search

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

fill*

dilated*

cirrus*

cloud*

shadow*

snow*

clear*

water*

swath_coverage_percentage*

valid_pixel_percentage*

Note

landsat_search by default returns ALL Landsat scenes meeting the date and query_filter parameters. This means there can be single dates with more than one Landsat observation in the search result (e.g. overlapping tiles, different satelite). 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 Landsat data in a single 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.LandsatSearchResult.concat() method.

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

Example

>>> query_filters = {"valid_pixel_percentage" : {">=": 50}, "cloud" : {"<=": 50}})
>>> res_landsat = client.landsat_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, Sentinel-2 or Landsat) 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, LandsatSearchResult]]) – 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

weather_search(aoi, start_date, end_date, variables=None)[source]#

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