dpolcat 0.2.0.dev1__py3-none-any.whl

dpolcat/__init__.py

@@ -0,0 +1,2 @@
+from .core import *  # noqa: I001
+from . import utils, processor, modelling  # noqa: F401

dpolcat/core.py

@@ -0,0 +1,144 @@
+"""
+dpolcat/core - polarimetric categorization of dual-pol. synthetic aperture radar (SAR) data
+
+Author: Luke McQuade
+"""
+
+from numba import njit
+import numpy as np
+import xarray
+
+
+def linear_to_db(x):
+    """Convert linear backscatter to power ratio (decibels)."""
+    return 10 * np.log10(x)
+
+
+# This used to do a different transform, keep this as a passthrough until the rest of the code is updated.
+def scale_nice(x):
+    return linear_to_db(x)
+
+
+def xr_scale_nice(x):
+    """XArray, Dask-oriented, version of scaling function."""
+    return xarray.apply_ufunc(scale_nice, x, dask="parallelized", output_dtypes=[float])
+
+
+# Remember to keep this updated.
+NUM_CATEGORIES = 20
+"""Total number of categories."""
+
+
+@njit
+def categorize(vv_scaled, vh_scaled):
+    """
+    Our dual-polarimetric categorization decision tree algorithm.
+    Inputs should be in numpy or xarray-compatible form, scaled using our custom scaling function.
+    """
+    vv = vv_scaled
+    vh = vh_scaled
+
+    i = 0
+    if vv is None or vh is None:
+        # NoData/invalid
+        i = 0
+    # Low volume scatter, ie., predominantly surface scatterers
+    elif -np.inf <= vh < -20.0:
+        if -np.inf <= vv < -18.0:
+            i = 1
+        elif -18.0 <= vv < -16.0:
+            i = 2
+        elif -16.0 <= vv < -14.0:
+            i = 3
+        elif -14.0 <= vv < -6.0:
+            i = 4
+        elif -6.0 <= vv < 2.0:
+            i = 5
+        elif vv >= 2.0:
+            # Higher values, likely to be double-bounce (buildings) or terrain effects
+            i = 13  # [merged A]
+    elif vv < -18.0:
+        if vh < -14.0:
+            # Low specular with some cross-pol, e.g., moist soil
+            i = 6
+        elif vh >= -14.0:
+            # Predominantly polarizing surfaces (unrealistic)
+            i = 19  # [merged C]
+    # Combinations of scatter, e.g, natural volume scatterers
+    elif -18.0 <= vv < -14.0 and -22.0 <= vh < -14.0:
+        i = 7
+    elif -14.0 <= vv < -2.0 and -14.0 <= vh < -10.0:
+        i = 12
+
+    # Further mid-range categories
+    elif -18.0 <= vv < -14.0 and -14.0 <= vh < -10.0:
+        i = 19  # [merged C]
+    elif -18.0 <= vv < -6.0 and -10.0 <= vh < 2.0:
+        # Maybe double-bounce
+        i = 14
+    elif -14.0 <= vv < -6.0 and -22.0 <= vh < -17.0:
+        i = 8
+    elif -14.0 <= vv < -6.0 and -17.0 <= vh < -15.6:
+        i = 9
+    elif -14.0 <= vv < -6.0 and -15.6 <= vh < -14.0:
+        i = 10
+    elif -6.0 <= vv < 2.0 and -22.0 <= vh < -14.0:
+        i = 11
+    elif -2.0 <= vv < 2.0 and -14.0 <= vh < -10.0:
+        i = 15  # [merged B] #
+
+    # Higher values, likely to be double-bounce (buildings) or terrain effects.
+    elif -6.0 <= vv < 2.0 and -10.0 <= vh < 2.0:
+        i = 15  # [merged B]
+    elif vv >= 2.0 and -22.0 <= vh < -10.0:
+        i = 13  # [merged A]
+    elif vv >= 2.0 and -10.0 <= vh < 2.0:
+        i = 16
+    elif vh >= 2.0 and -22.0 < vv < 2.0:
+        i = 17
+    elif vv >= 2.0 and vh >= 2.0:
+        i = 18
+
+    return i
+
+
+categorize_np = np.vectorize(categorize, otypes=[np.uint8])
+"""Numpy vectorized version of the categorizer."""
+
+
+def xr_categorize(vv_scaled, vh_scaled):
+    """XArray, Dask-oriented, version of the categorizer."""
+    return xarray.apply_ufunc(
+        categorize_np,
+        vv_scaled,
+        vh_scaled,
+        dask="parallelized",
+        output_dtypes=[np.uint8],
+    ).rename("dpolcat")
+
+
+color_list = np.array(
+    [
+        [0, 0, 0],  # 0
+        [129, 244, 255],  # 1
+        [199, 180, 215],  # 2
+        [166, 121, 215],  # 3
+        [255, 200, 128],  # 4
+        [203, 73, 114],  # 5
+        [222, 123, 214],  # 6
+        [251, 210, 212],  # 7
+        [231, 251, 187],  # 8
+        [200, 187, 66],  # 9
+        [157, 225, 90],  # 10
+        [114, 73, 114],  # 11
+        [105, 69, 42],  # 12
+        [200, 10, 30],  # 13
+        [255, 255, 0],  # 14
+        [255, 204, 0],  # 15
+        [158, 34, 108],  # 16
+        [217, 0, 255],  # 17
+        [252, 74, 0],  # 18
+        [70, 70, 70],  # 19
+    ]
+)
+"""Suggested category colours, of the form [R,G,B (0 to 255)]"""

