eodal.core.sensors.sentinel2 module

This module contains the Sentinel2 class that inherits from eodal’s core RasterCollection class.

The Sentinel2 class enables reading one or more spectral bands from Sentinel-2 data in .SAFE format which is ESA’s standard format for distributing Sentinel-2 data.

The class handles data in L1C and L2A processing level.

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.sensors.sentinel2.Sentinel2(band_constructor: Callable[[...], Band] | None = None, scene_properties: SceneProperties | None = None, *args, **kwargs)[source]

Bases: RasterCollection

Class for storing Sentinel-2 band data read from bandstacks or .SAFE archives (L1C and L2A level) overwriting methods inherited from ~eodal.utils.io.SatDataHandler.

classmethod from_safe(in_dir: Path | Dict[str, str], band_selection: List[str] | None = None, read_scl: bool | None = True, apply_scaling: bool | None = True, **kwargs)[source]

Loads Sentinel-2 data into a RasterCollection.

There are two options:

  • Read data from a .SAFE archive which is ESA’s standard format for distributing Sentinel-2 data (L1C and L2A processing levels).

  • Read data from a Asset-List returned from a STAC query

Note

If a spatial subset is read (vector_features in kwargs) the single S2 bands are clipped to the spatial extent of the S2 in the band selection with the coarsest (lowest) spatial resolution. This way it is ensured that all bands share the same spatial extent regardless of their spatial resolution (10, 20, or 60m). This is possible because all bands share the same origin (upper left corner).

Parameters:

  • in_dir – file-path to the .SAFE directory containing Sentinel-2 data in L1C or L2A processing level or collection of hyper-links in the case of STAC

  • band_selection – selection of Sentinel-2 bands to read. Per default, all 10 and 20m bands are processed. If you wish to read less or more, specify the band names accordingly, e.g., [‘B02’,’B03’,’B04’] to read only the VIS bands. If the processing level is L2A the SCL band is always loaded unless you set read_scl to False.

  • read_scl – read SCL file if available (default, L2A processing level).

  • apply_scaling – apply Sentinel-2 gain and offset factor to derive reflectance values scaled between 0 (negative values are possible from baseline N0400 onwards) and 1 (default behavior). Because of the reflectance offset of -1000 introduced with PDGS baseline N0400 in January 2022 applying the automatized scaling is recommended to always obtain physically correct reflectance factor values - at the cost of higher storage requirements because scaling converts the data to float32.

  • kwargs – optional key-word arguments to pass to ~eodal.core.band.Band.from_rasterio

Returns:

Sentinel2 instance with S2 bands loaded

get_cloud_and_shadow_mask(mask_band: str | None = 'scl', inplace: bool | None = False, name_cloud_mask: str | None = 'cloud_mask', cloud_classes: list[int] | None = [1, 2, 3, 7, 8, 9, 10, 11]) → Sentinel2 | None[source]

Generate a binary cloud mask from the Scene Classification Layer (SCL) that is part of the standard ESA product.

Note

You can specify any band instance instead of SCL as long as the band has an integer data type.

Parameters:

  • mask_band – The name of the band to use for masking. Default is ‘scl’.

  • inplace – Whether to return a new Band instance or add a Band to the current Sentinel2 instance. Default is False.

  • name_cloud_mask – The name of the water mask band. Default is ‘water_mask’.

  • cloud_classes – list of SCL values to be considered as clouds/shadows and snow. By default, all three cloud classes and cloud shadows are considered plus snow.

Returns:

A Band instance containing the cloud mask or None if inplace is True.

get_cloudy_pixel_percentage(cloud_classes: List[int] | None = [2, 3, 7, 8, 9, 10, 11]) → float[source]

Calculates the cloudy pixel percentage [0-100] for the current AOI (L2A processing level, only) considering all SCL classes that are not NoData.

Parameters:

  • cloud_classes – list of SCL values to be considered as clouds. By default, all three cloud classes and cloud shadows are considered.

  • check_for_snow – if True (default) also counts snowy pixels as clouds.

Returns:

