eodal.core.scene module

A SceneCollection is a collection of scenes. A Scene is a RasterCollections with an acquisition date, an unique identifier and a (remote sensing) platform that acquired the raster data.

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.core.scene.SceneCollection(scene_constructor: Callable[[...], RasterCollection] | None = None, indexed_by_timestamps: bool | None = True, *args, **kwargs)[source]

Bases: MutableMapping

Collection of 0:N scenes where each scene is a RasterCollection with non-empty SceneProperties as each scene is indexed by its acquistion time.

__init__(scene_constructor: Callable[[...], RasterCollection] | None = None, indexed_by_timestamps: bool | None = True, *args, **kwargs)[source]

Initializes a SceneCollection object with 0 to N scenes.

Parameters:

  • scene_constructor – optional callable returning an ~eodal.core.raster.RasterCollection instance.

  • indexed_by_timestamps – if True, all scene indices are interpreted as timestamps (datetime.datetime). Set to False if scene indices should be treated as different data types

  • args – arguments to pass to scene_constructor or one of RasterCollection’s class methods (e.g., RasterCollection.from_multi_band_raster)

  • kwargs – key-word arguments to pass to scene_constructor or one of RasterCollection’s class methods (e.g., RasterCollection.from_multi_band_raster)

add_scene(scene_constructor: Callable[[...], RasterCollection] | RasterCollection, *args, **kwargs) → None[source]

Adds a Scene to the collection of scenes.

Raises an error if a scene with the same timestamp already exists (unique timestamp constraint)

Parameters:

  • scene_constructor – callable returning a ~eodal.core.raster.RasterCollection instance or existing RasterCollection instance

  • args – positional arguments to pass to scene_constructor

  • kwargs – keyword arguments to pass to scene_constructor

apply(func: Callable, *args, **kwargs) → Any[source]

Apply a custom function to a SceneCollection.

Parameters:

  • func – custom callable taking the SceneCollection as first argument

  • args – optional arguments to pass to func

  • kwargs – optional keyword arguments to pass to func

Returns:

results of func

clip_scenes(inplace: bool | None = False, **kwargs)[source]

Clip scenes in a SceneCollection to a user-defined spatial bounds.

Parameters:

  • inplace – if False (default) returns a copy of the SceneCollection instance with the changes applied. If True overwrites the values in the current instance.

  • **kwargs –

    key-word arguments to pass to RasterCollection.clip_bands method.

copy()[source]

returns a true copy of the SceneCollection

property empty: bool

Scene Collection is empty

classmethod from_pickle(stream: bytes | Path)[source]

Load SceneCollection from pickled binary stream.

Parameters:

stream – pickled binary stream to load into a SceneCollection or file-path to pickled binary on disk.

Returns:

SceneCollection instance.

classmethod from_raster_collections(raster_collections: List[RasterCollection] | Tuple[RasterCollection], sort_scenes: bool | None = True, sort_direction: str | None = 'asc', **kwargs)[source]

Create a SceneCollection from a list/tuple of N RasterCollection objects.

Parameters:

  • raster_collections – list or tuple of RasterCollections from which to create a new scene collection.

  • sort_scenes – if True (default) scenes are order in chronological order by their acquisition time.

  • sort_direction – direction of sorting. Must be either ‘asc’ (ascending) or ‘desc’ (descending). Ignored if sort_scenes is False.

  • kwargs – key word arguments to pass to SceneCollection constructor call.

Returns:

SceneCollection instance

get_feature_timeseries(vector_features: Path | GeoDataFrame | str, reindex_dataframe: bool | None = False, **kwargs) → GeoDataFrame[source]

Get a time series for 1:N vector features from SceneCollection.

Parameters:

  • vector_features – vector features for which to extract time series data. If Point geometries are provided calls ~RasterCollection.get_pixels() on all scenes in the collection. If Polygon (or MultiPolygons) are provided, calls ~RasterCollection.band_summaries() on all scenes in the collection.

  • reindex_dataframe – boolean flag whether to reindex the resulting GeoDataFrame after extracting data from all scenes. Set to True to ensure that the returned GeoDataFrame has a unique index. False by default.

  • kwargs – key word arguments to pass to ~RasterCollection.get_pixels() or ~RasterCollection.band_summaries() depending on the type of the input geometries.

Returns:

GeoDataFrame with extracted raster values per feature and time stamp

property identifiers: List[str]

list of scene identifiers

property indexed_by_timestamps: bool
property is_sorted: bool

are the scenes sorted by their timstamps?

plot(band_selection: str | List[str], max_scenes_in_row: int | None = 6, eodal_plot_kwargs: Dict | None = {}, **kwargs) → Figure[source]

Plots scenes in a SceneCollection

Parameters:

  • band_selection – selection of band(s) to use for plotting. Must be either a single band or a set of three bands

  • max_scenes_in_row – number of scenes in a row. Set to 6 by default.

  • eodal_plot_kwargs – optional keyword arguments to pass on to eodal.core.band.Band.plot()

  • kwargs – optional keyword arguments to pass to matplotlib.subplots().

Returns:

Figure object

sort(sort_direction: str | None = 'asc')[source]

Returns a sorted copy of the SceneCollection.

Parameters:

sort_direction – direction of sorting. Must be either ‘asc’ (ascending) or ‘desc’ (descending). Ignored if sort_scenes is False.

Returns:

sorted SceneCollection.

property timestamps: List[str | Any]

acquisition timestamps of scenes in collection

to_pickle() → bytes[source]

Dumps a scene collection as pickled object

Returns:

pickled binary object

to_xarray(**kwargs) → DataArray[source]

Converts all scenes in a SceneCollection to a single xarray.DataArray.

Parameters:

kwargs – key word arguments to pass to ~RasterCollection.to_xarray

Returns:

SceneCollection as xarray.DataArray