mapchete-eo 2026.2.0__py3-none-any.whl

mapchete_eo/image_operations/color_correction.py

@@ -0,0 +1,136 @@
+import logging
+from typing import Tuple
+
+import cv2
+import numpy as np
+import numpy.ma as ma
+from numpy.typing import DTypeLike
+from rasterio.plot import reshape_as_image, reshape_as_raster
+
+from mapchete_eo.image_operations.sigmoidal import sigmoidal
+
+logger = logging.getLogger(__name__)
+
+
+def color_correct(
+    rgb: ma.MaskedArray,
+    gamma: float = 1.15,
+    clahe_flag: bool = True,
+    clahe_clip_limit: float = 1.25,
+    clahe_tile_grid_size: Tuple[int, int] = (32, 32),
+    sigmoidal_flag: bool = False,
+    sigmoidal_constrast: int = 0,
+    sigmoidal_bias: float = 0.0,
+    saturation: float = 3.2,
+    calculations_dtype: DTypeLike = np.float16,
+) -> ma.MaskedArray:
+    """
+    Return color corrected 8 bit RGB array from 8 bit input RGB.
+
+    Uses rio-color to apply correction.
+
+    Parameters
+    ----------
+    bands : ma.MaskedArray
+        Input bands as a 8bit 3D array.
+    gamma : float
+        Apply gamma in HSV color space.
+    clahe_clip_limit : float
+        Common values limit the resulting amplification to between 3 and 4.
+        See "Contrast Limited AHE" at:
+        https://en.wikipedia.org/wiki/Adaptive_histogram_equalization.
+    saturation : float
+        Controls the saturation in HSV color space.
+
+    Returns
+    -------
+    color corrected image : np.ndarray
+    """
+    if isinstance(calculations_dtype, str):
+        calculations_dtype = np.dtype(getattr(np, calculations_dtype))
+    if not isinstance(calculations_dtype, np.dtype):
+        raise TypeError(
+            f"Harmonization dtype needs to be valid numpy dtype is: {type(calculations_dtype)}"
+        )
+
+    if rgb.dtype != "uint8":
+        raise TypeError("rgb must be of dtype np.uint8")
+
+    # get and keep original mask
+    rgb_src_mask = rgb.mask
+    rgb_src_fill_value = rgb.fill_value
+
+    # Move bands to the last axis
+    # rgb = np.swapaxes(rgb, 0, 2).astype(np.uint8, copy=False)
+    rgb_image = reshape_as_image(rgb)
+
+    # Saturation from OpenVC
+    if saturation != 1.0:
+        imghsv = cv2.cvtColor(rgb_image, cv2.COLOR_RGB2HSV).astype(
+            calculations_dtype, copy=False
+        )
+        (h, s, v) = cv2.split(imghsv)
+        # add all new HSV values into output
+        imghsv = cv2.merge([h, np.clip(s * saturation, 1, 255), v]).astype(
+            np.uint8, copy=False
+        )
+        rgb_image = np.clip(
+            cv2.cvtColor(imghsv, cv2.COLOR_HSV2RGB),
+            1,
+            255,  # clip valid values to 1 and 255 to avoid accidental nodata values
+        ).astype(np.uint8, copy=False)
+
+    # Sigmodial Contrast and Bias from rio-color
+    # Swap bands from last axis to the first one as we are acusstomed to
+    # For the sigmodial contrast
+    if sigmoidal_flag is True:
+        rgb_image = np.clip(
+            (
+                sigmoidal(
+                    np.clip(
+                        rgb_image.astype(calculations_dtype, copy=False) / 255,
+                        0,
+                        1,
+                    ).astype(calculations_dtype, copy=False),
+                    contrast=sigmoidal_constrast,
+                    bias=sigmoidal_bias,
+                    out_dtype=calculations_dtype,
+                ).astype(calculations_dtype, copy=False)
+                * 255
+            ),
+            1,
+            255,
+        ).astype(np.uint8, copy=False)
+
+    # Gamma from rio-color
+    if gamma != 1.0:
+        rgb_image = np.clip(
+            ((rgb_image.astype(calculations_dtype) / 255) ** (1.0 / gamma)) * 255,
+            1,
+            255,
+        ).astype(np.uint8, copy=False)
+
+    # CLAHE from OpenVC
+    # Some CLAHE info: https://imagej.net/plugins/clahe
+    if clahe_flag is True:
+        lab = cv2.cvtColor(
+            rgb_image.astype(np.uint8, copy=False), cv2.COLOR_RGB2LAB
+        ).astype(np.uint8, copy=False)
+        lab_planes = list(cv2.split(lab))
+        clahe = cv2.createCLAHE(
+            clipLimit=clahe_clip_limit, tileGridSize=clahe_tile_grid_size
+        )
+        lab_planes[0] = clahe.apply(lab_planes[0])
+        lab = cv2.merge(lab_planes)
+        rgb_image = np.clip(
+            cv2.cvtColor(lab, cv2.COLOR_LAB2RGB),
+            1,
+            255,  # clip valid values to 1 and 255 to avoid accidental nodata values
+        ).astype(np.uint8, copy=False)
+
+    # Return array with original mask
+    return ma.masked_array(
+        data=reshape_as_raster(rgb_image),
+        mask=rgb_src_mask,
+        fill_value=rgb_src_fill_value,
+    )