dpolcat/fast_frost.py

@@ -0,0 +1,184 @@
+"""
+Fast Frost speckle filters using Numba. 
+
+frost_filter_fast does minimal numerical checking. It will break (silently) if there are *any* NaNs in the input.
+
+frost_filter_nanny is NaN-aware, but this comes with a performance penalty.
+
+Based on findpeaks.filters [0] / PyRadar [1], and the original paper [2].
+
+Mostly generated with ChatGPT o3 (17-Jun-2025).
+
+
+[0]: https://github.com/erdogant/findpeaks/blob/master/findpeaks/filters/frost.py
+
+[1]: https://github.com/PyRadar/pyradar
+
+[2]: Frost, Victor S., Josephine Abbott Stiles, K. S. Shanmugan, and Julian C. Holtzman. 'A Model for Radar Images and Its Application to Adaptive Digital Filtering of Multiplicative Noise'. IEEE Transactions on Pattern Analysis and Machine Intelligence PAMI-4, no. 2 (March 1982): 15766. https://doi.org/10.1109/TPAMI.1982.4767223.
+
+Licence: LGPL-3.0.
+
+"""
+
+import numpy as np
+from scipy.ndimage import uniform_filter
+from numba import njit, prange
+
+
+@njit(parallel=True, fastmath=True)
+def _frost_core(img, factor_A, r):
+    """Inner loop: compute weighted average for every pixel."""
+    n_rows, n_cols = img.shape
+    out = np.empty_like(img)
+
+    for i in prange(n_rows):               # parallel loop
+        for j in range(n_cols):
+            # window bounds (clamped to image)
+            x0 = max(i - r, 0);  x1 = min(i + r + 1, n_rows)
+            y0 = max(j - r, 0);  y1 = min(j + r + 1, n_cols)
+
+            centre = img[i, j]
+            A      = factor_A[i, j]
+
+            w_sum = 0.0
+            v_sum = 0.0
+            for x in range(x0, x1):
+                for y in range(y0, y1):
+                    diff = abs(img[x, y] - centre)
+                    w = np.exp(-A * diff)
+                    w_sum += w
+                    v_sum += w * img[x, y]
+
+            out[i, j] = v_sum / w_sum if w_sum > 0.0 else 0.0
+    return out
+
+
+def frost_filter_fast(img, *, damping_factor: float = 2.0,
+                 win_size: int = 3, dtype=np.float32):
+    """
+    Frost speckle filter accelerated with Numba.
+
+    Parameters
+    ----------
+    img : 2-D ndarray
+    damping_factor : float, default 2.0
+    win_size : odd int ≥ 3, default 3
+    dtype : numpy dtype, default float32
+
+    Returns
+    -------
+    ndarray  (same shape as *img*)
+    """
+    if img.ndim != 2:
+        raise ValueError("Input must be a 2-D array.")
+    if win_size < 3 or win_size % 2 == 0:
+        raise ValueError("win_size must be odd and ≥ 3.")
+
+    img = np.asarray(img, dtype=dtype, order='C')  # contiguous for Numba
+    r   = win_size // 2
+
+    # Local mean and variance via fast box filter
+    mean     = uniform_filter(img, size=win_size, mode='reflect')
+    mean_sq  = uniform_filter(img * img, size=win_size, mode='reflect')
+    var      = np.clip(mean_sq - mean * mean, 0, None)
+    std      = np.sqrt(var)
+
+    # Frost parameters
+    sigma0   = std / np.maximum(mean, 1e-12) / np.maximum(mean, 1e-12)
+    factor_A = damping_factor * sigma0
+
+    return _frost_core(img, factor_A, r).astype(img.dtype, copy=False)
+
+
+@njit(parallel=True, fastmath=True)
+def _frost_core_nanny(img, factor_A, win_size):
+    """Numba kernel: weight computation + pixel update (ignores NaNs)."""
+    n_rows, n_cols = img.shape
+    r = win_size // 2
+    out = np.empty_like(img)
+
+    for i in prange(n_rows):
+        for j in range(n_cols):
+            centre = img[i, j]
+            if np.isnan(centre):              # centre missing → output NaN
+                out[i, j] = np.nan
+                continue
+
+            x0 = max(i - r, 0)
+            x1 = min(i + r + 1, n_rows)
+            y0 = max(j - r, 0)
+            y1 = min(j + r + 1, n_cols)
+
+            A = factor_A[i, j]
+            w_sum = 0.0
+            v_sum = 0.0
+
+            for x in range(x0, x1):
+                for y in range(y0, y1):
+                    pix = img[x, y]
+                    if np.isnan(pix):          # skip NaNs in the window
+                        continue
+                    diff = abs(pix - centre)
+                    w = np.exp(-A * diff)
+                    w_sum += w
+                    v_sum += w * pix
+
+            out[i, j] = v_sum / w_sum if w_sum > 0 else np.nan
+    return out
+
+
+def frost_filter_nanny(img, *, damping_factor: float = 2.0, win_size: int = 3,
+                      dtype=np.float32):
+    """
+    Frost speckle filter accelerated with Numba (NaN-aware).
+
+    Parameters
+    ----------
+    img : 2-D ndarray
+        SAR intensity image (NaNs allowed).
+    damping_factor : float, default 2.0
+        Frost damping constant.
+    win_size : int, default 3 (must be odd ≥ 3)
+        Square window size.
+    dtype : numpy dtype, default np.float32
+        Internal working precision.
+
+    Returns
+    -------
+    filtered : ndarray
+        Frost-filtered image (same shape as *img*).
+    """
+    if img.ndim != 2:
+        raise ValueError("Input must be a 2-D array.")
+    if win_size < 3 or win_size % 2 == 0:
+        raise ValueError("win_size must be odd and ≥ 3.")
+
+    img = np.asarray(img, dtype=dtype, order='C')          # C-contiguous
+
+    # ---- local mean & variance, ignoring NaNs ---- #
+    nan_mask = np.isfinite(img).astype(dtype)              # 1 where valid, 0 where NaN
+    img_filled = np.where(nan_mask, img, 0)
+
+    # uniform_filter returns an *average* → multiply by win_size**2 to get sums
+    size = win_size
+    win_area = float(size * size)
+
+    sum_valid = uniform_filter(img_filled, size=size, mode='reflect') * win_area
+    sum_sq_valid = uniform_filter(img_filled * img_filled, size=size, mode='reflect') * win_area
+    count_valid = uniform_filter(nan_mask, size=size, mode='reflect') * win_area
+
+    # avoid division by zero where window has no valid pixels
+    mean = np.where(count_valid > 0, sum_valid / count_valid, np.nan)
+    var = np.where(count_valid > 0, sum_sq_valid / count_valid - mean * mean, np.nan)
+    std = np.sqrt(np.maximum(var, 0))
+
+    cv = std / mean                                     # coefficient of variation
+    sigma_zero = cv / mean                              # std / mean²
+    factor_A = damping_factor * sigma_zero
+    factor_A = np.where(np.isfinite(factor_A), factor_A, 0)
+
+    # ---- JIT kernel ---- #
+    filtered = _frost_core_nanny(img, factor_A.astype(dtype), win_size)
+
+    return filtered
+

