earthdiff 0.2.0__py3-none-any.whl

earthdiff/__init__.py

@@ -0,0 +1,28 @@
+"""earthdiff - explainable change reports from free Sentinel-2 imagery."""
+
+import os as _os
+from importlib.util import find_spec as _find_spec
+
+__version__ = "0.2.0"
+
+
+def _prefer_bundled_proj_data() -> None:
+    """Machines with PostGIS/QGIS/OSGeo4W often export PROJ_LIB/GDAL_DATA pointing at an *older*
+    PROJ database, which makes rasterio fail with 'EPSG code is unknown'. The rasterio wheel ships
+    consistent data, so point this process (only) at it. Set EARTHDIFF_KEEP_PROJ_ENV=1 to opt out."""
+    if _os.environ.get("EARTHDIFF_KEEP_PROJ_ENV"):
+        return
+    spec = _find_spec("rasterio")
+    if not spec or not spec.submodule_search_locations:
+        return
+    root = list(spec.submodule_search_locations)[0]
+    proj = _os.path.join(root, "proj_data")
+    gdal = _os.path.join(root, "gdal_data")
+    if _os.path.isdir(proj):
+        _os.environ["PROJ_DATA"] = proj
+        _os.environ["PROJ_LIB"] = proj
+    if _os.path.isdir(gdal):
+        _os.environ["GDAL_DATA"] = gdal
+
+
+_prefer_bundled_proj_data()

earthdiff/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

earthdiff/aoi.py

