earthdiff 0.2.0__py3-none-any.whl

earthdiff/render.py

@@ -0,0 +1,146 @@
+"""PNG / WebP rendering: true colour, change overlays, Web-Mercator warping, montage."""
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFont
+from pyproj import Transformer
+from rasterio.enums import Resampling
+from rasterio.transform import array_bounds
+from rasterio.warp import calculate_default_transform, reproject
+
+from .aoi import Grid
+from .change import CLASSES
+
+
+def _hex(color: str) -> tuple[int, int, int]:
+    color = color.lstrip("#")
+    return int(color[0:2], 16), int(color[2:4], 16), int(color[4:6], 16)
+
+
+def true_color(bands: dict[str, np.ndarray], mask: np.ndarray | None = None, vmax: float = 0.20, gamma: float = 0.75) -> np.ndarray:
+    """Sentinel-2 true colour (B04,B03,B02) as RGBA uint8. NaN / outside-AOI pixels are transparent."""
+    rgb = np.stack([bands["red"], bands["green"], bands["blue"]], axis=-1)
+    finite = np.isfinite(rgb).all(axis=-1)
+    x = np.clip(np.nan_to_num(rgb, nan=0.0) / vmax, 0.0, 1.0) ** gamma
+    out = np.zeros(rgb.shape[:2] + (4,), dtype=np.uint8)
+    out[..., :3] = (x * 255).astype(np.uint8)
+    alpha = finite if mask is None else (finite & mask)
+    out[..., 3] = np.where(alpha, 255, 0).astype(np.uint8)
+    return out
+
+
+def class_rgba(classmap: np.ndarray, alpha: int = 215) -> np.ndarray:
+    out = np.zeros(classmap.shape + (4,), dtype=np.uint8)
+    for cid, info in CLASSES.items():
+        m = classmap == cid
+        if m.any():
+            out[m, :3] = _hex(info.color)
+            out[m, 3] = alpha
+    return out
+
+
+def to_mercator(rgba: np.ndarray, grid: Grid, categorical: bool = False, max_dim: int | None = None):
+    """Warp an RGBA raster on ``grid`` to EPSG:3857. Returns (rgba, [[south, west], [north, east]])."""
+    h, w = rgba.shape[:2]
+    dst_t, dw, dh = calculate_default_transform(grid.crs, "EPSG:3857", w, h, *grid.bounds)
+    dst = np.zeros((4, dh, dw), dtype=np.uint8)
+    rs = Resampling.nearest if categorical else Resampling.bilinear
+    for i in range(4):
+        reproject(
+            source=np.ascontiguousarray(rgba[..., i]),
+            destination=dst[i],
+            src_transform=grid.transform,
+            src_crs=grid.crs,
+            dst_transform=dst_t,
+            dst_crs="EPSG:3857",
+            resampling=rs,
+        )
+    out = np.moveaxis(dst, 0, -1)
+    west, south, east, north = array_bounds(dh, dw, dst_t)
+    t = Transformer.from_crs("EPSG:3857", "EPSG:4326", always_xy=True)
+    w_lon, s_lat = t.transform(west, south)
+    e_lon, n_lat = t.transform(east, north)
+    if max_dim and max(out.shape[:2]) > max_dim:
+        im = Image.fromarray(out, "RGBA")
+        k = max_dim / max(out.shape[:2])
+        im = im.resize((max(1, round(out.shape[1] * k)), max(1, round(out.shape[0] * k))), Image.NEAREST if categorical else Image.LANCZOS)
+        out = np.asarray(im)
+    return np.ascontiguousarray(out), [[s_lat, w_lon], [n_lat, e_lon]]
+
+
+def save_png(rgba: np.ndarray, path: str | Path) -> None:
+    Image.fromarray(rgba, "RGBA").save(path, optimize=True)
+
+
+def webp_bytes(rgba: np.ndarray, quality: int = 86) -> bytes:
+    buf = io.BytesIO()
+    Image.fromarray(rgba, "RGBA").save(buf, "WEBP", quality=quality, method=4)
+    return buf.getvalue()
+
+
+def png_bytes(rgba: np.ndarray) -> bytes:
+    buf = io.BytesIO()
+    Image.fromarray(rgba, "RGBA").save(buf, "PNG", optimize=True)
+    return buf.getvalue()
+
+
+def _font(size: int):
+    try:
+        return ImageFont.load_default(size=size)
+    except TypeError:  # very old Pillow
+        return ImageFont.load_default()
+
+
+def _flatten(rgba: np.ndarray, bg=(235, 235, 235)) -> Image.Image:
+    base = Image.new("RGBA", (rgba.shape[1], rgba.shape[0]), bg + (255,))
+    base.alpha_composite(Image.fromarray(rgba, "RGBA"))
+    return base.convert("RGB")
+
+
+def change_map_image(after_rgba: np.ndarray, classmap: np.ndarray, totals: dict, max_dim: int = 1400) -> Image.Image:
+    """After-image (faded) with change classes on top and a legend with hectares."""
+    base = Image.fromarray(after_rgba, "RGBA")
+    faded = np.asarray(base).copy()
+    faded[..., :3] = (faded[..., :3].astype(np.float32) * 0.55 + 255 * 0.45).astype(np.uint8)
+    img = _flatten(faded)
+    over = Image.fromarray(class_rgba(classmap, 235), "RGBA")
+    img = img.convert("RGBA")
+    img.alpha_composite(over)
+    img = img.convert("RGB")
+    k = min(1.0, max_dim / max(img.size))
+    if k < 1.0:
+        img = img.resize((round(img.width * k), round(img.height * k)), Image.NEAREST)
+    d = ImageDraw.Draw(img)
+    f = _font(max(13, img.width // 70))
+    rows = [(info, totals.get(info.key, {}).get("area_ha", 0.0)) for info in CLASSES.values()]
+    lh = f.size + 8
+    box_w = int(f.size * 20)
+    box_h = lh * len(rows) + 14
+    x0, y0 = 10, img.height - box_h - 10
+    d.rectangle([x0, y0, x0 + box_w, y0 + box_h], fill=(255, 255, 255), outline=(60, 60, 60))
+    for i, (info, ha) in enumerate(rows):
+        y = y0 + 8 + i * lh
+        d.rectangle([x0 + 8, y, x0 + 8 + f.size, y + f.size], fill=_hex(info.color), outline=(40, 40, 40))
+        d.text((x0 + 16 + f.size, y - 1), f"{info.label}: {ha:,.1f} ha", fill=(20, 20, 20), font=f)
+    return img
+
+
+def montage(before_rgba: np.ndarray, after_rgba: np.ndarray, change_img: Image.Image, titles: tuple[str, str, str], panel: int = 620) -> Image.Image:
+    panels = [_flatten(before_rgba), _flatten(after_rgba), change_img.convert("RGB")]
+    resized = []
+    for p in panels:
+        k = panel / p.width
+        resized.append(p.resize((panel, max(1, round(p.height * k))), Image.LANCZOS))
+    hmax = max(p.height for p in resized)
+    cap = 36
+    sheet = Image.new("RGB", (panel * 3 + 8 * 4, hmax + cap + 16), (255, 255, 255))
+    d = ImageDraw.Draw(sheet)
+    f = _font(20)
+    for i, (p, t) in enumerate(zip(resized, titles)):
+        x = 8 + i * (panel + 8)
+        sheet.paste(p, (x, cap + 8))
+        d.text((x + 4, 8), t, fill=(20, 20, 20), font=f)
+    return sheet

earthdiff/report.py

@@ -0,0 +1,113 @@
+"""Self-contained HTML report (Leaflet inlined, imagery embedded as data URLs)."""
+from __future__ import annotations
+
+import base64
+import html
+import json
+from importlib import resources
+from typing import Any
+
+from .change import CLASSES
+from .i18n import CLASS_LABELS_TR, basis_tr, method_html_tr, warning_tr
+from .xlsx import report_workbook
+
+_TEMPLATE_PKG = "earthdiff"
+
+
+def _read(rel: str) -> str:
+    return resources.files(_TEMPLATE_PKG).joinpath(rel).read_text(encoding="utf-8")
+
+
+def data_url(data: bytes, mime: str) -> str:
+    return f"data:{mime};base64," + base64.b64encode(data).decode("ascii")
+
+
+def method_html(thresholds: dict[str, float], mmu_ha: float, resolution: float) -> str:
+    t = thresholds
+    rows = "".join(
+        f"<tr><td><span class='chip' style='background:{c.color}'></span>{html.escape(c.label)}</td><td><code>{html.escape(c.rule)}</code></td></tr>"
+        for c in CLASSES.values()
+    )
+    return f"""
+<p>earthdiff compares two <b>median composites</b> of Sentinel-2 L2A surface reflectance. Cloud, cloud shadow, cirrus, snow and
+saturated pixels are removed with the scene classification layer (SCL, cloud pixels buffered by 30&nbsp;m) before the per-pixel median is taken,
+so each pixel is the median of its cloud-free observations in that period. Everything below is a plain, inspectable rule &ndash; no machine-learning model.</p>
+<table><thead><tr><th>Change class</th><th>Rule (d = after &minus; before)</th></tr></thead><tbody>{rows}</tbody></table>
+<pre>NDVI  = (NIR - Red) / (NIR + Red)                      B08, B04
+MNDWI = (Green - SWIR1) / (Green + SWIR1)              B03, B11
+BSI   = ((SWIR1 + Red) - (NIR + Blue)) / ((SWIR1 + Red) + (NIR + Blue))   B11, B04, B08, B02</pre>
+<p>Pixel rules are then cleaned: features narrower than 3 pixels are removed by a morphological opening (3x3) (for pixels &le; 20&nbsp;m), blobs smaller than the
+<b>minimum mapping unit ({mmu_ha:g}&nbsp;ha)</b> are dropped, and the rest are polygonized (8-connectivity). Areas are pixel counts &times; pixel area
+({resolution:g}&nbsp;m pixels) on a UTM grid.</p>
+<p><b>Confidence</b> is a heuristic score from 0 to 1 &mdash; <i>not</i> a probability: 0.5&times;magnitude (how far the mean index change exceeds the threshold, saturating at 2&times;)
++ 0.3&times;valid observations (min of before/after, saturating at 3) + 0.2&times;size (log10 of area / MMU, saturating at 10&times;MMU). &ge;0.70 is &ldquo;high&rdquo;, &ge;0.45 &ldquo;medium&rdquo;.</p>
+<h3>Likely cause, seasonal check, bright surfaces</h3>
+<p><b>Likely cause</b> (vegetation-loss polygons only) is a hint, not a verdict: <code>fire-like</code> needs a dNBR of at least 0.27 (moderate-low burn severity of Key &amp; Benson 2006, the thresholds also used by Copernicus EFFIS)
+plus a dark post-event surface and more evidence for fire (also an irregular outline) than for clearing; <code>clearing-like</code> means little burn signal or a straight-edged, bright outline (felling, harvest, ploughing, construction); everything else is <code>unclear</code>.
+The brightness and shape thresholds are this project's own heuristics. When the two windows are years apart, each vegetation-loss polygon is also followed through one pass per in-between year; if one year-to-year step drops NBR much more than the whole period does (an event that has partly recovered since, such as an old burn), the hint is judged on that step and the report says when it happened. <b>Likely seasonal</b> (optional check) flags polygons whose NDVI fell by a similar amount in the same windows of earlier years; polygons are never removed.
+<b>Bright surfaces</b> (salt, sand, snow: mean visible reflectance &ge; 0.25 and NDVI &lt; 0.15) saturate the imagery; when they cover a large share of the area the report warns that change there is not reliable and lowers the confidence of polygons on them.</p>
+<h3>Limitations &mdash; please read</h3>
+<ul>
+<li><b>Seasonality and agriculture.</b> Crops, grassland and deciduous forest change colour with the seasons and with management. Compare the same season in different years; harvest, ploughing, irrigation and grazing look like vegetation loss/gain.</li>
+<li><b>Not a burn-severity or forest-law product.</b> &ldquo;Vegetation loss&rdquo; says vegetation greenness fell; it does not say why (fire, felling, drought, harvest, construction). &ldquo;New bare/built-up&rdquo; can also be soil moisture, dried crops or exposed lake bed.</li>
+<li><b>Water.</b> Shallow, turbid or algae-covered water and wet soil can fall on either side of the MNDWI rule; cloud shadow and terrain shadow can mimic water.</li>
+<li><b>Resolution.</b> Sentinel-2 pixels are {resolution:g}&nbsp;m here (SWIR is natively 20&nbsp;m). Features narrower than a few pixels (roads, small buildings, narrow streams) are not reliably detected. The MMU hides everything smaller than {mmu_ha:g}&nbsp;ha.</li>
+<li><b>Atmosphere and geometry.</b> Residual haze, sun/view-angle differences between dates and scene co-registration (~10&nbsp;m) create false alarms along edges.</li>
+<li><b>No ground truth.</b> Results are screening hints. Verify anything consequential with higher-resolution imagery, field data or official sources.</li>
+</ul>"""
+
+
+def render_report(
+    *,
+    title: str,
+    meta: dict[str, Any],
+    totals: dict[str, Any],
+    warnings: list[str],
+    geojson: dict[str, Any],
+    aoi_geojson: dict[str, Any],
+    bounds: list[list[float]],
+    images: dict[str, str],
+    scenes: list[dict[str, Any]],
+    thresholds: dict[str, float],
+    attribution: str,
+    extras: dict[str, Any] | None = None,
+    timeline: dict[str, Any] | None = None,
+    terrain: dict[str, Any] | None = None,
+) -> str:
+    data = {
+        "meta": meta,
+        "totals": totals,
+        "warnings": warnings,
+        "geojson": geojson,
+        "aoi": aoi_geojson,
+        "bounds": bounds,
+        "img": images,
+        "scenes": scenes,
+        "thresholds": thresholds,
+        "attribution": attribution,
+        "extras": extras or {},
+        "timeline": timeline or {"frames": [], "bounds": None},
+        "terrain": terrain,
+        "classes": {c.key: {"label": c.label, "color": c.color} for c in CLASSES.values()},
+        "method_html": method_html(thresholds, meta["mmu_ha"], meta["resolution_m"]),
+        # Turkish texts; the page switches language in the browser (English stays the default for non-Turkish browsers)
+        "i18n": {"tr": {
+            "warnings": [warning_tr(w) for w in warnings],
+            "method_html": method_html_tr(CLASSES.values(), meta["mmu_ha"], meta["resolution_m"]),
+            "classes": CLASS_LABELS_TR,
+        }},
+    }
+    # the report's Excel button downloads one of these, in the language shown
+    data["xlsx"] = {lg: base64.b64encode(report_workbook(lg, meta, totals, warnings if lg == "en" else data["i18n"]["tr"]["warnings"], geojson, scenes, extras,
+                                                       attribution, (terrain or {}).get("attribution"))).decode("ascii") for lg in ("en", "tr")}
+    for f in geojson.get("features", []):
+        p = f.get("properties", {})
+        if p.get("likely_cause_basis"):
+            p["likely_cause_basis_tr"] = basis_tr(p["likely_cause_basis"])
+    payload = json.dumps(data, ensure_ascii=False, separators=(",", ":")).replace("<", "\\u003c").replace("\u2028", "\\u2028")
+    page = _read("templates/report.html")
+    # placeholders are replaced with plain str.replace so the big blobs are never re-scanned by a regex
+    page = page.replace("{{TITLE}}", html.escape(title))
+    page = page.replace("{{LEAFLET_CSS}}", _read("vendor/leaflet.css"))
+    page = page.replace("{{LEAFLET_JS}}", _read("vendor/leaflet.js").replace("</script", "<\\/script"))
+    return page.replace("{{DATA_JSON}}", payload)

earthdiff/safety.py

@@ -0,0 +1,93 @@
+"""Input hygiene, output-folder confinement, error redaction and the network allow-list of the MCP server.
+
+Everything a model (or an OSM / STAC response) can put into a file name, a folder name or a message goes through here.
+"""
+from __future__ import annotations
+
+import re
+import unicodedata
+from datetime import datetime
+from pathlib import Path
+from urllib.parse import urlparse
+
+# C0/C1 control characters, zero-width and bidi override characters, line/paragraph separators
+_CONTROL = re.compile(r"[\x00-\x1f\x7f-\x9f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]")
+_TURKISH = str.maketrans({"ı": "i", "İ": "I", "ş": "s", "Ş": "S", "ğ": "g", "Ğ": "G", "ç": "c", "Ç": "C", "ö": "o", "Ö": "O", "ü": "u", "Ü": "U"})
+
+# Hosts the server may talk to: STAC APIs, Sentinel-2 COG storage and the Nominatim place search. Nothing else.
+STAC_HOSTS = ("earth-search.aws.element84.com", "planetarycomputer.microsoft.com")
+DATA_HOSTS = ("sentinel-cogs.s3.us-west-2.amazonaws.com", "*.blob.core.windows.net")
+NOMINATIM_HOST = "nominatim.openstreetmap.org"
+
+
+def clean_text(value: object, max_len: int = 200) -> str:
+    """Printable single-line text: control and bidi characters removed, whitespace collapsed, length capped."""
+    s = unicodedata.normalize("NFC", str(value))
+    s = _CONTROL.sub(" ", s)
+    s = re.sub(r"\s+", " ", s).strip()
+    return s[:max_len]
+
+
+def safe_filename(stem: str, max_len: int = 48) -> str:
+    """ASCII slug that is safe as a file or folder name on Windows, macOS and Linux (no separators, no dots at the ends)."""
+    s = str(stem).translate(_TURKISH)
+    s = unicodedata.normalize("NFKD", s).encode("ascii", "ignore").decode("ascii")
+    s = re.sub(r"[^A-Za-z0-9_-]+", "_", s).strip("_-")[:max_len].strip("_-")
+    return s or "area"
+
+
+def run_folder(root: Path, name: str, now: datetime | None = None) -> Path:
+    """Create and return ``<root>/<YYYYmmdd-HHMMSS>_<slug>``; refuses anything that would resolve outside ``root``."""
+    root = Path(root)
+    root.mkdir(parents=True, exist_ok=True)
+    root_resolved = root.resolve()
+    stamp = (now or datetime.now()).strftime("%Y%m%d-%H%M%S")
+    base = f"{stamp}_{safe_filename(name)}"
+    for n in range(1, 100):
+        candidate = root_resolved / (base if n == 1 else f"{base}-{n}")
+        if candidate.parent != root_resolved:  # defence in depth: the slug cannot contain separators
+            raise ValueError("invalid output folder name")
+        try:
+            candidate.mkdir()
+        except FileExistsError:
+            continue
+        return candidate
+    raise ValueError("could not create a unique output folder")
+
+
+# ----------------------------------------------------------------------------------------------- redaction
+_WIN_PATH = re.compile(r"(?<![A-Za-z0-9])[A-Za-z]:[\\/][^\s'\"<>|*?]*")
+_UNC_PATH = re.compile(r"\\\\[^\s'\"<>|*?]+")
+_POSIX_PATH = re.compile(r"(?<![\w:/.])/(?:[\w.\-~]+/)+[\w.\-~]*")
+_MAX_ERROR = 600
+
+
+def redact(text: object, extra: tuple[str, ...] = ()) -> str:
+    """Remove local file-system paths (and the given extra literals such as the home or output folder) from a message."""
+    s = str(text)
+    s = _UNC_PATH.sub("<path>", s)
+    s = _WIN_PATH.sub("<path>", s)
+    s = _POSIX_PATH.sub("<path>", s)
+    for lit in sorted({e for e in extra if e and len(e) >= 3}, key=len, reverse=True):
+        s = s.replace(lit, "<path>").replace(lit.replace("\\", "/"), "<path>")
+    s = _CONTROL.sub(" ", s)
+    return s[:_MAX_ERROR]
+
+
+# ----------------------------------------------------------------------------------------------- network allow-list
+def host_allowed(url: str, patterns: tuple[str, ...]) -> bool:
+    """True when ``url`` is https and its host matches an exact name or a ``*.suffix`` pattern."""
+    try:
+        parsed = urlparse(url)
+        host = (parsed.hostname or "").lower()
+    except ValueError:
+        return False
+    if parsed.scheme != "https" or not host:
+        return False
+    for pat in patterns:
+        if pat.startswith("*."):
+            if host.endswith(pat[1:]) and len(host) > len(pat) - 1:
+                return True
+        elif host == pat:
+            return True
+    return False

earthdiff/seasonal.py

@@ -0,0 +1,155 @@
+"""Seasonal-cycle check for vegetation loss ("is this just the harvest?").
+
+For every vegetation-loss polygon we look at the same two time windows in the previous 1 to ``years`` years. If NDVI fell by a similar amount
+between those earlier windows too, the loss is a recurring annual cycle (harvest, senescence, grazing, irrigation pattern) and the polygon is
+flagged ``likely_seasonal``. Polygons are never removed.
+
+Cost control: only the bounding window of the vegetation-loss pixels is read, only red and NIR, at most ``max_scenes`` scenes per window, and
+windows that equal the main before/after windows are reused. Typical extra cost is 2 to 4 small composites.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Callable
+
+import numpy as np
+from affine import Affine
+
+from .aoi import Grid
+from .composite import Reader, build_composite
+from .indices import ndvi
+from .periods import Period
+
+REPEAT_MIN_DROP = 0.12  # an earlier-year NDVI drop smaller than this does not count as a repeat
+REPEAT_FRACTION = 0.5  # ... and it must be at least this fraction of the current drop
+MIN_VEG_BEFORE = 0.30  # the earlier "before" window must have been vegetated
+
+
+def subgrid(mask: np.ndarray, grid: Grid, pad: int = 1) -> tuple[Grid, tuple[int, int, int, int]] | None:
+    """Smallest grid window (same pixel lattice) that contains every True pixel of ``mask``."""
+    if not mask.any():
+        return None
+    rows, cols = np.flatnonzero(mask.any(axis=1)), np.flatnonzero(mask.any(axis=0))
+    r0, r1 = max(int(rows[0]) - pad, 0), min(int(rows[-1]) + 1 + pad, grid.height)
+    c0, c1 = max(int(cols[0]) - pad, 0), min(int(cols[-1]) + 1 + pad, grid.width)
+    t = grid.transform
+    sub = Grid(grid.epsg, Affine(grid.res, 0, t.c + c0 * grid.res, 0, -grid.res, t.f - r0 * grid.res), c1 - c0, r1 - r0, grid.res)
+    return sub, (r0, r1, c0, c1)
+
+
+def prior_windows(before: Period, after: Period, years: int) -> list[tuple[Period, Period]]:
+    return [(before.shift_years(-k), after.shift_years(-k)) for k in range(1, years + 1)]
+
+
+def _mean_by_label(labels: np.ndarray, arr: np.ndarray, n: int) -> tuple[np.ndarray, np.ndarray]:
+    ok = np.isfinite(arr) & (labels > 0)
+    cnt = np.bincount(labels[ok], minlength=n + 1).astype(np.float64)
+    tot = np.bincount(labels[ok], weights=arr[ok].astype(np.float64), minlength=n + 1)
+    with np.errstate(invalid="ignore", divide="ignore"):
+        mean = tot / cnt
+    mean[cnt == 0] = np.nan
+    return mean, cnt
+
+
+def seasonal_check(
+    result,
+    grid: Grid,
+    before: Period,
+    after: Period,
+    geom,
+    backend: str,
+    max_cloud: float,
+    search: Callable,
+    reader: Reader,
+    years: int = 2,
+    max_scenes: int = 3,
+    progress: Callable[[str], None] | None = None,
+) -> dict[str, Any]:
+    """Annotate the vegetation-loss features of ``result`` in place and return a summary dict."""
+    say = progress or (lambda m: None)
+    t0 = time.monotonic()
+    veg_ids = [(f, lid) for f, lid in zip(result.features, result.label_ids) if f["properties"]["class"] == "vegetation_loss"]
+    summary: dict[str, Any] = {
+        "enabled": True, "years": years, "extra_composites": 0, "windows": [], "checked_polygons": 0, "no_data_polygons": 0,
+        "likely_seasonal": {"polygons": 0, "area_ha": 0.0, "share_of_vegetation_loss": 0.0},
+    }
+    veg_mask = result.classmap == 1
+    sg = subgrid(veg_mask, grid)
+    if not veg_ids or sg is None:
+        summary["elapsed_s"] = round(time.monotonic() - t0, 1)
+        return summary
+    sub, (r0, r1, c0, c1) = sg
+    sl = (slice(r0, r1), slice(c0, c1))
+    labels = result.labels[sl].copy()
+    veg_labels = {lid for _, lid in veg_ids}
+    labels[~np.isin(labels, list(veg_labels))] = 0
+    n = int(result.labels.max())
+    mask_sub = veg_mask[sl]
+
+    known = {(before.start, before.end): result.indices_before["ndvi"][sl], (after.start, after.end): result.indices_after["ndvi"][sl]}
+
+    def ndvi_of(period: Period) -> np.ndarray | None:
+        key = (period.start, period.end)
+        if key in known:
+            return known[key]
+        cands = search(backend, geom, period, max_cloud)
+        summary["windows"].append(period.label())
+        if not cands:
+            known[key] = None
+            return None
+        comp = build_composite(cands, sub, mask_sub, max_scenes, reader=reader, progress=say, label=f"seasonal {period.label()}", bands=("red", "nir"))
+        summary["extra_composites"] += 1
+        known[key] = ndvi(comp.bands["nir"], comp.bands["red"]) if comp.scenes else None
+        return known[key]
+
+    per_year: list[tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray] | None] = []
+    for b_k, a_k in prior_windows(before, after, years):
+        say(f"seasonal check: {b_k.label()} -> {a_k.label()}")
+        nb_k, na_k = ndvi_of(b_k), ndvi_of(a_k)
+        if nb_k is None or na_k is None:
+            per_year.append(None)
+            continue
+        mb, cb = _mean_by_label(labels, nb_k, n)
+        ma, ca = _mean_by_label(labels, na_k, n)
+        per_year.append((mb, ma, cb, ca, np.bincount(labels.ravel(), minlength=n + 1).astype(np.float64)))
+
+    total_loss = sum(f["properties"]["area_ha"] for f, _ in veg_ids)
+    seasonal_ha = 0.0
+    for f, lid in veg_ids:
+        p = f["properties"]
+        cur_drop = abs(p["ndvi_after"] - p["ndvi_before"])
+        checked = repeating = 0
+        priors: list[float | None] = []
+        for item in per_year:
+            if item is None:
+                priors.append(None)
+                continue
+            mb, ma, cb, ca, npix = item
+            if not (np.isfinite(mb[lid]) and np.isfinite(ma[lid])) or min(cb[lid], ca[lid]) < max(3.0, 0.3 * npix[lid]):
+                priors.append(None)
+                continue
+            d = float(ma[lid] - mb[lid])
+            priors.append(round(d, 3))
+            checked += 1
+            if mb[lid] >= MIN_VEG_BEFORE and d <= -max(REPEAT_MIN_DROP, REPEAT_FRACTION * cur_drop):
+                repeating += 1
+        p["seasonal_years_checked"] = checked
+        p["seasonal_years_repeating"] = repeating
+        p["seasonal_prior_dndvi"] = priors
+        if checked == 0:
+            p["likely_seasonal"] = None
+            summary["no_data_polygons"] += 1
+            continue
+        summary["checked_polygons"] += 1
+        p["likely_seasonal"] = bool(repeating >= 1 and repeating / checked >= 0.5)
+        if p["likely_seasonal"]:
+            summary["likely_seasonal"]["polygons"] += 1
+            seasonal_ha += p["area_ha"]
+    summary["likely_seasonal"]["area_ha"] = round(seasonal_ha, 2)
+    summary["likely_seasonal"]["share_of_vegetation_loss"] = round(seasonal_ha / total_loss, 3) if total_loss > 0 else 0.0
+    summary["method"] = (
+        f"For each vegetation-loss polygon the same two windows of the previous {years} year(s) are compared (NDVI, red and NIR only, up to {max_scenes} scenes per window). "
+        f"A year repeats the loss when NDVI fell by at least max({REPEAT_MIN_DROP}, {REPEAT_FRACTION} x the current drop). likely_seasonal = repeated in at least half of the years that had data. Polygons are never removed."
+    )
+    summary["elapsed_s"] = round(time.monotonic() - t0, 1)
+    return summary

earthdiff/stac.py

@@ -0,0 +1,163 @@
+"""Sentinel-2 L2A discovery through public STAC APIs (no account, no API key)."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from shapely.geometry.base import BaseGeometry
+
+from .periods import Period
+
+
+@dataclass(frozen=True)
+class Backend:
+    name: str
+    url: str
+    collection: str
+    # logical band name -> STAC asset key
+    assets: dict[str, str]
+    attribution: str
+    signed: bool = False
+
+
+BACKENDS: dict[str, Backend] = {
+    "earth-search": Backend(
+        name="earth-search",
+        url="https://earth-search.aws.element84.com/v1",
+        collection="sentinel-2-l2a",
+        assets={"blue": "blue", "green": "green", "red": "red", "nir": "nir", "swir16": "swir16", "swir22": "swir22", "scl": "scl"},
+        attribution="Element 84 Earth Search (Sentinel-2 L2A COGs on AWS Open Data)",
+    ),
+    "planetary-computer": Backend(
+        name="planetary-computer",
+        url="https://planetarycomputer.microsoft.com/api/stac/v1",
+        collection="sentinel-2-l2a",
+        assets={"blue": "B02", "green": "B03", "red": "B04", "nir": "B08", "swir16": "B11", "swir22": "B12", "scl": "SCL"},
+        attribution="Microsoft Planetary Computer (Sentinel-2 L2A)",
+        signed=True,
+    ),
+}
+
+
+@dataclass
+class Scene:
+    id: str
+    datetime: datetime
+    cloud_cover: float
+    tile: str
+    hrefs: dict[str, str]
+    # logical band -> (scale, offset): reflectance = DN * scale + offset
+    radiometry: dict[str, tuple[float, float]] = field(default_factory=dict)
+
+    @property
+    def date(self) -> str:
+        return self.datetime.date().isoformat()
+
+
+class STACError(RuntimeError):
+    pass
+
+
+def _radiometry(item: Any, asset_key: str, backend: str) -> tuple[float, float]:
+    """(scale, offset) so that reflectance = DN * scale + offset.
+
+    ESA processing baseline >= 04.00 adds +1000 to the DN (offset -0.1 must be applied).
+    Planetary Computer serves the ESA files as they are. Element84 Earth Search has already
+    removed the offset for the reprocessed items (``earthsearch:boa_offset_applied`` = true) even
+    though the asset's ``raster:bands`` still lists -0.1 - verified empirically (red DN 1st
+    percentile is far below 1000 on baseline 05.xx scenes) - so we must NOT subtract again.
+    """
+    props = item.properties
+    baseline = str(props.get("s2:processing_baseline", "0") or "0")
+    try:
+        new_baseline = float(baseline) >= 4.0
+    except ValueError:
+        new_baseline = False
+    if backend == "earth-search":
+        applied = bool(props.get("earthsearch:boa_offset_applied", False))
+        return 1e-4, (-0.1 if (new_baseline and not applied) else 0.0)
+    rb = item.assets[asset_key].extra_fields.get("raster:bands") or []
+    if rb and "scale" in rb[0]:
+        return float(rb[0]["scale"]), float(rb[0].get("offset", 0.0))
+    return 1e-4, (-0.1 if new_baseline else 0.0)
+
+
+def _dedupe(scenes: list[Scene]) -> list[Scene]:
+    """Keep one scene per (tile, acquisition date): the highest reprocessing sequence."""
+    best: dict[tuple[str, str], Scene] = {}
+    for s in scenes:
+        key = (s.tile, s.date)
+        if key not in best or s.id > best[key].id:
+            best[key] = s
+    return list(best.values())
+
+
+def search_scenes(
+    backend: str,
+    geom_wgs84: BaseGeometry,
+    period: Period,
+    max_cloud: float = 80.0,
+    limit: int = 30,
+    retries: int = 3,
+) -> list[Scene]:
+    """Return up to ``limit`` least-cloudy scenes (by scene-level cloud cover) in ``period``."""
+    from pystac_client import Client
+
+    if backend not in BACKENDS:
+        raise STACError(f"unknown backend {backend!r}; choose from {', '.join(BACKENDS)}")
+    be = BACKENDS[backend]
+    modifier = None
+    if be.signed:
+        try:
+            import planetary_computer
+        except ImportError as exc:  # pragma: no cover
+            raise STACError("backend 'planetary-computer' needs: pip install planetary-computer") from exc
+        modifier = planetary_computer.sign_inplace
+
+    last: Exception | None = None
+    items: list[Any] = []
+    for attempt in range(retries):
+        try:
+            client = Client.open(be.url, modifier=modifier)
+            search = client.search(
+                collections=[be.collection],
+                bbox=list(geom_wgs84.bounds),
+                datetime=period.stac(),
+                query={"eo:cloud_cover": {"lt": max_cloud}},
+                max_items=400,
+            )
+            items = list(search.items())
+            last = None
+            break
+        except Exception as exc:  # network / API hiccup
+            last = exc
+            time.sleep(2 * (attempt + 1))
+    if last is not None:
+        raise STACError(f"STAC search failed ({be.url}): {last}") from last
+
+    scenes: list[Scene] = []
+    for it in items:
+        try:
+            hrefs = {k: it.assets[v].href for k, v in be.assets.items()}
+        except KeyError:
+            continue
+        # some old Earth Search items point to requester-pays JPEG2000 on s3://; only public COGs are supported
+        if not all(h.startswith("http") and h.lower().split("?")[0].endswith((".tif", ".tiff")) for h in hrefs.values()):
+            continue
+        radio = {k: _radiometry(it, v, backend) for k, v in be.assets.items() if k != "scl"}
+        tile = str(it.properties.get("grid:code") or it.properties.get("s2:mgrs_tile") or it.id)
+        scenes.append(
+            Scene(
+                id=it.id,
+                datetime=it.datetime,
+                cloud_cover=float(it.properties.get("eo:cloud_cover", 100.0)),
+                tile=tile,
+                hrefs=hrefs,
+                radiometry=radio,
+            )
+        )
+    scenes = _dedupe(scenes)
+    scenes.sort(key=lambda s: (s.cloud_cover, s.date))
+    return scenes[:limit]