eodal.core.sensors.landsat module

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

The Landsat class enables reading one or more spectral bands from Landsat 5 to 9 science products in L2 processing level.

The class handles data in L1C and L2A processing level.

Copyright (C) 2023 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.landsat.Landsat(band_constructor: Callable[[...], Band] | None = None, scene_properties: SceneProperties | None = None, *args, **kwargs)[source]

Bases: RasterCollection

Class for working with Landsat science products (Level-2).

calc_si(si_name: str, inplace: bool | None = False, band_mapping: Dict[str, str] | None = {}) → None | ndarray | MaskedArray[source]

Calculates a spectral index based on color-names (set as band aliases)

Parameters:

  • si_name – name of the spectral index to calculate (e.g., ‘NDVI’).

  • inplace – if False, returns the calculated SI as numpy array (default), else adds the calculated SI as a new band to the RasterCollection object.

  • band_mapping – ..versionadd 0.2.2:: optional band mapping to use different color names instead of the default ones (e.g., nir_2 instead of nir_1 as default near-infrared band, which might be helpful for some sensor with more than one NIR band such as Sentinel-2 MSI). See ~`eodal.core.spectral_indices.SpectralIndices` how band_mapping must look like.

classmethod from_usgs(in_dir: Path | Dict[str, str], band_selection: List[str] | None = None, read_qa: bool | None = True, read_atcor: bool | None = False, apply_scaling: bool | None = True, **kwargs)[source]

Load Landsat Level-2 science products (spectral bands, thermal bands, QA bands) into a EOdal `RasterCollection.

Parameters:

  • in_dir – Path to the directory containing the Landsat data or collection of hyper-links in the case of STAC. If a dictionary is passed, we assume that all files are stored in the same directory.

  • band_selection – List of bands to be loaded. If None, all bands will be loaded. The bands loaded depend on the sensor, e.g., TM, ETM, OLI, TIRS. The sensor will be auto-detected. To make sure, the band selection works for multiple sensors, use the aliases defined in ~eodal.utils.constants.landsat_band_mapping. For instance, to load the VIS bands pass [“blue”, “green”, “red”].

  • read_qa – If True, the QA bands will be loaded as well. Default is True.

  • read_atcor – If True, the bands stemming from the atmospheric correction are read as well. Default is False.

  • apply_scaling – If True, scales reflectance values to the range [0, 1] from original unsigned 16-bit integers. Default is True.

  • kwargs – Additional keyword arguments passed to the RasterCollection constructor.

Returns:

RasterCollection containing the Landsat bands.

get_cloud_and_shadow_mask(mask_band: str | None = 'qa_pixel', inplace: bool | None = False, name_cloud_mask: str | None = 'cloud_mask', cloud_classes: list[int] = [1, 2, 3, 5]) → Band | None[source]

Get a cloud and shadow mask from the pixel qualuty band (using bits [1, 2, 3, 5] by default)

Note

Since the mask_band can be set to any Band it is also possible to use a different cloud mask, e.g., from a custom classifier as long as the bit map used for the classes is the same. See also https://www.usgs.gov/media/images/landsat-collection-2-pixel-quality-assessment-bit-index for more details.

Parameters:

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

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

  • name_cloud_mask – The name of the cloud mask band. Default is ‘cloud_mask’.

  • cloud_classes – Classes that define “clouds”. Default is [1, 2, 3, 5].

Returns:

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

get_water_mask(mask_band: str | None = 'qa_pixel', inplace: bool | None = False, name_water_mask: str | None = 'water_mask', water_class: int = 7) → Band | None[source]

Get a water mask from the pixel quality band (bit 7 by default).

Note

Since the mask_band can be set to any Band it is also possible to use a different water mask, e.g., from a custom classifier as long as the bit map used for the classes is the same. See also https://www.usgs.gov/media/images/landsat-collection-2-pixel-quality-assessment-bit-index for more details.

Parameters:

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

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

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

  • water_class – Bit number of the water class. 7 by default.

Returns:

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

mask_clouds_and_shadows(bands_to_mask: list[str] | None = None, cloud_classes: list[int] | None = [1, 2, 3, 5], mask_band: str | None = 'qa_pixel', **kwargs) → None | Landsat[source]

A wrapper around the inherited mask method to mask cirrus, cloud and cloud shadow pixels in Landsat scenes based on the pixel quality band.

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 as long as the bit map used for the classes is the same. See also https://www.usgs.gov/media/images/landsat-collection-2-pixel-quality-assessment-bit-index for more details.

Note

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

Parameters:

  • bands_to_mask – A list of bands to mask. Default is all bands.

  • cloud_classes – A list of integers indicating the cloud classes to mask. Default is [1, 2, 3, 5].

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

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

Returns:

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

mask_from_qa_bits(bit_range: tuple, band_name: str | None = 'qa_pixel') → ndarray | MaskedArray[source]

Extract Quality Accurance (QA) bits from the QA band of Landsat to obtain a binary mask.

This function can be used to obtain a binary cloud or cloud shadow mask, for example.

Parameters:

  • bit_range – A tuple of two integers indicating the start and end bit of the bit range to extract.

  • band_name – The name of the QA band. Default is ‘qa_pixel’.

Returns:

A 2-dimensional numpy array containing the obtained mask.