mapchete_eo/image_operations/compositing.py

@@ -0,0 +1,266 @@
+import logging
+from enum import Enum
+from typing import Callable, Optional
+
+import cv2
+import numpy as np
+import numpy.ma as ma
+from mapchete import Timer
+from rasterio.plot import reshape_as_image, reshape_as_raster
+
+from mapchete_eo.image_operations import blend_functions
+
+
+logger = logging.getLogger(__name__)
+
+
+def to_rgba(arr: np.ndarray) -> np.ndarray:
+    def _expanded_mask(arr: ma.MaskedArray) -> np.ndarray:
+        if isinstance(arr.mask, np.bool_):
+            return np.full(arr.shape, fill_value=arr.mask, dtype=bool)
+        else:
+            return arr.mask
+
+    # make sure array is a proper MaskedArray with expanded mask
+    if not isinstance(arr, ma.MaskedArray):
+        arr = ma.masked_array(arr, mask=np.zeros(arr.shape, dtype=bool))
+    if arr.dtype != np.uint8:
+        raise TypeError(f"image array must be of type uint8, not {str(arr.dtype)}")
+    num_bands = arr.shape[0]
+    if num_bands == 1:
+        alpha = np.where(~_expanded_mask(arr[0]), 255, 0).astype(np.uint8, copy=False)
+        out = np.stack([arr[0], arr[0], arr[0], alpha]).data
+    elif num_bands == 2:
+        out = np.stack([arr[0], arr[0], arr[0], arr[1]]).data
+    elif num_bands == 3:
+        alpha = np.where(
+            (
+                ~_expanded_mask(arr[0])
+                & ~_expanded_mask(arr[1])
+                & ~_expanded_mask(arr[2])
+            ),
+            255,
+            0,
+        ).astype(np.uint8, copy=False)
+        out = np.stack([arr[0], arr[1], arr[2], alpha]).data
+    elif num_bands == 4:
+        out = arr.data
+    else:  # pragma: no cover
+        raise TypeError(
+            f"array must have between one and four bands but has {num_bands}"
+        )
+    return np.array(out, dtype=np.float16)
+
+
+def _blend_base(
+    bg: np.ndarray, fg: np.ndarray, opacity: float, operation: Callable
+) -> ma.MaskedArray:
+    # generate RGBA output and run compositing and normalize by dividing by 255
+    out_arr = reshape_as_raster(
+        (
+            operation(
+                reshape_as_image(to_rgba(bg) / 255),
+                reshape_as_image(to_rgba(fg) / 255),
+                opacity,
+            )
+            * 255
+        ).astype(np.uint8, copy=False)
+    )
+    # generate mask from alpha band
+    out_mask = np.where(out_arr[3] == 0, True, False)
+    return ma.masked_array(out_arr, mask=np.stack([out_mask for _ in range(4)]))
+
+
+def normal(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.normal)
+
+
+def soft_light(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.soft_light)
+
+
+def lighten_only(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.lighten_only)
+
+
+def screen(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.screen)
+
+
+def dodge(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.dodge)
+
+
+def addition(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.addition)
+
+
+def darken_only(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.darken_only)
+
+
+def multiply(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.multiply)
+
+
+def hard_light(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.hard_light)
+
+
+def difference(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.difference)
+
+
+def subtract(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.subtract)
+
+
+def grain_extract(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.grain_extract)
+
+
+def grain_merge(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.grain_merge)
+
+
+def divide(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.divide)
+
+
+def overlay(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
+    return _blend_base(bg, fg, opacity, blend_functions.overlay)
+
+
+METHODS = {
+    "multiply": multiply,
+    "normal": normal,
+    "soft_light": soft_light,
+    "lighten_only": lighten_only,
+    "screen": screen,
+    "dodge": dodge,
+    "addition": addition,
+    "darken_only": darken_only,
+    "hard_light": hard_light,
+    "difference": difference,
+    "subtract": subtract,
+    "grain_extract": grain_extract,
+    "grain_merge": grain_merge,
+    "divide": divide,
+    "overlay": overlay,
+}
+
+
+def composite(
+    method: str, bg: np.ndarray, fg: np.ndarray, opacity: float = 1
+) -> ma.MaskedArray:
+    """
+    Composite two image arrays using a named blending method.
+
+    Args:
+        method: Blending method name (e.g., 'multiply', 'screen').
+        bg: Background image array (channels-first).
+        fg: Foreground image array (channels-first).
+        opacity: Opacity of the foreground layer (0-1).
+
+    Returns:
+        ma.MaskedArray: Blended RGBA result.
+    """
+    return METHODS[method](bg, fg, opacity)
+
+
+def fuzzy_mask(
+    arr: np.ndarray,
+    fill_value: float,
+    radius: int = 0,
+    invert: bool = True,
+    dilate: bool = True,
+) -> np.ndarray:
+    """Create fuzzy mask from binary mask."""
+    if arr.ndim == 2:
+        arr = np.expand_dims(arr, 0)
+    if arr.ndim != 3:
+        raise TypeError("array must have exactly three dimensions")
+    if arr.shape[0] == 1:
+        three_bands = np.stack([arr[0] for _ in range(3)])
+    elif arr.shape[0] == 3:
+        three_bands = arr
+    else:
+        raise TypeError(
+            f"array must have either one or three bands, not {arr.shape[0]}"
+        )
+    if invert:
+        three_bands = ~three_bands
+    # convert mask into an image and set true values to fill value
+    # dilate = buffer image using the blur radius
+    out = np.multiply(reshape_as_image(three_bands), fill_value, dtype=np.uint8)
+    if dilate and radius:
+        with Timer() as t:
+            kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (radius, radius))
+        logger.debug("dilation kernel generated in %s", t)
+        with Timer() as t:
+            out = cv2.morphologyEx(out, cv2.MORPH_DILATE, kernel)
+        logger.debug("dilation took %s", t)
+    # blur and return
+    if radius:
+        with Timer() as t:
+            out = reshape_as_raster(cv2.blur(out, (radius, radius)))[0]
+        logger.debug("blur filter took %s", t)
+    else:
+        out = reshape_as_raster(out)[0]
+    if invert:
+        return -(out - fill_value).astype(np.uint8)
+    return out
+
+
+class GradientPosition(Enum):
+    inside = "inside"
+    outside = "outside"
+    edge = "edge"
+
+
+def fuzzy_alpha_mask(
+    arr: np.ndarray,
+    mask: Optional[np.ndarray] = None,
+    radius=0,
+    fill_value=255,
+    gradient_position=GradientPosition.outside,
+) -> np.ndarray:
+    """Return an RGBA array with a fuzzy alpha mask."""
+    try:
+        gradient_position = (
+            GradientPosition[gradient_position]
+            if isinstance(gradient_position, str)
+            else gradient_position
+        )
+    except KeyError:
+        raise ValueError(f"unknown gradient_position: {gradient_position}")
+
+    if arr.shape[0] != 3:
+        raise TypeError("input array must have exactly three bands")
+
+    if mask is None:
+        if not isinstance(arr, ma.MaskedArray):
+            raise TypeError(
+                "input array must be a numpy MaskedArray or mask must be provided"
+            )
+        mask = arr.mask
+
+    if gradient_position == GradientPosition.outside:
+        fuzzy = fuzzy_mask(
+            mask, fill_value=fill_value, radius=radius, invert=False, dilate=True
+        )
+
+    elif gradient_position == GradientPosition.inside:
+        fuzzy = fuzzy_mask(
+            mask, fill_value=fill_value, radius=radius, invert=True, dilate=True
+        )
+
+    elif gradient_position == GradientPosition.edge:
+        fuzzy = fuzzy_mask(mask, fill_value=fill_value, radius=radius, dilate=False)
+
+    else:  # pragma: no cover
+        raise ValueError(f"unknown gradient_position: {gradient_position}")
+
+    # doing this makes sure that originally masked pixels are also fully masked
+    # fuzzy[mask[0]] = 255
+    return np.concatenate((arr, np.expand_dims(fuzzy, 0)), axis=0)