dpolcat/modelling.py

@@ -0,0 +1,124 @@
+"""
+dpolcat/modelling - helper classes for semantic modelling
+
+Author: Luke McQuade
+"""
+
+from enum import IntEnum
+
+import dpolcat
+
+# Semantic API
+# ------------
+# Here we aim to present the polarimetric categories in a way
+# that they can be used to create understandable semantic models.
+
+
+class Surface(IntEnum):
+    """
+    Predominantly surface-scattering mechanics.
+    - `Smooth` (1): Very smooth surface scattering.
+    - `SlightlyRough` (2): Slightly rough surface scattering.
+    - `MediumRough` (3): Medium-rough surface scattering.
+    - `Rough` (4): Rough surface scattering.
+    - `VeryRough` (5): Very rough surface scattering.
+    """
+
+    Smooth = 1
+    """Very smooth surface scattering."""
+
+    SlightlyRough = 2
+    """Slightly rough surface scattering."""
+
+    MediumRough = 3
+    """Medium-rough surface scattering."""
+
+    Rough = 4
+    """Rough surface scattering."""
+
+    VeryRough = 5
+    """Very rough surface scattering."""
+
+
+class Volume(IntEnum):
+    """
+    Volume-scattering mechanics.
+    - `LowCo` (6): Volume scatterer with low co-polar response.
+    - `MediumCo` (7): Volume scatterer with medium co-polar response.
+    - `Low` (8): Weakly volume-scattering object.
+    - `MediumLow` (9): Medium-weakly volume-scattering object.
+    - `Medium` (10): Medium-strength volume-scattering object.
+    - `HighCo` (11): Volume scatterer with high co-polar response.
+    - `High` (12): Highly volume-scattering object.
+    """
+
+    LowCo = 6
+    """Volume scatterer with low co-polar response."""
+
+    MediumCo = 7
+    """Volume scatterer with medium co-polar response."""
+
+    Low = 8
+    """Weakly volume-scattering object."""
+
+    MediumLow = 9
+    """Medium-weakly volume scattering object."""
+
+    Medium = 10
+    """Medium-strength volume scattering object."""
+
+    HighCo = 11
+    """Volume scatterer with high co-polar response."""
+
+    High = 12
+    """Highly volume-scattering object."""
+
+
+class MultiBounce(IntEnum):
+    """
+    Double/triple-bounce mechanics.
+    - `HighCo` (13): High-strength co-polar double/triple-bounce, with low cross-polar response.  
+    - `MedHighCross` (14): Medium-strength cross-polar double/triple-bounce, with low co-polar response.  
+    - `MediumHigh` (15): Medium-high co- and cross-polar double/triple-bounce response.  
+    - `HighMixedCo` (16): High-strength double/triple-bounce with a mostly co-polar response.  
+    - `HighMixedCross` (17): High-strength double/triple-bounce with a mostly cross-polar response.  
+    - `VeryHigh` (18): Very strong co- and cross-polar double/triple-bounce response.  
+    """
+
+    HighCo = 13
+    """High strength co-polar double/triple-bounce, with low cross-polar, response."""
+
+    MedHighCross = 14
+    """Medium strength cross-polar double/triple-bounce, with low co-polar, response."""
+
+    MediumHigh = 15
+    """Medium-high co- and cross-polar double/triple-bounce response."""
+
+    HighMixedCo = 16
+    """High-strength double/triple-bounce with a mostly co-polar response."""
+
+    HighMixedCross = 17
+    """High-strength double/triple-bounce with a mostly cross-polar response."""
+
+    VeryHigh = 18
+    """Very strong co- and cross-polar double/triple-bounce response."""
+
+
+class Other(IntEnum):
+    """
+    Other categories.
+    - `NoData` (0): No data.  
+    - `Unknown` (19): Physically unrealistic/unknown mechanism.  
+    """
+
+    NoData = 0
+    """No data."""
+
+    Unknown = 19
+    """Physically unrealistic/unknown mechanism."""
+
+
+# A quick sanity check - do the definitions above line up with our expected number of categories?
+assert set(range(dpolcat.NUM_CATEGORIES)) == set(Surface) | set(Volume) | set(
+    MultiBounce
+) | set(Other), "Category definitions do not match the expected number."

dpolcat/pc_rio_driver.py

@@ -0,0 +1,31 @@
+# Custom PlanetaryComputer RioDriver for use in odc.stac.load,
+# which re-signs assets just before use (rather than up front).
+# planetary_computer.sign has a token cache, so it's not overly expensive.
+# Code via Claude Opus 5.5.
+
+import dataclasses
+from urllib.parse import urlsplit, urlunsplit
+
+import planetary_computer
+from odc.loader._rio import RioDriver, RioReader
+from odc.stac._mdtools import StacAuxReader
+
+
+def resign(url: str) -> str:
+    return planetary_computer.sign(urlunsplit(urlsplit(url)._replace(query="")))
+
+
+class PCRioReader(RioReader):
+    def read(self, cfg, dst_geobox, *, dst=None, selection=None):
+        src = dataclasses.replace(self._src, uri=resign(self._src.uri))
+        return RioReader(src, self._ctx).read(
+            cfg, dst_geobox, dst=dst, selection=selection
+        )
+
+
+class PCRioDriver(RioDriver):
+    def __init__(self):
+        super().__init__(aux_reader=StacAuxReader())
+
+    def open(self, src, ctx):
+        return PCRioReader(src, ctx)