Client/Fusion
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 byClient.compute_ard()
andClient.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 byClient.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 setsself.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 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
- Returns
models.Sentinel1SearchResult
object, continaing a pandas dataframe with the resulting S1 scenes from the searchThe 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()
ormodels.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 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
- Returns
models.Sentinel2SearchResult
object, continaing a pandas dataframe with the resulting S2 scenes from the searchThe 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()
ormodels.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.
- 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 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
- Returns
models.LandsatSearchResult
object, continaing a pandas dataframe with the resulting Landsat scenes from the searchThe 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
- 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
- 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
- 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
- Returns
models.WeatherSearchResult
object, continaing a pandas dataframe with the resulting weather dataThe 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