mapchete_eo/image_operations/dtype_scale.py

@@ -0,0 +1,43 @@
+from typing import Optional
+
+import numpy as np
+import numpy.ma as ma
+from mapchete.types import NodataVal
+from numpy.typing import DTypeLike
+
+
+def dtype_scale(
+    bands: ma.MaskedArray,
+    nodata: Optional[NodataVal] = None,
+    out_dtype: Optional[DTypeLike] = np.uint8,
+    max_source_value: float = 10000.0,
+    max_output_value: Optional[float] = None,
+) -> ma.MaskedArray:
+    """
+    (1) normalize array from range [0:max_value] to range [0:1]
+    (2) multiply with out_values to create range [0:out_values]
+    (3) clip to [1:out_values] to avoid rounding errors where band value can
+    accidentally become nodata (0)
+    (4) create masked array with burnt in nodata values and original nodata mask
+    """
+    out_dtype = np.dtype(out_dtype)
+
+    if max_output_value is None:
+        max_output_value = np.iinfo(out_dtype).max
+
+    if nodata is None:
+        nodata = 0
+
+    return ma.masked_where(
+        bands == nodata,
+        np.where(
+            bands.mask,
+            nodata,
+            np.clip(
+                (bands.astype("float16", copy=False) / max_source_value)
+                * max_output_value,
+                1,
+                max_output_value,
+            ),
+        ),
+    ).astype(out_dtype, copy=False)

