mapchete-eo 2026.2.0__py3-none-any.whl

mapchete_eo/platforms/sentinel2/brdf/config.py

@@ -0,0 +1,32 @@
+from enum import Enum
+from typing import NamedTuple
+
+
+class BRDFModels(str, Enum):
+    none = "none"
+    HLS = "HLS"
+    RossThick = "RossThick"
+
+
+class ModelParameters(NamedTuple):
+    f_iso: float
+    f_geo: float
+    f_vol: float
+
+
+# Source for bands outside of RGBNIR range:
+# https://www.sciencedirect.com/science/article/pii/S0034425717302791
+# https://www.semanticscholar.org/paper/Adjustment-of-Sentinel-2-Multi-Spectral-Instrument-Roy-Li/be90a03a19c612763f966fae5290222a4b76bba6
+class L2ABandFParams(ModelParameters, Enum):
+    B01 = ModelParameters(0.0774, 0.0079, 0.0372)
+    B02 = ModelParameters(0.0774, 0.0079, 0.0372)
+    B03 = ModelParameters(0.1306, 0.0178, 0.0580)
+    B04 = ModelParameters(0.1690, 0.0227, 0.0574)
+    B05 = ModelParameters(0.2085, 0.0256, 0.0845)
+    B06 = ModelParameters(0.2316, 0.0273, 0.1003)
+    B07 = ModelParameters(0.2599, 0.0294, 0.1197)
+    B08 = ModelParameters(0.3093, 0.0330, 0.1535)
+    B8A = ModelParameters(0.3093, 0.0330, 0.1535)
+    B09 = ModelParameters(0.3201, 0.0471, 0.1611)
+    B11 = ModelParameters(0.3430, 0.0453, 0.1154)
+    B12 = ModelParameters(0.2658, 0.0387, 0.0639)

mapchete_eo/platforms/sentinel2/brdf/correction.py

