mapchete-eo 2025.7.0__py2.py3-none-any.whl

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 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: ...

mapchete_eo/platforms/sentinel2/brdf/ross_thick.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import DTypeLike
+
+from typing import Optional
+
+from affine import Affine
+from mapchete.io.raster import ReferencedRaster
+from mapchete.types import CRSLike
+
+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.hls import _get_viewing_angles
+from mapchete_eo.platforms.sentinel2.metadata_parser import S2Metadata
+from mapchete_eo.platforms.sentinel2.types import L2ABand
+
+
+class RossThick(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_radian = np.deg2rad(self.sun_zenith)
+        self.sun_azimuth_radian = np.deg2rad(self.sun_azimuth)
+        self.view_zenith_radian = np.deg2rad(self.view_zenith)
+        self.view_azimuth_radian = np.deg2rad(self.view_azimuth)
+
+        self.relative_azimuth_angle_radian = np.abs(
+            self.view_azimuth_radian - self.sun_azimuth_radian
+        )
+
+        self.transform = s2_metadata.sun_angles.zenith.raster.transform
+        self.crs = s2_metadata.crs
+
+    def calculate(self) -> ReferencedRaster:
+        """
+        Ross-Thick BRDF model function that computes the C factor.
+
+        Parameters:
+        - f_iso, f_vol, f_geo: BRDF model parameters to fit.
+        - sza: Solar Zenith Angle (in degrees).
+        - vza: View Zenith Angle (in degrees).
+        - raa: Relative Azimuth Angle (in degrees).
+        - normalize: Normalize by nadir sensor with sun angles.
+
+        Returns:
+        - C factor according to the Ross-Thick BRDF model.
+        """
+        sza = self.sun_zenith_radian
+        vza = self.view_zenith_radian
+        raa = self.relative_azimuth_angle_radian
+
+        f_iso = self.f_band_params.f_iso
+        f_vol = self.f_band_params.f_vol
+        f_geo = self.f_band_params.f_geo
+
+        # Scale vza for fitting
+        vza = vza / (np.pi / 2)
+
+        def compute_kernels(vza, sza, raa):
+            # Cosine of view and solar zenith angles
+            cos_vza = np.cos(vza)
+            cos_sza = np.cos(sza)
+
+            # Phase angle (theta)
+            cos_theta = cos_vza * cos_sza + np.sin(vza) * np.sin(sza) * np.cos(raa)
+            theta = np.arccos(np.clip(cos_theta, -1.0, 1.0))
+
+            # Ross-Thick Kernel (K_vol)
+            K_vol = ((np.pi - theta) * cos_theta + np.sin(theta)) / (
+                cos_vza + cos_sza
+            ) - np.pi / 4
+
+            # Li-Sparse Kernel (K_geo)
+            tan_vza = np.tan(vza)
+            tan_sza = np.tan(sza)
+            D = np.sqrt(tan_vza**2 + tan_sza**2 - 2 * tan_vza * tan_sza * np.cos(raa))
+            cos_phase = np.clip((2 * D / (D + tan_vza + tan_sza)), -1.0, 1.0)
+            K_geo = (1 / np.pi) * (D - cos_phase * (tan_vza + tan_sza)) + np.arctan(D)
+
+            return K_vol, K_geo
+
+        # Calculate kernels for actual angles
+        K_vol, K_geo = compute_kernels(vza, sza, raa)
+        C_actual = f_iso + f_vol * K_vol + f_geo * K_geo
+
+        # Calculate kernels for nadir (0° view, 0° relative azimuth)
+        K_vol_nadir, K_geo_nadir = compute_kernels(0, sza, 0)
+        C_nadir = f_iso + f_vol * K_vol_nadir + f_geo * K_geo_nadir
+
+        # Normalize  and return c-factors
+        return ReferencedRaster.from_array_like(
+            array_like=(C_nadir / C_actual),
+            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,
+    ) -> RossThick:
+        return RossThick(
+            s2_metadata=s2_metadata,
+            band=band,
+            detector_id=detector_id,
+            processing_dtype=processing_dtype,
+        )

mapchete_eo/platforms/sentinel2/brdf/sun_angle_arrays.py

@@ -0,0 +1,76 @@
+from typing import Tuple
+
+from fiona.transform import transform
+import numpy as np
+
+from mapchete_eo.platforms.sentinel2.metadata_parser import S2Metadata
+
+
+def get_sun_zenith_angles(s2_metadata: S2Metadata) -> np.ndarray:
+    _, (bottom, top) = transform(
+        s2_metadata.crs,
+        "EPSG:4326",
+        [s2_metadata.bounds[0], s2_metadata.bounds[2]],
+        [s2_metadata.bounds[1], s2_metadata.bounds[3]],
+    )
+    return get_sun_angle_array(
+        min_lat=bottom,
+        max_lat=top,
+        shape=s2_metadata.sun_angles.zenith.raster.data.shape,
+    )
+
+
+def get_sun_angle_array(
+    min_lat: float, max_lat: float, shape: Tuple[int, int]
+) -> np.ndarray:
+    """
+    Calculate array of sun angles between latitudes.
+
+    Returns
+    =======
+    sun angle array in radians : np.ndarray
+    """
+
+    def _sun_angle(lat):
+        """
+        Calculate the constant sun zenith angle via 6th polynomial function see HLS.
+
+        See page 13 of:
+        https://hls.gsfc.nasa.gov/wp-content/uploads/2019/01/HLS.v1.4.UserGuide_draft_ver3.1.pdf
+        """
+        # constants used for sun angle calculation
+        # See page 13 of:
+        # https://hls.gsfc.nasa.gov/wp-content/uploads/2019/01/HLS.v1.4.UserGuide_draft_ver3.1.pdf
+        k0 = 31
+        k1 = -0.127
+        k2 = 0.0119
+        k3 = 2.4e-05
+        k4 = -9.48e-07
+        k5 = -1.95e-09
+        k6 = 6.15e-11
+
+        # Constant sun zenith angle 6th polynomial function
+        return (
+            k0
+            + k1 * lat
+            + k2 * (lat**2)
+            + k4 * (lat**4)
+            + k3 * (lat**3)
+            + k5 * (lat**5)
+            + k6 * (lat**6)
+        )
+
+    # return get_constant_sun_angle(min_lat, max_lat)
+    height, width = shape
+    cell_size = (max_lat - min_lat) / (height + 1)
+
+    # move by half a pixel so pixel centers are represented
+    top = max_lat - cell_size / 2
+
+    # generate one column of angles
+    angles = [_sun_angle(top - i * cell_size) for i in range(width)]
+
+    # expand column to output shape width
+    return np.radians(
+        np.array([[i for _ in range(width)] for i in angles], dtype=np.float32)
+    )

mapchete_eo/platforms/sentinel2/config.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from typing import List, Optional, Union
+
+from mapchete.path import MPathLike
+from pydantic import (
+    BaseModel,
+    ValidationError,
+    field_validator,
+)
+
+from mapchete_eo.base import BaseDriverConfig
+from mapchete_eo.io.path import ProductPathGenerationMethod
+from mapchete_eo.platforms.sentinel2.archives import ArchiveClsFromString, AWSL2ACOGv1
+from mapchete_eo.platforms.sentinel2.brdf.config import BRDFModels
+from mapchete_eo.platforms.sentinel2.types import (
+    CloudType,
+    ProductQIMaskResolution,
+    Resolution,
+    SceneClassification,
+)
+from mapchete_eo.search.config import StacSearchConfig
+from mapchete_eo.types import TimeRange
+
+
+class BRDFModelConfig(BaseModel):
+    model: BRDFModels = BRDFModels.HLS
+    bands: List[str] = ["blue", "green", "red", "nir"]
+    resolution: Resolution = Resolution["60m"]
+    footprints_cached_read: bool = False
+    log10_bands_scale: bool = False
+    per_detector_correction: bool = False
+
+    # This correction value is applied to `fv` (kvol) and `fr` (kgeo) in the final steps of the BRDF param
+    correction_weight: float = 1.0
+
+
+class BRDFSCLClassConfig(BRDFModelConfig):
+    scl_classes: List[SceneClassification]
+
+    @field_validator("scl_classes", mode="before")
+    @classmethod
+    def to_scl_classes(cls, values: List[str]) -> List[SceneClassification]:
+        out = []
+        for value in values:
+            if isinstance(value, SceneClassification):
+                out.append(value)
+            elif isinstance(value, str):
+                out.append(SceneClassification[value])
+            else:
+                raise ValidationError("value must be mappable to SceneClassification")
+        return out
+
+
+class BRDFConfig(BRDFModelConfig):
+    """
+    Main BRDF configuration with optional sub-configurations for certain SCL classes.
+
+    model: BRDF model
+    bands: list of band names
+    resolution: resolution BRDF is calculated on
+    footprints_cached_read: download and read footprints from cache or not
+    correction_weight: make correction stronger (>1) or weaker (<1)
+    scl_specific_configurations: list of parameters like above plus SCL classes it
+        should be applied to
+
+    e.g.
+    BRDFConfig(
+        model="HLS",
+        bands=["red", "green", "blue"],
+        resolution="60m",
+        footprints_cached_read=True,
+        correction_weight=0.9,
+        log10_bands_scale=True,
+        scl_specific_configurations=[
+            BRDFSCLClassConfig(
+                scl_classes=["water"],
+                model="HLS",
+                bands=["red", "green", "blue"],
+                resolution="60m",
+                footprints_cached_read=True,
+                correction_weight=1.3,
+            )
+        ]
+    )
+
+    """
+
+    scl_specific_configurations: Optional[List[BRDFSCLClassConfig]] = None
+
+
+class CacheConfig(BaseModel):
+    path: MPathLike
+    product_path_generation_method: ProductPathGenerationMethod = (
+        ProductPathGenerationMethod.hash
+    )
+    intersection_percent: float = 100.0
+    assets: List[str] = []
+    assets_resolution: Resolution = Resolution.original
+    keep: bool = False
+    max_cloud_cover: float = 100.0
+    max_disk_usage: float = 90.0
+    brdf: Optional[BRDFConfig] = None
+    zoom: int = 13
+
+
+class Sentinel2DriverConfig(BaseDriverConfig):
+    format: str = "Sentinel-2"
+    time: Union[TimeRange, List[TimeRange]]
+    archive: ArchiveClsFromString = AWSL2ACOGv1
+    cat_baseurl: Optional[MPathLike] = None
+    search_index: Optional[MPathLike] = None
+    max_cloud_cover: float = 100.0
+    stac_config: StacSearchConfig = StacSearchConfig()
+    first_granule_only: bool = False
+    utm_zone: Optional[int] = None
+    with_scl: bool = False
+    brdf: Optional[BRDFConfig] = None
+    cache: Optional[CacheConfig] = None
+
+
+class MaskConfig(BaseModel):
+    # mask by footprint geometry
+    footprint: bool = True
+    # apply buffer (in meters!) to footprint
+    footprint_buffer_m: float = -500
+    # add pixel buffer to all masks
+    buffer: int = 0
+    # mask by L1C cloud types (either opaque, cirrus or all)
+    l1c_cloud_type: Optional[CloudType] = None
+    # mask using the snow/ice mask
+    snow_ice: bool = False
+    # mask using cloud probability classification
+    cloud_probability_threshold: int = 100
+    cloud_probability_resolution: ProductQIMaskResolution = ProductQIMaskResolution[
+        "60m"
+    ]
+    # mask using cloud probability classification
+    snow_probability_threshold: int = 100
+    snow_probability_resolution: ProductQIMaskResolution = ProductQIMaskResolution[
+        "60m"
+    ]
+    # mask using one or more of the SCL classes
+    scl_classes: Optional[List[SceneClassification]] = None
+    # download masks before reading
+    l1c_cloud_mask_cached_read: bool = False
+    snow_ice_mask_cached_read: bool = False
+    cloud_probability_cached_read: bool = False
+    snow_probability_cached_read: bool = False
+    scl_cached_read: bool = False
+
+    @field_validator("scl_classes", mode="before")
+    @classmethod
+    def to_scl_classes(cls, values: List[str]) -> List[SceneClassification]:
+        if values is None:
+            return
+        out = []
+        for value in values:
+            if isinstance(value, SceneClassification):
+                out.append(value)
+            elif isinstance(value, str):
+                out.append(SceneClassification[value])
+            else:
+                raise ValidationError("value must be mappable to SceneClassification")
+        return out
+
+    @staticmethod
+    def parse(config: Union[dict, MaskConfig]) -> MaskConfig:
+        """
+        Make sure all values are parsed correctly
+        """
+        if isinstance(config, MaskConfig):
+            return config
+
+        elif isinstance(config, dict):
+            return MaskConfig(**config)
+
+        else:
+            raise TypeError(
+                f"mask configuration should either be a dictionary or a MaskConfig object, not {config}"
+            )

mapchete_eo/platforms/sentinel2/driver.py

@@ -0,0 +1,78 @@
+from typing import Optional, List, Tuple
+
+from mapchete.geometry import reproject_geometry
+from mapchete.path import MPath
+from mapchete.types import NodataVal
+from rasterio.enums import Resampling
+
+from mapchete_eo import base
+from mapchete_eo.archives.base import Archive
+from mapchete_eo.platforms.sentinel2.config import Sentinel2DriverConfig
+from mapchete_eo.platforms.sentinel2.preprocessing_tasks import parse_s2_product
+from mapchete_eo.search.stac_static import STACStaticCatalog
+from mapchete_eo.settings import mapchete_eo_settings
+from mapchete_eo.types import MergeMethod
+
+METADATA: dict = {
+    "driver_name": "Sentinel-2",
+    "data_type": None,
+    "mode": "r",
+    "file_extensions": [],
+}
+
+
+class Sentinel2Cube(base.EODataCube):
+    # Sentinel-2 driver specific default values:
+    default_read_merge_method: MergeMethod = MergeMethod.average
+    default_read_merge_products_by: Optional[str] = "s2:datastrip_id"
+    default_read_nodataval: NodataVal = 0
+    default_read_resampling: Resampling = Resampling.bilinear
+
+
+Sentinel2CubeGroup = List[Tuple[str, Sentinel2Cube]]
+
+
+class InputData(base.InputData):
+    """
+    Main driver class used by mapchete.
+    """
+
+    # Sentinel-2 driver specific parameters:
+    default_preprocessing_task = staticmethod(parse_s2_product)
+    driver_config_model = Sentinel2DriverConfig
+    params: Sentinel2DriverConfig
+    input_tile_cls = Sentinel2Cube
+
+    def set_archive(self, base_dir: MPath):
+        if self.params.cat_baseurl:
+            self.archive = Archive(
+                catalog=STACStaticCatalog(
+                    baseurl=MPath(self.params.cat_baseurl).absolute_path(
+                        base_dir=base_dir
+                    ),
+                ),
+                area=self.bbox(mapchete_eo_settings.default_catalog_crs),
+                time=self.time,
+                search_kwargs=dict(max_cloud_cover=self.params.max_cloud_cover),
+            )
+        elif self.params.archive:
+            catalog_area = reproject_geometry(
+                self.area,
+                src_crs=self.crs,
+                dst_crs=mapchete_eo_settings.default_catalog_crs,
+            )
+            self.archive = self.params.archive(
+                time=self.time,
+                bounds=catalog_area.bounds,
+                area=catalog_area,
+                search_kwargs=dict(
+                    search_index=(
+                        MPath(self.params.search_index).absolute_path(base_dir=base_dir)
+                        if self.params.search_index
+                        else None
+                    ),
+                    max_cloud_cover=self.params.max_cloud_cover,
+                ),
+            )
+        else:
+            raise ValueError("either 'archive' or 'cat_baseurl' or both is required.")