mapchete_eo/image_operations/fillnodata.py

@@ -0,0 +1,130 @@
+import logging
+from enum import Enum
+
+import numpy as np
+import numpy.ma as ma
+from mapchete import Timer
+from rasterio.features import rasterize, shapes
+from rasterio.fill import fillnodata as rio_fillnodata
+from scipy.ndimage import convolve
+from shapely.geometry import shape
+
+logger = logging.getLogger(__name__)
+
+
+class FillSelectionMethod(str, Enum):
+    all = "all"
+    patch_size = "patch_size"
+    nodata_neighbors = "nodata_neighbors"
+
+
+def fillnodata(
+    bands: ma.MaskedArray,
+    method: FillSelectionMethod = FillSelectionMethod.patch_size,
+    max_patch_size: int = 2,
+    max_nodata_neighbors: int = 0,
+    max_search_distance: float = 10,
+    smoothing_iterations: int = 0,
+) -> ma.MaskedArray:
+    """
+    Interpolate nodata areas up to a given size.
+
+    This function uses the nodata mask to determine contingent nodata areas. Patches
+    up to a certain size are then interpolated using rasterio.fill.fillnodata.
+
+    Parameters
+    ----------
+    bands : ma.MaskedArray
+        Input bands as a 3D array.
+    method : str
+        Method how to select areas to interpolate. (default: patch_size)
+            - all: interpolate all nodata areas
+            - patch_size: only interpolate areas up to a certain size. (defined by
+                max_patch_size)
+            - nodata_neighbors: only interpolate single nodata pixel.
+    max_patch_size : int
+        Maximum patch size in pixels which is going to be interpolated in "patch_size"
+        method.
+    max_nodata_neighbors : int
+        Maximum number of nodata neighbor pixels in "nodata_neighbors" method.
+    max_search_distance : float
+        The maxmimum number of pixels to search in all directions to find values to
+        interpolate from.
+    smoothing_iterations : int
+        The number of 3x3 smoothing filter passes to run.
+
+    Returns
+    -------
+    filled bands : ma.MaskedArray
+    """
+    if not isinstance(bands, ma.MaskedArray):  # pragma: no cover
+        raise TypeError("bands must be a ma.MaskedArray")
+
+    def _interpolate(bands, max_search_distance, smoothing_iterations):
+        return np.stack(
+            [
+                rio_fillnodata(
+                    band.data,
+                    mask=~band.mask,
+                    max_search_distance=max_search_distance,
+                    smoothing_iterations=smoothing_iterations,
+                )
+                for band in bands
+            ]
+        )
+
+    if bands.mask.any():
+        if method == FillSelectionMethod.all:
+            logger.debug("interpolate pixel values in all nodata areas")
+            return ma.masked_array(
+                data=_interpolate(bands, max_search_distance, smoothing_iterations),
+                mask=np.zeros(bands.shape),
+            )
+
+        elif method == FillSelectionMethod.patch_size:
+            logger.debug(
+                "interpolate pixel values in nodata areas smaller than or equal %s pixel",
+                max_patch_size,
+            )
+            with Timer() as t:
+                patches = [
+                    (p, v)
+                    for p, v in shapes(bands.mask[0].astype(np.uint8))
+                    if v == 1 and shape(p).area <= (max_patch_size)
+                ]
+            logger.debug("found %s small nodata patches in %s", len(patches), t)
+            if patches:
+                interpolation_mask = rasterize(
+                    patches,
+                    out_shape=bands[0].data.shape,
+                ).astype(bool)
+                # create masked aray using original mask with removed small patches
+                return ma.masked_array(
+                    data=_interpolate(bands, max_search_distance, smoothing_iterations),
+                    mask=bands.mask ^ np.stack([interpolation_mask for _ in bands]),
+                )
+
+        elif method == FillSelectionMethod.nodata_neighbors:
+            kernel = np.array(
+                [
+                    [0, 1, 0],
+                    [1, 0, 1],
+                    [0, 1, 0],
+                ]
+            )
+            # count occurances of masked neighbor pixels
+            number_mask = bands[0].mask.astype(np.uint8)
+            count_mask = convolve(number_mask, kernel)
+            # use interpolation on nodata values where there are no neighbor pixels
+            interpolation_mask = (count_mask <= max_nodata_neighbors) & bands[0].mask
+            # create masked aray using original mask with removed small patches
+            return ma.masked_array(
+                data=_interpolate(bands, max_search_distance, smoothing_iterations),
+                mask=bands.mask ^ np.stack([interpolation_mask for _ in bands]),
+            )
+
+        else:  # pragma: no cover
+            raise ValueError(f"unknown method: {method}")
+
+    # if nothing was masked or no small patches could be found, return original data
+    return bands