cloudy pixel percentage in the AOI [0-100%] related to the overall number of valid pixels (SCL != no_data)

get_scl_stats() → DataFrame[source]

Returns a DataFrame with the number of pixel for each class of the scene classification layer. Works for data in L2A processing level, only.

Returns:

DataFrame with pixel count of SCL classes available in the currently loaded Sentinel-2 scene. Masked pixels are ignored and also not used for calculating the relative class occurences.

property is_blackfilled: bool

Checks if the scene is black-filled (nodata only)

mask_clouds_and_shadows(bands_to_mask: List[str] | None = None, cloud_classes: List[int] | None = [1, 2, 3, 7, 8, 9, 10, 11], mask_band: str | None = 'SCL', **kwargs) → None | Sentinel2[source]

A Wrapper around the inherited mask method to mask clouds, shadows, water and snow based on (by default) the SCL band. Works therefore on L2A data, only.

Note

Since the mask_band can be set to any Band it is also possible to use a different cloud/shadow etc. mask, e.g., from a custom classifier.

Note

You might also use the mask function from eodal.core.raster.RasterCollection directly.

Parameters:

  • bands_to_mask – list of bands on which to apply the SCL mask. If not specified all bands are masked.

  • cloud_classes – list of SCL values to be considered as clouds/shadows and snow. By default, all three cloud classes and cloud shadows are considered plus snow.

  • kwargs – optional kwargs to pass to ~eodal.core.raster.RasterCollection.mask

Returns:

depending on inplace (passed in the kwargs) a new Sentinel2 instance or None

plot_scl(colormap: str | None = '') → Figure[source]

Wrapper around plot_band method to plot the Scene Classification Layer available from the L2A processing level. Raises an error if the band is not available

Parameters:

colormap – optional matplotlib named colormap to use for visualization. If not provided uses a custom color map that tries to reproduce the standard SCL colors provided by ESA.

Returns:

matplotlib figure object with the SCL band data plotted as map

classmethod read_pixels_from_safe(in_dir: Dict[str, Any] | Path, vector_features: Path | GeoDataFrame, band_selection: List[str] | None = None, read_scl: bool | None = True, apply_scaling: bool | None = True) → GeoDataFrame[source]

Extracts Sentinel-2 raster values at locations defined by one or many vector geometry features read from a vector file (e.g., ESRI shapefile) or GeoDataFrame.

The Sentinel-2 data must be organized in .SAFE archive structure in either L1C or L2A processing level. Each selected Sentinel-2 band is returned as a column in the resulting GeoDataFrame. Pixels outside of the band bounds are ignored and not returned as well as pixels set to blackfill (zero reflectance in all spectral bands).

Important

This function works for Sentinel-2 data organized in .SAFE format! If the Sentinel-2 data has been converted to multi-band tiffs, use ~Sentinel2().read_pixels() instead.

Note

A point is dimension-less, therefore, the raster grid cell (pixel) closest to the point is returned if the point lies within the raster. Therefore, this method works on all Sentinel-2 bands without the need to do spatial resampling! The underlying rasterio.sample function always snaps to the closest pixel in the current spectral band.

Parameters:

  • in_dir – Sentinel-2 scene in .SAFE structure from which to extract pixel values at the provided point locations. Can be either a dictionary item returned from STAC or a physical file-path

  • vector_features – vector file (e.g., ESRI shapefile or geojson) or GeoDataFrame defining point locations for which to extract pixel values

  • band_selection – list of bands to read. Per default all raster bands available are read.

  • read_scl – read SCL file if available (default, L2A processing level).

  • apply_scaling – apply Sentinel-2 gain and offset factor to derive reflectance values scaled between 0 (negative values are possible from baseline N0400 onwards) and 1 (default behavior). Because of the reflectance offset of -1000 introduced with PDGS baseline N0400 in January 2022 applying the automatized scaling is recommended to always obtain physically correct reflectance factor values - at the cost of higher storage requirements because scaling converts the data to float32.

Returns:

GeoDataFrame containing the extracted raster values. The band values are appended as columns to the dataframe. Existing columns of the input in_file_pixels are preserved.