@@ -0,0 +1,161 @@
+"""Area-of-interest handling: GeoJSON / bbox parsing, UTM grid, area."""
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from affine import Affine
+from pyproj import Transformer
+from rasterio import features
+from shapely.geometry import box, mapping, shape
+from shapely.geometry.base import BaseGeometry
+from shapely.ops import transform as shp_transform, unary_union
+from shapely.validation import make_valid
+
+# One area limit for every entry point (CLI, watch, web UI, MCP server). Large areas are read on a coarser grid
+# (choose_resolution: 10/20/30/60 m, <= 4 M pixels), so memory stays bounded; run time grows with the area.
+MAX_AREA_KM2 = 2000.0
+
+WGS84 = "EPSG:4326"
+
+
+class AOIError(ValueError):
+    pass
+
+
+def bbox_geometry(west: float, south: float, east: float, north: float) -> BaseGeometry:
+    if not (-180 <= west < east <= 180 and -90 <= south < north <= 90):
+        raise AOIError("bbox must be west,south,east,north in WGS84 degrees with west<east and south<north")
+    return box(west, south, east, north)
+
+
+def parse_bbox(text: str) -> BaseGeometry:
+    try:
+        w, s, e, n = (float(x) for x in text.replace(" ", "").split(","))
+    except ValueError as exc:
+        raise AOIError("bbox must be 'west,south,east,north'") from exc
+    return bbox_geometry(w, s, e, n)
+
+
+def geometry_from_geojson(obj: dict[str, Any]) -> BaseGeometry:
+    """Accept FeatureCollection / Feature / bare geometry; return the union of its polygons."""
+    kind = obj.get("type")
+    if kind == "FeatureCollection":
+        geoms = [shape(f["geometry"]) for f in obj.get("features", []) if f.get("geometry")]
+    elif kind == "Feature":
+        geoms = [shape(obj["geometry"])]
+    elif kind in {"Polygon", "MultiPolygon"}:
+        geoms = [shape(obj)]
+    else:
+        raise AOIError(f"unsupported GeoJSON type: {kind!r}")
+    polys = []
+    for g in geoms:
+        if g.geom_type == "Polygon":
+            polys.append(g)
+        elif g.geom_type == "MultiPolygon":
+            polys.extend(g.geoms)
+    if not polys:
+        raise AOIError("the GeoJSON contains no Polygon/MultiPolygon geometry")
+    geom = _polygons_only(unary_union([make_valid(p) for p in polys]))
+    if geom.is_empty:
+        raise AOIError("AOI geometry is empty")
+    minx, miny, maxx, maxy = geom.bounds
+    if not (-180 <= minx and maxx <= 180 and -90 <= miny and maxy <= 90):
+        raise AOIError("AOI coordinates must be WGS84 longitude/latitude (EPSG:4326)")
+    return geom
+
+
+def _polygons_only(geom: BaseGeometry) -> BaseGeometry:
+    if geom.geom_type in {"Polygon", "MultiPolygon"}:
+        return geom
+    parts = [g for g in getattr(geom, "geoms", []) if g.geom_type in {"Polygon", "MultiPolygon"}]
+    return unary_union(parts) if parts else geom.buffer(0)
+
+
+def load_aoi(path: str | Path) -> BaseGeometry:
+    with open(path, "r", encoding="utf-8") as fh:
+        return geometry_from_geojson(json.load(fh))
+
+
+def utm_epsg(lon: float, lat: float) -> int:
+    if lat >= 84 or lat <= -80:
+        raise AOIError("polar areas (beyond 84N / 80S) are not supported (UTM)")
+    zone = int((lon + 180) // 6) + 1
+    zone = min(max(zone, 1), 60)
+    return (32600 if lat >= 0 else 32700) + zone
+
+
+def to_crs(geom: BaseGeometry, src: str, dst: str) -> BaseGeometry:
+    t = Transformer.from_crs(src, dst, always_xy=True)
+    return shp_transform(t.transform, geom)
+
+
+def area_km2(geom_wgs84: BaseGeometry) -> float:
+    c = geom_wgs84.representative_point()
+    utm = to_crs(geom_wgs84, WGS84, f"EPSG:{utm_epsg(c.x, c.y)}")
+    return utm.area / 1e6
+
+
+@dataclass(frozen=True)
+class Grid:
+    """Analysis grid: a UTM raster window at a fixed resolution."""
+
+    epsg: int
+    transform: Affine
+    width: int
+    height: int
+    res: float
+
+    @property
+    def crs(self) -> str:
+        return f"EPSG:{self.epsg}"
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        return (self.height, self.width)
+
+    @property
+    def bounds(self) -> tuple[float, float, float, float]:
+        t = self.transform
+        return (t.c, t.f + t.e * self.height, t.c + t.a * self.width, t.f)
+
+    @property
+    def pixel_area_ha(self) -> float:
+        return self.res * self.res / 10_000.0
+
+
+def _utm_bounds(geom_wgs84: BaseGeometry) -> tuple[int, tuple[float, float, float, float]]:
+    c = geom_wgs84.representative_point()
+    epsg = utm_epsg(c.x, c.y)
+    return epsg, to_crs(geom_wgs84, WGS84, f"EPSG:{epsg}").bounds
+
+
+def choose_resolution(geom_wgs84: BaseGeometry, max_pixels: int = 4_000_000) -> float:
+    """Smallest of 10/20/30/60 m so that the window stays within ``max_pixels``."""
+    _, (minx, miny, maxx, maxy) = _utm_bounds(geom_wgs84)
+    w, h = maxx - minx, maxy - miny
+    for res in (10.0, 20.0, 30.0, 60.0):
+        if (w / res) * (h / res) <= max_pixels:
+            return res
+    return 60.0
+
+
+def make_grid(geom_wgs84: BaseGeometry, res: float) -> Grid:
+    epsg, (minx, miny, maxx, maxy) = _utm_bounds(geom_wgs84)
+    x0 = math.floor(minx / res) * res
+    y1 = math.ceil(maxy / res) * res
+    width = max(1, int(math.ceil((maxx - x0) / res)))
+    height = max(1, int(math.ceil((y1 - miny) / res)))
+    return Grid(epsg, Affine(res, 0, x0, 0, -res, y1), width, height, res)
+
+
+def aoi_mask(geom_wgs84: BaseGeometry, grid: Grid) -> np.ndarray:
+    """Boolean raster, True where the pixel centre lies inside the AOI polygon."""
+    utm = to_crs(geom_wgs84, WGS84, grid.crs)
+    return features.rasterize(
+        [(mapping(utm), 1)], out_shape=grid.shape, transform=grid.transform, fill=0, dtype="uint8"
+    ).astype(bool)

earthdiff/cause.py

@@ -0,0 +1,144 @@
+"""Likely cause of vegetation loss: fire-like, clearing-like or unclear.
+
+This is a *hint*, never a verdict. Vegetation loss is first found by the NDVI rule (``change.py``); here each polygon is described by
+a few measurements and compared with published thresholds:
+
+* **dNBR** (differenced Normalized Burn Ratio, NBR = (NIR - SWIR2) / (NIR + SWIR2), Sentinel-2 B08 and B12; dNBR = NBR before - NBR after).
+  Burn-severity classes of Key & Benson (2006), "Landscape assessment (LA)", FIREMON, USDA Forest Service RMRS-GTR-164-CD, as used by the
+  Copernicus EFFIS fire-severity product (https://forest-fire.emergency.copernicus.eu/about-effis/technical-background/fire-severity)
+  and described by UN-SPIDER (burn severity recommended practice):
+  < 0.10 unburned or regrowth, 0.10-0.27 low, 0.27-0.44 moderate-low, 0.44-0.66 moderate-high, >= 0.66 high severity.
+  The thresholds were derived for Landsat in specific ecosystems and vary between regions and land covers, so they are indicative only.
+* **Post-event brightness** and **shape** are NOT taken from a standard: burn scars are usually darker (char, ash) than the bare soil that
+  fields and clear-cuts expose, and clearings and fields have straight edges (area close to the area of the minimum rotated rectangle).
+  These thresholds are ours (``DARK_VIS_AFTER``, ``BRIGHT_VIS_AFTER``, ``RECT_MIN``, ``IRREGULAR_MAX``), set by looking at two public cases only (Manavgat 2021 fire, Istanbul Airport 2017-2019 construction; see validation/)
+  and may not transfer to other regions, seasons or fire ages (old, ashy or grey burn scars are brighter than fresh char).
+
+Labels (stored in ``likely_cause`` of the feature, with the measurements and a plain-language basis):
+``fire-like``      dNBR at least moderate-low AND a dark post-event surface AND more evidence for fire than for clearing
+``clearing-like``  little or no burn signal, or straight-edged and bright, i.e. more evidence for clearing, harvest or construction
+``unclear``        mixed or weak evidence (the default whenever the measurements disagree)
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from .aoi import Grid
+
+DNBR_LOW = 0.10  # Key & Benson 2006: below this: unburned / regrowth
+DNBR_MODERATE_LOW = 0.27  # Key & Benson 2006: lower bound of "moderate-low" severity
+DNBR_MODERATE_HIGH = 0.44  # Key & Benson 2006: lower bound of "moderate-high" severity
+DARK_VIS_AFTER = 0.09  # ours: mean(blue, green, red) after, at or below = dark surface (char / ash). Manavgat median 0.055, Istanbul Airport 5th percentile 0.092
+BRIGHT_VIS_AFTER = 0.20  # ours: at or above = bright bare surface (soil, stubble, concrete)
+RECT_MIN = 0.80  # ours: area / minimum rotated rectangle at or above = straight-edged (field, clear-cut, site)
+IRREGULAR_MAX = 0.60  # ours: at or below = irregular outline
+
+LABELS = ("fire-like", "clearing-like", "unclear")
+SOURCES = [
+    "Key & Benson (2006) FIREMON Landscape Assessment: dNBR severity thresholds 0.10 / 0.27 / 0.44 / 0.66",
+    "Copernicus EFFIS fire severity (same thresholds applied to Sentinel-2): https://forest-fire.emergency.copernicus.eu/about-effis/technical-background/fire-severity",
+    "UN-SPIDER recommended practice: burn severity mapping with NBR / dNBR",
+]
+
+
+def classify_cause(m: dict[str, float]) -> tuple[str, list[str]]:
+    """``m`` holds dnbr, vis_after, vis_delta, rectangularity, area_ha. Returns (label, basis sentences)."""
+    fire: list[str] = []
+    clear: list[str] = []
+    d = m["dnbr"]
+    if d is None or not np.isfinite(d):
+        return "unclear", ["no SWIR2 (B12) measurement, so no burn signal could be computed"]
+    if d >= DNBR_MODERATE_HIGH:
+        fire.append(f"dNBR {d:.2f} (at least moderate-high burn severity by Key & Benson thresholds)")
+    elif d >= DNBR_MODERATE_LOW:
+        fire.append(f"dNBR {d:.2f} (at least moderate-low burn severity)")
+    elif d < DNBR_LOW:
+        clear.append(f"dNBR {d:.2f} (below 0.10: no burn signal)")
+    else:
+        clear.append(f"dNBR {d:.2f} (low, 0.10 to 0.27: weak burn signal)")
+    if m["vis_after"] <= DARK_VIS_AFTER:
+        fire.append(f"dark after (visible reflectance {m['vis_after']:.2f}), like char or ash")
+    elif m["vis_after"] >= BRIGHT_VIS_AFTER:
+        clear.append(f"bright after (visible reflectance {m['vis_after']:.2f}), like exposed soil or stubble")
+    r = m["rectangularity"]
+    if r >= RECT_MIN:
+        clear.append(f"straight-edged outline (rectangularity {r:.2f})")
+    elif r <= IRREGULAR_MAX:
+        fire.append(f"irregular outline (rectangularity {r:.2f})")
+
+    burn_signal = d >= DNBR_MODERATE_LOW
+    dark = m["vis_after"] <= DARK_VIS_AFTER
+    if burn_signal and dark and len(fire) > len(clear):  # dNBR alone is not enough (harvest and clearing raise it too): the surface must also be dark
+        return "fire-like", fire + clear
+    if (not burn_signal) and len(clear) >= len(fire) and len(clear) >= 1:
+        return "clearing-like", clear + fire
+    if burn_signal and len(clear) > len(fire):
+        return "clearing-like", clear + fire
+    return "unclear", fire + clear
+
+
+def _bincount_mean(labels_flat: np.ndarray, arr_flat: np.ndarray, n: int) -> np.ndarray:
+    ok = np.isfinite(arr_flat)
+    cnt = np.bincount(labels_flat[ok], minlength=n + 1).astype(np.float64)
+    tot = np.bincount(labels_flat[ok], weights=arr_flat[ok].astype(np.float64), minlength=n + 1)
+    with np.errstate(invalid="ignore", divide="ignore"):
+        out = tot / cnt
+    out[cnt == 0] = np.nan
+    return out
+
+
+def label_causes(result, before_bands: dict[str, np.ndarray], after_bands: dict[str, np.ndarray]) -> dict[str, Any] | None:
+    """Add ``likely_cause`` and its measurements to the vegetation-loss features of ``result`` (in place).
+
+    Returns a summary dict (hectares per label, method and sources) or ``None`` when B12 is unavailable (then the features get no label)."""
+    nb, na = result.indices_before.get("nbr"), result.indices_after.get("nbr")
+    if nb is None or na is None:
+        return None
+    n = int(result.labels.max())
+    if n == 0:
+        return _summary({})
+    sel = result.labels > 0
+    lab = result.labels[sel]
+    dnbr = _bincount_mean(lab, (nb - na)[sel], n)
+    vis_a = _bincount_mean(lab, ((after_bands["blue"] + after_bands["green"] + after_bands["red"]) / 3.0)[sel], n)
+    vis_b = _bincount_mean(lab, ((before_bands["blue"] + before_bands["green"] + before_bands["red"]) / 3.0)[sel], n)
+    totals: dict[str, dict[str, float]] = {k: {"polygons": 0, "area_ha": 0.0} for k in LABELS}
+    for f, lid in zip(result.features, result.label_ids):
+        p = f["properties"]
+        if p["class"] != "vegetation_loss":
+            continue
+        shape = result.shape_stats.get(lid, {})
+        m = {
+            "dnbr": float(dnbr[lid]) if np.isfinite(dnbr[lid]) else None,
+            "vis_after": float(vis_a[lid]),
+            "vis_delta": float(vis_a[lid] - vis_b[lid]),
+            "rectangularity": float(shape.get("rectangularity", 0.0)),
+            "area_ha": float(p["area_ha"]),
+        }
+        label, basis = classify_cause(m)
+        p["likely_cause"] = label
+        p["likely_cause_basis"] = "; ".join(basis)
+        p["dnbr"] = None if m["dnbr"] is None else round(m["dnbr"], 3)
+        p["vis_reflectance_after"] = round(m["vis_after"], 3)
+        p["rectangularity"] = round(m["rectangularity"], 3)
+        totals[label]["polygons"] += 1
+        totals[label]["area_ha"] = round(totals[label]["area_ha"] + p["area_ha"], 2)
+    return _summary(totals)
+
+
+def _summary(totals: dict[str, dict[str, float]]) -> dict[str, Any]:
+    full = {k: totals.get(k, {"polygons": 0, "area_ha": 0.0}) for k in LABELS}
+    return {
+        "applies_to": "vegetation_loss polygons",
+        "totals": full,
+        "note": "A hint from dNBR, brightness and shape, not a verdict on the cause. 'fire-like' does not prove a fire; 'clearing-like' covers felling, harvest, ploughing and construction.",
+        "thresholds": {
+            "dnbr_unburned_below": DNBR_LOW, "dnbr_moderate_low": DNBR_MODERATE_LOW, "dnbr_moderate_high": DNBR_MODERATE_HIGH,
+            "dark_visible_reflectance_after_at_most": DARK_VIS_AFTER, "bright_visible_reflectance_after_at_least": BRIGHT_VIS_AFTER,
+            "straight_edged_rectangularity_at_least": RECT_MIN, "irregular_rectangularity_at_most": IRREGULAR_MAX,
+        },
+        "sources": SOURCES,
+        "own_thresholds": "brightness and rectangularity thresholds are this project's heuristics, checked on only two public cases",
+    }

earthdiff/change.py

@@ -0,0 +1,337 @@
+"""Rule-based change classification, minimum mapping unit, polygonization, confidence."""
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+import numpy as np
+from pyproj import Transformer
+from rasterio import features
+from scipy.ndimage import binary_opening, label
+from shapely.geometry import mapping, shape
+from shapely.ops import transform as shp_transform
+
+from .aoi import WGS84, Grid
+from .composite import Composite
+from .indices import compute_indices, ndvi, normalized_difference
+
+
+@dataclass(frozen=True)
+class ClassInfo:
+    id: int
+    key: str
+    label: str
+    color: str  # colour-blind friendly (Okabe-Ito)
+    rule: str
+
+
+CLASSES: dict[int, ClassInfo] = {
+    1: ClassInfo(1, "vegetation_loss", "Vegetation loss", "#D55E00",
+                 "NDVI before >= veg_min_before AND dNDVI <= -veg_drop AND not water after"),
+    2: ClassInfo(2, "vegetation_gain", "Vegetation gain", "#009E73",
+                 "NDVI after >= veg_min_after AND dNDVI >= +veg_rise AND not water before"),
+    3: ClassInfo(3, "new_water", "New water", "#0072B2",
+                 "water after (MNDWI > water_mndwi, NDVI < 0.30) AND MNDWI before < land_mndwi AND dMNDWI >= water_delta"),
+    4: ClassInfo(4, "water_loss", "Water loss", "#F0E442",
+                 "water before AND MNDWI after < land_mndwi AND dMNDWI <= -water_delta"),
+    5: ClassInfo(5, "new_bare_or_built", "New bare soil / built-up", "#CC79A7",
+                 "dBSI >= bare_rise AND NDVI after < bare_ndvi_max AND no water before/after"),
+}
+KEY_TO_ID = {c.key: c.id for c in CLASSES.values()}
+
+
+@dataclass(frozen=True)
+class Thresholds:
+    veg_min_before: float = 0.40
+    veg_drop: float = 0.25
+    veg_min_after: float = 0.40
+    veg_rise: float = 0.25
+    water_mndwi: float = 0.10
+    land_mndwi: float = -0.05
+    water_ndvi_max: float = 0.30
+    water_delta: float = 0.25
+    bare_rise: float = 0.15
+    bare_ndvi_max: float = 0.25
+
+    def as_dict(self) -> dict[str, float]:
+        return asdict(self)
+
+
+SENSITIVITY = {
+    "strict": dict(veg_drop=0.35, veg_rise=0.35, water_delta=0.35, bare_rise=0.22),
+    "default": {},
+    "sensitive": dict(veg_drop=0.18, veg_rise=0.18, water_delta=0.18, bare_rise=0.10),
+}
+
+
+def thresholds_for(sensitivity: str = "default", **overrides: float) -> Thresholds:
+    if sensitivity not in SENSITIVITY:
+        raise ValueError(f"sensitivity must be one of {', '.join(SENSITIVITY)}")
+    params = {**SENSITIVITY[sensitivity], **overrides}
+    return Thresholds(**params)
+
+
+def classify(before: dict[str, np.ndarray], after: dict[str, np.ndarray], thr: Thresholds) -> np.ndarray:
+    """Per-pixel class id (uint8; 0 = no change). ``before``/``after`` hold ndvi, mndwi, bsi."""
+    nb, na = before["ndvi"], after["ndvi"]
+    mb, ma = before["mndwi"], after["mndwi"]
+    bb, ba = before["bsi"], after["bsi"]
+    valid = np.isfinite(nb) & np.isfinite(na) & np.isfinite(mb) & np.isfinite(ma) & np.isfinite(bb) & np.isfinite(ba)
+
+    with np.errstate(invalid="ignore"):
+        dn, dm, db = na - nb, ma - mb, ba - bb
+        water_a = (ma > thr.water_mndwi) & (na < thr.water_ndvi_max)
+        water_b = (mb > thr.water_mndwi) & (nb < thr.water_ndvi_max)
+
+        new_water = water_a & (mb < thr.land_mndwi) & (dm >= thr.water_delta)
+        water_loss = water_b & (ma < thr.land_mndwi) & (dm <= -thr.water_delta)
+        veg_loss = (nb >= thr.veg_min_before) & (dn <= -thr.veg_drop) & ~water_a
+        veg_gain = (na >= thr.veg_min_after) & (dn >= thr.veg_rise) & ~water_b
+        bare = (db >= thr.bare_rise) & (na < thr.bare_ndvi_max) & ~water_a & ~water_b
+
+    out = np.zeros(nb.shape, dtype=np.uint8)
+    # lowest priority first; later assignments overwrite earlier ones
+    out[bare & valid] = 5
+    out[veg_gain & valid] = 2
+    out[veg_loss & valid] = 1
+    out[water_loss & valid] = 4
+    out[new_water & valid] = 3
+    return out
+
+
+def label_components(
+    classmap: np.ndarray, res: float, mmu_ha: float, open_noise: bool = True
+) -> tuple[np.ndarray, np.ndarray]:
+    """Clean each class (opening for <=20 m pixels), drop blobs below the MMU, label the rest.
+
+    Returns ``(labels, label_class)`` where ``label_class[label] -> class id`` (index 0 unused).
+    """
+    labels = np.zeros(classmap.shape, dtype=np.int32)
+    label_class = [0]
+    min_pix = max(1, int(math.ceil(mmu_ha * 10_000.0 / (res * res))))
+    struct8 = np.ones((3, 3), dtype=bool)
+    square3 = np.ones((3, 3), dtype=bool)
+    next_id = 1
+    for cid in CLASSES:
+        m = classmap == cid
+        if not m.any():
+            continue
+        if open_noise and res <= 20.0:
+            m = binary_opening(m, structure=square3)
+            if not m.any():
+                continue
+        lab, n = label(m, structure=struct8)
+        sizes = np.bincount(lab.ravel(), minlength=n + 1)
+        keep = sizes >= min_pix
+        keep[0] = False
+        kept = np.flatnonzero(keep)
+        if kept.size == 0:
+            continue
+        remap = np.zeros(n + 1, dtype=np.int32)
+        remap[kept] = np.arange(next_id, next_id + kept.size, dtype=np.int32)
+        sel = keep[lab]
+        labels[sel] = remap[lab[sel]]
+        label_class.extend([cid] * int(kept.size))
+        next_id += int(kept.size)
+    return labels, np.array(label_class, dtype=np.uint8)
+
+
+def _primary(cid: int, mean_b: dict[str, np.ndarray], mean_a: dict[str, np.ndarray], thr: Thresholds):
+    """(delta, threshold) that defines each class; used for the magnitude part of the confidence."""
+    dn = mean_a["ndvi"] - mean_b["ndvi"]
+    dm = mean_a["mndwi"] - mean_b["mndwi"]
+    db = mean_a["bsi"] - mean_b["bsi"]
+    return {
+        1: (-dn, thr.veg_drop),
+        2: (dn, thr.veg_rise),
+        3: (dm, thr.water_delta),
+        4: (-dm, thr.water_delta),
+        5: (db, thr.bare_rise),
+    }[cid]
+
+
+def confidence_score(magnitude_ratio: float, obs: float, area_ha: float, mmu_ha: float) -> float:
+    """Heuristic 0..1 (NOT a statistical probability).
+
+    0.5 * magnitude + 0.3 * valid observations + 0.2 * size, where
+      magnitude = clip((delta - threshold) / threshold, 0, 1)   (delta of 2x threshold -> 1)
+      obs       = clip(min(valid obs before, after) / 3, 0, 1)
+      size      = clip(log10(area / MMU), 0, 1)                 (10x the MMU -> 1)
+    """
+    mag = min(max(magnitude_ratio, 0.0), 1.0)
+    o = min(max(obs / 3.0, 0.0), 1.0)
+    size = min(max(math.log10(max(area_ha, 1e-9) / mmu_ha), 0.0), 1.0)
+    return 0.5 * mag + 0.3 * o + 0.2 * size
+
+
+def confidence_level(score: float) -> str:
+    return "high" if score >= 0.70 else "medium" if score >= 0.45 else "low"
+
+
+@dataclass
+class ChangeResult:
+    classmap: np.ndarray  # cleaned, uint8
+    labels: np.ndarray
+    features: list[dict[str, Any]]
+    indices_before: dict[str, np.ndarray]
+    indices_after: dict[str, np.ndarray]
+    valid: np.ndarray  # bool, comparable pixels inside the AOI
+    totals: dict[str, dict[str, float]] = field(default_factory=dict)
+    label_ids: list[int] = field(default_factory=list)  # raster label of each feature (same order as ``features``)
+    shape_stats: dict[int, dict[str, float]] = field(default_factory=dict)
+    bright_fraction: float = 0.0  # share of comparable pixels that are very bright in the before OR after composite
+    bright_both_fraction: float = 0.0  # ... in BOTH composites
+    bright_ndwi: dict[str, float] | None = None  # NDWI > 0 share of the bright pixels before / after (exploratory wet/dry signal), None if no bright pixels
+
+
+def bright_mask(bands: dict[str, np.ndarray], vis_min: float = 0.25, ndvi_max: float = 0.15) -> np.ndarray:
+    """Very bright, non-vegetated surface (salt pan, sand, snow, bare limestone, concrete): mean visible reflectance >= ``vis_min``
+    and NDVI < ``ndvi_max``. Such surfaces saturate true-colour images and the water/vegetation rules are unreliable on them."""
+    vis = (bands["blue"] + bands["green"] + bands["red"]) / 3.0
+    nd = ndvi(bands["nir"], bands["red"])
+    with np.errstate(invalid="ignore"):
+        return np.isfinite(vis) & (vis >= vis_min) & (nd < ndvi_max)
+
+
+def polygonize(*args, **kwargs) -> list[dict[str, Any]]:
+    """Polygons as GeoJSON features (see :func:`polygonize_detailed` for the label ids and shape statistics)."""
+    return polygonize_detailed(*args, **kwargs)[0]
+
+
+def polygonize_detailed(
+    labels: np.ndarray,
+    label_class: np.ndarray,
+    grid: Grid,
+    ib: dict[str, np.ndarray],
+    ia: dict[str, np.ndarray],
+    obs_b: np.ndarray,
+    obs_a: np.ndarray,
+    thr: Thresholds,
+    mmu_ha: float,
+    bright_b: np.ndarray | None = None,
+    bright_a: np.ndarray | None = None,
+) -> tuple[list[dict[str, Any]], list[int], dict[int, dict[str, float]]]:
+    """Like :func:`polygonize` but also returns ``label_ids`` (the raster label of each feature, same order) and per-label
+    shape statistics (``rectangularity`` = area / minimum rotated rectangle area, ``solidity`` = area / convex hull area)."""
+    n = int(labels.max())
+    if n == 0:
+        return [], [], {}
+    sel = labels > 0
+    lab = labels[sel]
+    npix = np.bincount(lab, minlength=n + 1).astype(np.float64)
+    denom = np.maximum(npix, 1.0)
+
+    def mean_of(arr: np.ndarray) -> np.ndarray:
+        return np.bincount(lab, weights=np.nan_to_num(arr[sel].astype(np.float64)), minlength=n + 1) / denom
+
+    mb = {k: mean_of(ib[k]) for k in ("ndvi", "mndwi", "bsi")}
+    ma = {k: mean_of(ia[k]) for k in ("ndvi", "mndwi", "bsi")}
+    ob, oa = mean_of(obs_b), mean_of(obs_a)
+
+    to_wgs = Transformer.from_crs(grid.crs, WGS84, always_xy=True).transform
+    shapes_iter = features.shapes(labels, mask=sel, transform=grid.transform, connectivity=8)
+    parts: dict[int, list[dict]] = {}
+    for geom, value in shapes_iter:
+        parts.setdefault(int(value), []).append(geom)
+
+    bsh_b = mean_of(bright_b.astype(np.float32)) if bright_b is not None else None
+    bsh_a = mean_of(bright_a.astype(np.float32)) if bright_a is not None else None
+    out: list[tuple[dict[str, Any], int]] = []
+    shapes: dict[int, dict[str, float]] = {}
+    for lid in sorted(parts):
+        cid = int(label_class[lid])
+        info = CLASSES[cid]
+        area_ha = float(npix[lid] * grid.pixel_area_ha)
+        delta_arr, t = _primary(cid, {k: v[lid] for k, v in mb.items()}, {k: v[lid] for k, v in ma.items()}, thr)
+        mag_ratio = (float(delta_arr) - t) / t
+        obs = float(min(ob[lid], oa[lid]))
+        score = confidence_score(mag_ratio, obs, area_ha, mmu_ha)
+        bright_share = 0.0
+        if bsh_b is not None and bsh_a is not None:
+            bright_share = float(max(bsh_b[lid], bsh_a[lid]))
+            score *= 1.0 - 0.5 * bright_share  # confidence is lowered where the surface is very bright (salt, sand, snow)
+        utm_geom = shape(parts[lid][0])
+        mrr, hull = utm_geom.minimum_rotated_rectangle.area, utm_geom.convex_hull.area
+        shapes[lid] = {
+            "rectangularity": round(float(utm_geom.area / mrr), 3) if mrr > 0 else 0.0,
+            "solidity": round(float(utm_geom.area / hull), 3) if hull > 0 else 0.0,
+        }
+        geom = shp_transform(to_wgs, utm_geom)
+        cen = geom.representative_point()
+        out.append(
+            ({
+                "type": "Feature",
+                "geometry": mapping(_round_geom(geom)),
+                "properties": {
+                    "id": len(out) + 1,
+                    "class": info.key,
+                    "class_label": info.label,
+                    "area_ha": round(area_ha, 2),
+                    "confidence": round(score, 2),
+                    "confidence_level": confidence_level(score),
+                    "ndvi_before": round(float(mb["ndvi"][lid]), 3),
+                    "ndvi_after": round(float(ma["ndvi"][lid]), 3),
+                    "mndwi_before": round(float(mb["mndwi"][lid]), 3),
+                    "mndwi_after": round(float(ma["mndwi"][lid]), 3),
+                    "bsi_before": round(float(mb["bsi"][lid]), 3),
+                    "bsi_after": round(float(ma["bsi"][lid]), 3),
+                    "valid_obs_before": round(float(ob[lid]), 1),
+                    "valid_obs_after": round(float(oa[lid]), 1),
+                    "centroid_lon": round(cen.x, 6),
+                    "centroid_lat": round(cen.y, 6),
+                    "bright_share": round(bright_share, 3),
+                },
+            }, lid)
+        )
+    out.sort(key=lambda t: -t[0]["properties"]["area_ha"])
+    for i, (f, _) in enumerate(out, 1):
+        f["properties"]["id"] = i
+    return [f for f, _ in out], [lid for _, lid in out], shapes
+
+
+def _round_geom(geom, nd: int = 6):
+    from shapely import set_precision
+
+    return set_precision(geom, 10 ** -nd)
+
+
+def detect_changes(
+    before: Composite,
+    after: Composite,
+    grid: Grid,
+    mask: np.ndarray,
+    thr: Thresholds,
+    mmu_ha: float = 0.5,
+) -> ChangeResult:
+    ib = compute_indices(before.bands)
+    ia = compute_indices(after.bands)
+    valid = mask & (before.count > 0) & (after.count > 0)
+    for d in (ib, ia):
+        for arr in d.values():
+            arr[~valid] = np.nan
+    raw = classify(ib, ia, thr)
+    labels, label_class = label_components(raw, grid.res, mmu_ha)
+    del raw
+    bright_b, bright_a = bright_mask(before.bands) & valid, bright_mask(after.bands) & valid
+    n_valid = max(1, int(valid.sum()))
+    bright_fraction = float((bright_b | bright_a).sum()) / n_valid
+    bright_both = float((bright_b & bright_a).sum()) / n_valid
+    bright_ndwi = None
+    ref = bright_b | bright_a
+    if int(ref.sum()) >= 100:
+        bright_ndwi = {"pixels": int(ref.sum())}
+        for tag, comp in (("before", before), ("after", after)):
+            nd = normalized_difference(comp.bands["green"], comp.bands["nir"])
+            bright_ndwi[tag] = round(float(((nd > 0) & ref).sum()) / int(ref.sum()), 3)
+    feats, label_ids, shapes = polygonize_detailed(labels, label_class, grid, ib, ia, before.count, after.count, thr, mmu_ha, bright_b, bright_a)
+    classmap = label_class[labels] if labels.size else np.zeros_like(labels, dtype=np.uint8)
+    totals: dict[str, dict[str, float]] = {}
+    for info in CLASSES.values():
+        subset = [f for f in feats if f["properties"]["class"] == info.key]
+        totals[info.key] = {
+            "label": info.label,
+            "polygons": len(subset),
+            "area_ha": round(sum(f["properties"]["area_ha"] for f in subset), 2),
+        }
+    return ChangeResult(classmap.astype(np.uint8), labels, feats, ib, ia, valid, totals, label_ids, shapes, bright_fraction, bright_both, bright_ndwi)