eodal.mapper.mapper module

The EOdal Mapper class allows to extract and handle EO data in space and time and bring the data into Analysis-Ready-Format (ARD).

New in version 0.2.0.

Copyright (C) 2022 Lukas Valentin Graf

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

class eodal.mapper.mapper.Mapper(mapper_configs: MapperConfigs, time_column: str | None = 'sensing_time')[source]

Bases: object

Generic class for mapping Earth Observation Data across space and time and bring them into Analysis-Readay-Format (ARD).

The mapper class takes over searching for EO scenes, merging them and filling eventually occurring black-fill (no-data regions).

Attrib mapper_configs:

MapperConfig instance defining search criteria

Attrib data:

loaded scene data as EOdal SceneCollection

Attrib metadata:

corresponding scene metadata as GeoDataFrame.

__init__(mapper_configs: MapperConfigs, time_column: str | None = 'sensing_time')[source]

Class constructor

Parameters:

  • mapper_configs – MapperConfig instance defining search criteria

  • time_column – name of the metadata column denoting the time stamps of the scenes. sensing_time by default.

property data: None | SceneCollection | GeoDataFrame

SceneCollection with scenes found or GeoDataFrame in case single pixel values are extracted

load_scenes(scene_kwargs: Dict[str, Any] | None = None, pixel_kwargs: Dict[str, Any] | None = None, round_time_stamps_to_freq: str | None = None) → None[source]

Load scenes from ~Mapper.query_scenes result into a SceneCollection (Polygon and MultiPolygon geometries) or into a GeoDataFrame (Point and MultiPoint geometries).

Mosaicing operations are handled on the fly so calling programs will always receive analysis-ready data (e.g., when working across image tiles).

Parameters:

  • scene_kwargs – key-word arguments to pass to ~Mapper._load_scenes_collection for handling EOdal scenes. These arguments MUST be provided when using Polygon or MulitPolygon geometries in the Mapper call.

  • pixel_kwargs – key-word arguments to pass to ~Mapper._load_pixels for handling single pixel values. These arguments MUST be provided when using Point or MulitPoint geometries in the Mapper call.

  • round_time_stamps_to_freq – ..versionadd:: 0.2.2 optionally round scene time stamps to a custom temporal frequency accepted by ~pandas.Timestamp.round to allow moscaicing of scenes with slightly different timestamps as it might be necessary for some EO platforms.

property mapper_configs: MapperConfigs

mapper configurations

property metadata: None | GeoDataFrame

scene metadata found

query_scenes() → None[source]

Query available scenes for the current MapperConfigs and loads into the observations attribute.

Depending on the settings of EOdal, this method either makes a query to a STAC resource or to a PostgreSQL/PostGIS database.

Note

This method only queries a metadata catalog without reading data.

property sensor: str | None
property time_column: str
class eodal.mapper.mapper.MapperConfigs(collection: str, feature: Feature, time_start: datetime, time_end: datetime, metadata_filters: List[Filter] | None = None)[source]

Bases: object

global configurations of the Mapper class defining metadata search criteria (space and time), data collections to search and behavior for bringing data into analysis-ready-format (ARD)

Attrib collection:

name of the collection (<platform>-<sensor>-<processing level>) to use. E.g., “Sentinel2-MSI-L2A

Attrib feature:

geographic feature(s) for which to extract data from collection

Atrrib time_start:

time stamp from which onwards to extract data from collection

Atrrib time_end:

time stamp till which to extract data from collection

Attrib metadata_filters:

list of custom metadata filters to shrink collection to. Examples include cloud cover filters in the case of optical data or filter by incidence angle in the case of SAR observations.

Attrib data_source:

denotes from which resource (local archive, STAC archive) the data was read from including the STAC API end point URL.

__init__(collection: str, feature: Feature, time_start: datetime, time_end: datetime, metadata_filters: List[Filter] | None = None)[source]

default class constructor

Parameters:

  • collection – name of the collection (<platform>-<sensor>) to use. E.g., “sentinel2-msi”. <sensor> is optional and can be omitted if a platform does not carry more than a single sensor. I.e., one could also pass “sentinel2” instead.

  • feature – geographic feature(s) for which to extract data from collection

  • time_start – time stamp from which onwards to extract data from collection

  • time_end – time stamp till which to extract data from collection

  • metadata_filters –

    list of custom metadata filters to shrink collection to. Examples include cloud cover filters in the case of optical data or filter by incidence angle in the case of SAR observations.

property collection: str
property data_source: str
property feature: Feature
classmethod from_yaml(fpath: str | Path)[source]

Load mapping configurations from YAML file

Parameters:

fpath – file-path to yaml with Mapper configurations

Returns:

new MapperConfigs instance

property metadata_filters: List[Filter] | None
property platform: str
property sensor: str
property time_end: datetime
property time_start: datetime
to_yaml(fpath: str | Path) → None[source]

save MapperConfig and some meta-information to YAML file (*.yml)

Parameters:

fpath – file-path where saving the Feature instance to