@@ -0,0 +1,260 @@
+import logging
+from typing import List
+
+from mapchete import Timer
+from mapchete.io.raster import ReferencedRaster, resample_from_array
+from mapchete.protocols import GridProtocol
+from mapchete.types import NodataVal
+import numpy as np
+import numpy.ma as ma
+from numpy.typing import DTypeLike
+from rasterio.enums import Resampling
+from rasterio.fill import fillnodata
+
+from mapchete_eo.exceptions import BRDFError
+from mapchete_eo.platforms.sentinel2.brdf.models import BRDFModels, get_model
+from mapchete_eo.platforms.sentinel2.metadata_parser.s2metadata import S2Metadata
+from mapchete_eo.platforms.sentinel2.types import (
+    L2ABand,
+    Resolution,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _correction_combine_detectors(
+    s2_metadata: S2Metadata,
+    band: L2ABand,
+    out_grid: GridProtocol,
+    model: BRDFModels = BRDFModels.HLS,
+    dtype: DTypeLike = np.float32,
+) -> ma.MaskedArray:
+    """
+    Run correction using combined angle masks of all
+    """
+    return resample_from_array(
+        get_model(
+            model=model, s2_metadata=s2_metadata, band=band, processing_dtype=dtype
+        ).calculate(),
+        out_grid=out_grid,
+        nodata=0,
+        resampling=Resampling.bilinear,
+        keep_2d=True,
+    )
+
+
+def _correction_per_detector(
+    s2_metadata: S2Metadata,
+    band: L2ABand,
+    out_grid: GridProtocol,
+    model: BRDFModels = BRDFModels.HLS,
+    smoothing_iterations: int = 10,
+    dtype: DTypeLike = np.float32,
+    footprints_cached_read: bool = True,
+) -> ma.MaskedArray:
+    """
+    Run correction separately for each detector footprint.
+    """
+    # create output array
+    model_params = ma.masked_equal(np.zeros(out_grid.shape, dtype=dtype), 0)
+
+    # get detector footprints
+    detector_footprints = s2_metadata.detector_footprints(
+        band, cached_read=footprints_cached_read
+    )
+    resampled_detector_footprints = resample_from_array(
+        detector_footprints,
+        out_grid=out_grid,
+        nodata=0,
+        resampling=Resampling.nearest,
+        keep_2d=True,
+    )
+    if resampled_detector_footprints.ndim not in [2, 3]:
+        raise ValueError(
+            f"detector_footprints has to be a 2- or 3-dimensional array but has shape {detector_footprints.shape}"
+        )
+    if resampled_detector_footprints.ndim == 3:
+        resampled_detector_footprints = resampled_detector_footprints[0]
+
+    # determine available detector IDs
+    detector_ids: List[int] = [
+        detector_id
+        for detector_id in np.unique(resampled_detector_footprints)
+        if detector_id != 0
+    ]
+
+    # get viewing angle arrays per detector
+    viewing_azimuth_per_detector = s2_metadata.viewing_incidence_angles(
+        band
+    ).azimuth.detectors
+    viewing_zenith_per_detector = s2_metadata.viewing_incidence_angles(
+        band
+    ).zenith.detectors
+
+    # iterate through detector footprints and calculate BRDF for each one
+    for detector_id in detector_ids:
+        logger.debug("run on detector %s", detector_id)
+
+        # handle rare cases where detector geometries are available but no respective
+        # angle arrays:
+        if detector_id not in viewing_zenith_per_detector:  # pragma: no cover
+            logger.debug("no zenith angles grid found for detector %s", detector_id)
+            continue
+        if detector_id not in viewing_azimuth_per_detector:  # pragma: no cover
+            logger.debug("no azimuth angles grid found for detector %s", detector_id)
+            continue
+
+        # select pixels which are covered by detector
+        detector_mask = np.where(
+            resampled_detector_footprints == detector_id, True, False
+        )
+
+        # skip if detector footprint does not intersect with output window
+        if not detector_mask.any():  # pragma: no cover
+            logger.debug("detector %s does not intersect with band window", detector_id)
+            continue
+
+        # run low resolution model
+        model_values = get_model(
+            model=model,
+            s2_metadata=s2_metadata,
+            band=band,
+            detector_id=detector_id,
+            processing_dtype=dtype,
+        ).calculate()
+
+        # interpolate missing nodata edges and return BRDF difference model
+        detector_brdf_param = ma.masked_invalid(
+            fillnodata(model_values.data, smoothing_iterations=smoothing_iterations)
+        )
+
+        # resample model to output resolution
+        detector_brdf = resample_from_array(
+            detector_brdf_param,
+            out_grid=out_grid,
+            array_transform=model_values.transform,
+            in_crs=model_values.crs,
+            nodata=0,
+            resampling=Resampling.bilinear,
+            keep_2d=True,
+        )
+        # merge detector stripes
+        model_params[detector_mask] = detector_brdf[detector_mask]
+        model_params.mask[detector_mask] = detector_brdf.mask[detector_mask]
+
+    return model_params
+
+
+def correction_values(
+    s2_metadata: S2Metadata,
+    band: L2ABand,
+    model: BRDFModels = BRDFModels.HLS,
+    resolution: Resolution = Resolution["60m"],
+    footprints_cached_read: bool = False,
+    per_detector: bool = True,
+    dtype: DTypeLike = np.float32,
+) -> ReferencedRaster:
+    """Calculate BRDF correction values.
+
+    Calculation is always done on original product CRS, but the resolution
+    can be defined.
+    """
+    with Timer() as t:
+        if per_detector:
+            # Per Detector strategy:
+            brdf_params = _correction_per_detector(
+                s2_metadata=s2_metadata,
+                band=band,
+                out_grid=s2_metadata.grid(resolution),
+                model=model,
+                dtype=dtype,
+                footprints_cached_read=footprints_cached_read,
+            )
+        else:
+            brdf_params = _correction_combine_detectors(
+                s2_metadata=s2_metadata,
+                band=band,
+                out_grid=s2_metadata.grid(resolution),
+                model=model,
+                dtype=dtype,
+            )
+    logger.debug(
+        f"BRDF for product {s2_metadata.product_id} band {band.name} calculated in {str(t)}"
+    )
+    if brdf_params.mask.all():  # pragma: no cover
+        raise BRDFError(f"BRDF grid array for {s2_metadata.product_id} is empty!")
+    return ReferencedRaster(
+        data=brdf_params,
+        transform=s2_metadata.transform(resolution),
+        crs=s2_metadata.crs,
+        bounds=s2_metadata.bounds,
+        driver="COG",
+    )
+
+
+def apply_correction(
+    band: ma.MaskedArray,
+    correction: np.ndarray,
+    log10_bands_scale: bool = False,
+    correction_weight: float = 1.0,
+    nodata: NodataVal = 0,
+) -> ma.MaskedArray:
+    """
+    Apply BRDF parameter to band.
+
+    If target nodata value is 0, then the corrected band values that would become 0 are
+    set to 1.
+
+    Parameters
+    ----------
+    band : numpy.ma.MaskedArray
+    brdf_param : numpy.ma.MaskedArray
+    nodata : nodata value used to mask output
+
+    Returns
+    -------
+    BRDF corrected band : numpy.ma.MaskedArray
+    """
+    if isinstance(band, ma.MaskedArray) and band.mask.all():  # pragma: no cover
+        return band
+    else:
+        mask = (
+            band.mask
+            if isinstance(band, ma.MaskedArray)
+            else np.where(band == nodata, True, False)
+        )
+
+        if correction_weight != 1.0:
+            logger.debug("apply weight to correction")
+            # a correction_weight value of >1 should increase the correction, whereas a
+            # value <1 should decrease the correction
+            correction = 1 - (1 - correction) * correction_weight
+
+        if log10_bands_scale:
+            # # Apply BRDF correction to log10 scaled Sentinel-2 data
+            corrected = (
+                np.log10(band.astype(np.float32, copy=False), where=band > 0)
+                * correction
+            ).astype(np.float32, copy=False)
+            # Revert the log to linear
+            corrected = (np.power(10, corrected)).astype(np.float32, copy=False)
+        else:
+            corrected = (band.astype(np.float32, copy=False) * correction).astype(
+                band.dtype, copy=False
+            )
+
+        if nodata == 0:
+            return ma.masked_array(
+                data=np.where(
+                    mask,
+                    0,
+                    np.clip(corrected, 1, np.iinfo(band.dtype).max).astype(
+                        band.dtype, copy=False
+                    ),
+                ),
+                mask=mask,
+            )
+        else:  # pragma: no cover
+            return ma.masked_array(
+                data=corrected.astype(band.dtype, copy=False), mask=mask
+            )

mapchete_eo/platforms/sentinel2/brdf/hls.py

@@ -0,0 +1,251 @@
+"""
+Legacy implementation from before 2024.
+"""
+
+from __future__ import annotations
+from typing import Optional, Tuple
+
+from affine import Affine
+from mapchete.io.raster import ReferencedRaster
+from mapchete.types import CRSLike
+import numpy as np
+from numpy.typing import DTypeLike
+
+from mapchete_eo.platforms.sentinel2.brdf.protocols import (
+    BRDFModelProtocol,
+)
+from mapchete_eo.platforms.sentinel2.brdf.config import L2ABandFParams, ModelParameters
+from mapchete_eo.platforms.sentinel2.brdf.sun_angle_arrays import get_sun_zenith_angles
+from mapchete_eo.platforms.sentinel2.metadata_parser.s2metadata import S2Metadata
+from mapchete_eo.platforms.sentinel2.types import L2ABand
+
+
+class HLSBaseModel:
+    """Base class for sensor and sun models."""
+
+    # Class with adapted Sentinel-2 Sentinel-Hub Normalization (Also used elsewhere)
+    # Sources:
+    # https://sci-hub.st/https://ieeexplore.ieee.org/document/8899868
+    # https://sci-hub.st/https://ieeexplore.ieee.org/document/841980
+    # https://custom-scripts.sentinel-hub.com/sentinel-2/brdf/
+    # Alt GitHub: https://github.com/maximlamare/s2-normalisation
+    sun_zenith_radian: np.ndarray
+    sun_azimuth_radian: np.ndarray
+    view_zenith_radian: np.ndarray
+    view_azimuth_radian: np.ndarray
+    f_band_params: ModelParameters
+    relative_azimuth_angle_radian: np.ndarray
+    processing_dtype: DTypeLike = np.float32
+
+    def __init__(
+        self,
+        sun_zenith_radian: np.ndarray,
+        sun_azimuth_radian: np.ndarray,
+        view_zenith_radian: np.ndarray,
+        view_azimuth_radian: np.ndarray,
+        f_band_params: ModelParameters,
+        relative_azimuth_angle_radian: Optional[np.ndarray] = None,
+        processing_dtype: DTypeLike = np.float32,
+    ):
+        self.sun_zenith_radian = sun_zenith_radian
+        self.sun_azimuth_radian = sun_azimuth_radian
+        self.view_zenith_radian = view_zenith_radian
+        self.view_azimuth_radian = view_azimuth_radian
+        self.f_band_params = f_band_params
+        self.processing_dtype = processing_dtype
+
+        # relative azimuth angle (in rad)
+        if relative_azimuth_angle_radian is None:
+            _phi = np.deg2rad(
+                np.rad2deg(sun_azimuth_radian) - np.rad2deg(view_azimuth_radian)
+            )
+            self.relative_azimuth_angle_radian = np.where(
+                _phi < 0, _phi + 2 * np.pi, _phi
+            )
+
+        else:
+            self.relative_azimuth_angle_radian = relative_azimuth_angle_radian
+
+    # Get delta
+    def delta(self):
+        return np.sqrt(
+            np.power(np.tan(self.sun_zenith_radian), 2)
+            + np.power(np.tan(self.view_zenith_radian), 2)
+            - 2
+            * np.tan(self.sun_zenith_radian)
+            * np.tan(self.view_zenith_radian)
+            * np.cos(self.relative_azimuth_angle_radian)
+        )
+
+    # Air Mass
+    def masse(self):
+        return 1 / np.cos(self.sun_zenith_radian) + 1 / np.cos(self.view_zenith_radian)
+
+    # Get xsi
+    def cos_xsi(self):
+        return np.cos(self.sun_zenith_radian) * np.cos(
+            self.view_zenith_radian
+        ) + np.sin(self.sun_zenith_radian) * np.sin(self.view_zenith_radian) * np.cos(
+            self.relative_azimuth_angle_radian
+        )
+
+    def sin_xsi(self):
+        return np.sqrt(1 - np.power(self.cos_xsi(), 2))
+
+    def xsi(self):
+        xsi = np.arccos(self.cos_xsi())
+        return xsi
+
+    # Function t
+    def cos_t(self):
+        trig = (
+            np.tan(self.sun_zenith_radian)
+            * np.tan(self.view_zenith_radian)
+            * np.sin(self.relative_azimuth_angle_radian)
+        )
+        # Coeficient for "t" any natural number is good, 1 or 2 are used
+        coef = 1
+        cos_t = (
+            coef / self.masse() * np.sqrt(np.power(self.delta(), 2) + np.power(trig, 2))
+        )
+        return np.clip(cos_t, -1, 1)
+
+    def sin_t(self):
+        return np.sqrt(1 - np.power(self.cos_t(), 2))
+
+    def t(self):
+        return np.arccos(self.cos_t())
+
+    def sec(self, x: np.ndarray) -> np.ndarray:
+        return 1 / np.cos(x)
+
+    # Function FV Ross_Thick, V is for volume scattering (Kernel)
+    def f_vol(self):
+        return (self.masse() / np.pi) * (
+            (self.t() - self.sin_t() * self.cos_t() - np.pi)
+            + (
+                (1 + self.cos_xsi())
+                / (2 * np.cos(self.sun_zenith_radian) * np.cos(self.view_zenith_radian))
+            )
+        )
+
+    #  Function FR Li-Sparse, R is for roughness (surface roughness)
+    def f_roughness(self):
+        # HLS formula
+        # https://userpages.umbc.edu/~martins/PHYS650/maignan%20brdf.pdf
+        a = 1 / (np.cos(self.sun_zenith_radian) + np.cos(self.view_zenith_radian))
+        return 4 / (3 * np.pi) * a * (
+            (np.pi / 2 - self.xsi()) * self.cos_xsi() + self.sin_xsi()
+        ) - (1 / 3)
+
+    def calculate_array(self) -> np.ndarray:
+        return (
+            self.f_band_params.f_iso
+            + self.f_band_params.f_geo * self.f_roughness()
+            + self.f_band_params.f_vol * self.f_vol()
+        )
+
+
+class HLS(BRDFModelProtocol):
+    """Directional model."""
+
+    sun_zenith: np.ndarray
+    sun_azimuth: np.ndarray
+    view_zenith: np.ndarray
+    view_azimuth: np.ndarray
+    f_band_params: ModelParameters
+    processing_dtype: DTypeLike = np.float32
+    transform: Affine
+    crs: CRSLike
+
+    def __init__(
+        self,
+        s2_metadata: S2Metadata,
+        band: L2ABand,
+        detector_id: Optional[int] = None,
+        processing_dtype: DTypeLike = np.float32,
+    ):
+        self.sun_zenith = s2_metadata.sun_angles.zenith.raster.data
+        self.sun_azimuth = s2_metadata.sun_angles.azimuth.raster.data
+        self.view_zenith, self.view_azimuth = _get_viewing_angles(
+            s2_metadata=s2_metadata, band=band, detector_id=detector_id
+        )
+        self.f_band_params = L2ABandFParams[band.name].value
+        self.processing_dtype = processing_dtype
+        self.sun_zenith_angles_radian = get_sun_zenith_angles(s2_metadata)
+        self.transform = s2_metadata.sun_angles.zenith.raster.transform
+        self.crs = s2_metadata.crs
+
+    def sensor_model(self) -> HLSBaseModel:
+        return HLSBaseModel(
+            sun_zenith_radian=np.deg2rad(self.sun_zenith),
+            sun_azimuth_radian=np.deg2rad(self.sun_azimuth),
+            view_zenith_radian=np.deg2rad(self.view_zenith),
+            view_azimuth_radian=np.deg2rad(self.view_azimuth),
+            f_band_params=self.f_band_params,
+            processing_dtype=self.processing_dtype,
+        )
+
+    def sun_model(self) -> HLSBaseModel:
+        # like sensor model, but:
+        # sun_zenith_radian = calculated sun zenith angles
+        # view_zenith_radian = np.zeros(self.sun_zenith_radian.shape)
+        # phi = np.zeros(self.sun_zenith_radian.shape)
+        return HLSBaseModel(
+            sun_zenith_radian=self.sun_zenith_angles_radian,
+            sun_azimuth_radian=np.deg2rad(self.sun_azimuth),
+            view_zenith_radian=np.zeros(self.sun_zenith_angles_radian.shape),
+            view_azimuth_radian=np.deg2rad(self.view_azimuth),
+            relative_azimuth_angle_radian=np.zeros(self.sun_zenith_angles_radian.shape),
+            f_band_params=self.f_band_params,
+            processing_dtype=self.processing_dtype,
+        )
+
+    def calculate(self) -> ReferencedRaster:
+        return ReferencedRaster.from_array_like(
+            array_like=(
+                self.sun_model().calculate_array()
+                / self.sensor_model().calculate_array()
+            ),
+            transform=self.transform,
+            crs=self.crs,
+        )
+
+    @staticmethod
+    def from_s2metadata(
+        s2_metadata: S2Metadata,
+        band: L2ABand,
+        detector_id: Optional[int] = None,
+        processing_dtype: DTypeLike = np.float32,
+    ) -> HLS:
+        return HLS(
+            s2_metadata=s2_metadata,
+            band=band,
+            detector_id=detector_id,
+            processing_dtype=processing_dtype,
+        )
+
+
+def _get_viewing_angles(
+    s2_metadata: S2Metadata, band: L2ABand, detector_id: Optional[int] = None
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Get viewing angles for single detector or for all detectors."""
+    if detector_id is not None:
+        view_zenith = (
+            s2_metadata.viewing_incidence_angles(band)
+            .zenith.detectors[detector_id]
+            .data
+        )
+        view_azimuth = (
+            s2_metadata.viewing_incidence_angles(band)
+            .azimuth.detectors[detector_id]
+            .data
+        )
+    else:
+        view_zenith = (
+            s2_metadata.viewing_incidence_angles(band).zenith.merge_detectors().data
+        )
+        view_azimuth = (
+            s2_metadata.viewing_incidence_angles(band).azimuth.merge_detectors().data
+        )
+    return (view_zenith, view_azimuth)

mapchete_eo/platforms/sentinel2/brdf/models.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+import numpy as np
+from numpy.typing import DTypeLike
+
+from mapchete_eo.platforms.sentinel2.brdf.protocols import BRDFModelProtocol
+from mapchete_eo.platforms.sentinel2.brdf.config import BRDFModels
+from mapchete_eo.platforms.sentinel2.brdf.hls import HLS
+from mapchete_eo.platforms.sentinel2.brdf.ross_thick import RossThick
+
+# from mapchete_eo.platforms.sentinel2.brdf.hls2 import HLS2
+from mapchete_eo.platforms.sentinel2.metadata_parser.s2metadata import S2Metadata
+from mapchete_eo.platforms.sentinel2.types import L2ABand
+
+logger = logging.getLogger(__name__)
+
+
+def get_model(
+    model: BRDFModels,
+    s2_metadata: S2Metadata,
+    band: L2ABand,
+    detector_id: Optional[int] = None,
+    processing_dtype: DTypeLike = np.float32,
+) -> BRDFModelProtocol:
+    match model:
+        case BRDFModels.HLS:
+            return HLS.from_s2metadata(
+                s2_metadata=s2_metadata,
+                band=band,
+                detector_id=detector_id,
+                processing_dtype=processing_dtype,
+            )
+        case BRDFModels.RossThick:
+            return RossThick.from_s2metadata(
+                s2_metadata=s2_metadata,
+                band=band,
+                detector_id=detector_id,
+                processing_dtype=processing_dtype,
+            )
+        case _:
+            raise KeyError(f"unkown or not implemented model: {model}")

mapchete_eo/platforms/sentinel2/brdf/protocols.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+from typing import Optional, Protocol
+
+from mapchete.io.raster import ReferencedRaster
+
+import numpy as np
+from numpy.typing import DTypeLike
+
+from mapchete_eo.platforms.sentinel2.metadata_parser.s2metadata import S2Metadata
+from mapchete_eo.platforms.sentinel2.types import L2ABand
+
+
+class BRDFModelProtocol(Protocol):
+    """Defines base interface to all kind of models.
+
+    Can be sensor models, sun models or directional models!
+    """
+
+    def calculate(self) -> ReferencedRaster: ...
+
+    @staticmethod
+    def from_s2metadata(
+        s2_metadata: S2Metadata,
+        band: L2ABand,
+        detector_id: Optional[int] = None,
+        processing_dtype: DTypeLike = np.float32,
+    ) -> BRDFModelProtocol: ...