earthdiff 0.2.0__py3-none-any.whl

earthdiff/cli.py

@@ -0,0 +1,202 @@
+"""Command line interface: run | plan | watch | ui | mcp."""
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import date
+from pathlib import Path
+
+from . import __version__
+from .aoi import AOIError, area_km2, load_aoi, parse_bbox
+from .aoi import MAX_AREA_KM2
+from .change import SENSITIVITY
+from .periods import parse_period
+from .pipeline import InsufficientDataError, RunOptions, plan, run_analysis
+from .stac import BACKENDS, STACError
+
+
+def _say(msg: str) -> None:
+    print(f"  {msg}", flush=True)
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    g = p.add_argument_group("area of interest")
+    g.add_argument("--aoi", help="GeoJSON file (Polygon/MultiPolygon, Feature or FeatureCollection; WGS84)")
+    g.add_argument("--bbox", help="west,south,east,north in degrees (alternative to --aoi)")
+    g = p.add_argument_group("time windows")
+    g.add_argument("--after", required=True, help="YYYY-MM | YYYY-MM-DD | START/END   (the 'now' window)")
+    g.add_argument("--before", help="baseline window; default = the --after window one year earlier (same season)")
+    g = p.add_argument_group("processing")
+    g.add_argument("--backend", choices=list(BACKENDS), default="earth-search", help="free public STAC API (default: earth-search)")
+    g.add_argument("--resolution", type=float, help="analysis pixel size in metres (default: auto 10/20/30/60)")
+    g.add_argument("--max-scenes", type=int, default=8, help="max scenes per composite (default 8)")
+    g.add_argument("--max-cloud", type=float, default=80.0, help="discard scenes with more scene-level cloud %% (default 80)")
+    g.add_argument("--sensitivity", choices=list(SENSITIVITY), default="default")
+    g.add_argument("--mmu-ha", type=float, default=0.5, help="minimum mapping unit in hectares (default 0.5)")
+    g.add_argument("--max-area-km2", type=float, default=MAX_AREA_KM2, help=f"AOI size limit (default {MAX_AREA_KM2:,.0f} km2, the same limit as the web UI and the MCP server)")
+    g.add_argument("--no-likely-cause", action="store_true", help="do not read B12 / label vegetation loss as fire-like, clearing-like or unclear (dNBR)")
+    g.add_argument("--any-season", action="store_true", help="run even when the two windows are in different seasons (refused by default: almost everything would look changed)")
+    g.add_argument("--no-yearly-frames", action="store_true", help="windows years apart: do not add one small timeline frame per in-between year")
+    g.add_argument("--no-terrain", action="store_true", help="do not read the Copernicus DEM for the report's offline 3D view and relief basemap")
+    g.add_argument("--seasonal-check", action="store_true", help="compare vegetation loss with the same windows of earlier years and flag recurring (harvest-like) loss; adds a few small downloads")
+    g.add_argument("--seasonal-years", type=int, default=2, choices=[1, 2, 3], help="how many earlier years the seasonal check looks at (default 2)")
+
+
+def _geometry(args):
+    if bool(args.aoi) == bool(args.bbox):
+        raise AOIError("give exactly one of --aoi or --bbox")
+    return load_aoi(args.aoi) if args.aoi else parse_bbox(args.bbox)
+
+
+def _options(args, name: str) -> RunOptions:
+    return RunOptions(
+        name=name,
+        backend=args.backend,
+        resolution=args.resolution,
+        max_scenes=args.max_scenes,
+        max_cloud=args.max_cloud,
+        sensitivity=args.sensitivity,
+        mmu_ha=args.mmu_ha,
+        max_area_km2=args.max_area_km2,
+        force=getattr(args, "force", False),
+        likely_cause=not args.no_likely_cause,
+        terrain=not args.no_terrain,
+        allow_season_mismatch=args.any_season,
+        yearly_frames=not args.no_yearly_frames,
+        seasonal_check=args.seasonal_check,
+        seasonal_years=args.seasonal_years,
+    )
+
+
+def _periods(args):
+    after = parse_period(args.after)
+    before = parse_period(args.before) if args.before else after.shift_years(-1)
+    return before, after
+
+
+def cmd_run(args) -> int:
+    geom = _geometry(args)
+    before, after = _periods(args)
+    name = args.name or (Path(args.aoi).stem if args.aoi else "bbox area")
+    print(f"earthdiff {__version__}: {name} | before {before.label()} -> after {after.label()}")
+    res = run_analysis(geom, before, after, args.out, _options(args, name), progress=_say)
+    print_summary(res.summary)
+    print(f"\nOpen: {res.files['report']}")
+    return 0
+
+
+def cmd_plan(args) -> int:
+    geom = _geometry(args)
+    before, after = _periods(args)
+    info = plan(geom, before, after, _options(args, "plan"))
+    print(f"AOI {info['aoi_km2']} km2, analysis resolution {info['resolution_m']:g} m")
+    print(f"before {before.label()}: {info['before_candidates']} candidate scenes  {', '.join(info['before_dates'][:12])}")
+    print(f"after  {after.label()}: {info['after_candidates']} candidate scenes  {', '.join(info['after_dates'][:12])}")
+    return 0
+
+
+def print_summary(s: dict) -> None:
+    print("\nResult")
+    print(f"  comparable (cloud-free in both periods): {s['valid_fraction'] * 100:.0f}% of the AOI")
+    for t in s["totals"].values():
+        print(f"  {t['label']:<26} {t['area_ha']:>10,.1f} ha   ({t['polygons']} polygons)")
+    lc = s.get("likely_cause")
+    if lc:
+        t = lc["totals"]
+        print("  vegetation loss, likely cause (a hint from dNBR, brightness and shape, not a verdict): "
+              + ", ".join(f"{k} {t[k]['area_ha']:,.1f} ha" for k in ("fire-like", "clearing-like", "unclear")))
+    sc = s.get("seasonal_check")
+    if sc and sc.get("enabled"):
+        ls = sc["likely_seasonal"]
+        print(f"  seasonal check ({sc['years']} earlier year(s), {sc['extra_composites']} extra composites, {sc.get('elapsed_s', 0)} s): likely seasonal {ls['area_ha']:,.1f} ha in {ls['polygons']} polygons")
+    for w in s["warnings"]:
+        print(f"  ! {w}")
+    print(f"  {s['attribution']}")
+
+
+def cmd_watch(args) -> int:
+    from .watch import EXAMPLE, run_watch
+
+    if args.init:
+        p = Path(args.config)
+        if p.exists():
+            print(f"{p} already exists; not overwriting", file=sys.stderr)
+            return 2
+        p.write_text(EXAMPLE, encoding="utf-8")
+        print(f"wrote example config to {p}")
+        return 0
+    today = date.fromisoformat(args.today) if args.today else None
+    outcomes = run_watch(args.config, today=today, force=args.force, progress=_say)
+    failed = 0
+    for o in outcomes:
+        extra = ""
+        if o.delta:
+            extra = "  (vs previous run: " + ", ".join(f"{k} {v:+.1f} ha" for k, v in o.delta.items() if v) + ")"
+        print(f"[{o.status}] {o.name}: {o.message}{extra}")
+        failed += o.status == "failed"
+    return 3 if failed else 0
+
+
+def cmd_ui(args) -> int:
+    from .ui import serve
+
+    serve(port=args.port, workdir=Path(args.workdir), open_browser=not args.no_browser)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="earthdiff", description="What changed here? Explainable change reports from free Sentinel-2 imagery.")
+    p.add_argument("--version", action="version", version=f"earthdiff {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    r = sub.add_parser("run", help="analyse one area and write a report folder")
+    _add_common(r)
+    r.add_argument("--out", default="report", help="output folder (default ./report)")
+    r.add_argument("--name", help="title shown in the report")
+    r.add_argument("--force", action="store_true", help="run even when the cloud-free fraction is very low")
+    r.set_defaults(fn=cmd_run)
+
+    pl = sub.add_parser("plan", help="dry run: only search scenes, download nothing")
+    _add_common(pl)
+    pl.set_defaults(fn=cmd_plan)
+
+    w = sub.add_parser("watch", help="re-run the areas of a TOML config for the last full month (schedule it yourself)")
+    w.add_argument("config", help="path of the TOML file")
+    w.add_argument("--init", action="store_true", help="write an example config to the given path and exit")
+    w.add_argument("--today", help="pretend today is YYYY-MM-DD (testing/backfill)")
+    w.add_argument("--force", action="store_true", help="redo periods that already have results")
+    w.set_defaults(fn=cmd_watch)
+
+    sub.add_parser("mcp", help="MCP server (stdio) for AI assistants; same as `earthdiff-mcp` (needs: pip install \"earthdiff[mcp]\")")
+
+    u = sub.add_parser("ui", help="local web UI (127.0.0.1 only): draw an area, pick dates, run")
+    u.add_argument("--port", type=int, default=8765)
+    u.add_argument("--workdir", default="earthdiff-runs", help="where UI runs are stored")
+    u.add_argument("--no-browser", action="store_true")
+    u.set_defaults(fn=cmd_ui)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    raw = sys.argv[1:] if argv is None else argv
+    if raw and raw[0] == "mcp":  # `earthdiff mcp [options]` is the same server as `earthdiff-mcp`
+        from .mcp_server import main as mcp_main
+
+        mcp_main(raw[1:])
+        return 0
+    args = build_parser().parse_args(argv)
+    try:
+        return args.fn(args)
+    except (AOIError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except (InsufficientDataError, STACError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 3
+    except KeyboardInterrupt:
+        print("interrupted", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

earthdiff/composite.py

@@ -0,0 +1,169 @@
+"""Cloud masking (SCL) and per-period median composites."""
+from __future__ import annotations
+
+import gc
+import warnings
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Callable
+
+import numpy as np
+from scipy.ndimage import binary_dilation
+
+from .aoi import Grid
+from .reader import cog_reader
+from .stac import Scene
+
+BANDS = ("blue", "green", "red", "nir", "swir16")
+BANDS_WITH_B12 = BANDS + ("swir22",)  # swir22 (B12) feeds NBR / dNBR; it is optional: an unreadable B12 never blocks a run
+OPTIONAL_BANDS = ("swir22",)
+
+# Sentinel-2 L2A Scene Classification Layer values
+SCL_NODATA, SCL_SATURATED, SCL_DARK, SCL_CLOUD_SHADOW = 0, 1, 2, 3
+SCL_CLOUD_MEDIUM, SCL_CLOUD_HIGH, SCL_CIRRUS, SCL_SNOW = 8, 9, 10, 11
+# Rejected by default: no data, saturated/defective, cloud shadow, clouds (all), cirrus, snow/ice.
+# Kept: dark area pixels (2), vegetation (4), not-vegetated (5), water (6), unclassified (7).
+DEFAULT_INVALID_SCL = (0, 1, 3, 8, 9, 10, 11)
+_CLOUDY = (3, 8, 9, 10)
+
+Reader = Callable[[Scene, str, Grid], np.ndarray]
+Progress = Callable[[str], None]
+
+
+def valid_from_scl(
+    scl: np.ndarray, res: float = 20.0, invalid: tuple[int, ...] = DEFAULT_INVALID_SCL, buffer_m: float = 30.0
+) -> np.ndarray:
+    """True where the pixel is usable. Cloud/shadow pixels are dilated by ``buffer_m`` metres."""
+    bad = np.isin(scl, invalid)
+    iters = int(round(buffer_m / res))
+    if iters > 0:
+        cloudy = np.isin(scl, _CLOUDY)
+        if cloudy.any():
+            bad |= binary_dilation(cloudy, iterations=iters)
+    return ~bad
+
+
+def to_reflectance(dn: np.ndarray, scale: float, offset: float) -> np.ndarray:
+    refl = dn.astype(np.float32) * np.float32(scale) + np.float32(offset)
+    np.clip(refl, 0.0, 2.0, out=refl)
+    return refl
+
+
+@dataclass
+class Composite:
+    bands: dict[str, np.ndarray]  # float32 reflectance; NaN where no valid observation
+    count: np.ndarray  # uint8, number of valid observations per pixel
+    scenes: list[Scene]
+    candidates: int
+    scene_valid_fraction: dict[str, float] = field(default_factory=dict)
+    # per-scene true-colour bands, subsampled by ``frame_step`` (float16, NaN = cloud / no data), for the report timeline
+    frames: dict[str, np.ndarray] = field(default_factory=dict)
+    frame_step: int = 1
+
+
+def strip_median(stack: np.ndarray, max_elems: int = 12_000_000) -> np.ndarray:
+    """nanmedian over axis 0, in row strips to bound temporary memory."""
+    n, h, w = stack.shape
+    out = np.empty((h, w), dtype=np.float32)
+    rows = max(1, max_elems // max(1, n * w))
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", RuntimeWarning)
+        for r0 in range(0, h, rows):
+            out[r0 : r0 + rows] = np.nanmedian(stack[:, r0 : r0 + rows], axis=0)
+    return out
+
+
+def build_composite(
+    candidates: list[Scene],
+    grid: Grid,
+    mask: np.ndarray,
+    max_scenes: int = 8,
+    min_scene_fraction: float = 0.02,
+    reader: Reader = cog_reader,
+    workers: int = 6,
+    progress: Progress | None = None,
+    label: str = "",
+    bands: tuple[str, ...] = BANDS,
+    frame_max_dim: int = 0,
+) -> Composite:
+    """Select the scenes that really cover the AOI cloud-free, then median-composite them."""
+    say = progress or (lambda m: None)
+    h, w = grid.shape
+    n_aoi = max(1, int(mask.sum()))
+
+    # 1) read SCL of every candidate (cheap, 20 m) and rank by cloud-free AOI coverage
+    say(f"{label}: checking cloud cover of {len(candidates)} candidate scenes")
+    def read_scl(s: Scene):
+        try:
+            return reader(s, "scl", grid)
+        except Exception as exc:  # unreadable scene: skip it instead of failing the whole run
+            say(f"{label}: skipping {s.id} ({str(exc)[:80]})")
+            return None
+
+    with ThreadPoolExecutor(max_workers=workers) as ex:
+        scls = list(ex.map(read_scl, candidates))
+    ranked = []
+    for s, scl in zip(candidates, scls):
+        if scl is None:
+            continue
+        valid = valid_from_scl(scl, grid.res) & mask
+        ranked.append((float(valid.sum()) / n_aoi, s, valid))
+    del scls
+    ranked.sort(key=lambda t: (-t[0], t[1].date))
+    chosen = [t for t in ranked if t[0] >= min_scene_fraction][:max_scenes]
+    chosen.sort(key=lambda t: t[1].date)
+    fractions = {t[1].id: round(t[0], 4) for t in ranked}
+    if not chosen:
+        empty = {b: np.full((h, w), np.nan, dtype=np.float32) for b in bands}
+        return Composite(empty, np.zeros((h, w), dtype=np.uint8), [], len(candidates), fractions)
+
+    scenes = [t[1] for t in chosen]
+    valid_stack = np.stack([t[2] for t in chosen])  # (n,h,w) bool
+    del ranked, chosen
+    gc.collect()
+
+    # 2) one band at a time: read -> reflectance -> mask -> strip-wise median
+    out: dict[str, np.ndarray] = {}
+    # small copies of each scene's red/green/blue (a few MB) let the report play the scenes one by one
+    step = max(1, -(-max(h, w) // frame_max_dim)) if frame_max_dim else 0
+    frames: dict[str, np.ndarray] = {}
+    for band in bands:
+        say(f"{label}: downloading + compositing band '{band}' from {len(scenes)} scenes")
+        stack = np.full((len(scenes), h, w), np.nan, dtype=np.float32)
+
+        def work(i: int, band=band, stack=stack):
+            s = scenes[i]
+            try:
+                dn = reader(s, band, grid)
+            except Exception:
+                if band in OPTIONAL_BANDS:  # leave this scene out of the optional band, keep the run going
+                    return
+                raise
+            scale, offset = s.radiometry.get(band, (1e-4, 0.0))
+            refl = to_reflectance(dn, scale, offset)
+            refl[(dn == 0) | ~valid_stack[i]] = np.nan
+            stack[i] = refl
+
+        with ThreadPoolExecutor(max_workers=min(workers, len(scenes))) as ex:
+            list(ex.map(work, range(len(scenes))))
+        if step and band in ("red", "green", "blue"):
+            frames[band] = stack[:, ::step, ::step].astype(np.float16)
+        out[band] = strip_median(stack)
+        del stack
+        gc.collect()
+
+    count = valid_stack.sum(axis=0).astype(np.uint8)
+    del valid_stack
+    # a pixel is only usable if all bands have a value
+    for b in [b for b in bands if b in OPTIONAL_BANDS]:
+        if not np.isfinite(out[b]).any():  # B12 unreadable everywhere: drop the band instead of the whole composite
+            del out[b]
+    required = [b for b in bands if b not in OPTIONAL_BANDS]
+    ok = np.ones((h, w), dtype=bool)
+    for b in required:
+        ok &= np.isfinite(out[b])
+    for b in out:
+        if b in required:
+            out[b][~ok] = np.nan
+    count[~ok] = 0
+    return Composite(out, count, scenes, len(candidates), fractions, frames, step or 1)

earthdiff/geocode.py

@@ -0,0 +1,186 @@
+"""Place-name search through OSM Nominatim, following the public usage policy
+(https://operations.osmfoundation.org/policies/nominatim/): identifying User-Agent, at most one request per second,
+cached results, no bulk use, attribution. Results are (c) OpenStreetMap contributors (ODbL)."""
+from __future__ import annotations
+
+import json
+import math
+import os
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+import httpx
+
+from . import __version__
+from .safety import NOMINATIM_HOST, clean_text
+
+NOMINATIM_URL = f"https://{NOMINATIM_HOST}/search"
+ATTRIBUTION = "Place search: (c) OpenStreetMap contributors (ODbL), via Nominatim"
+REPO_URL = "https://github.com/mveyseldelibas/earthdiff"
+
+
+class GeocodeError(RuntimeError):
+    """The place search failed (network, rate limit, bad response). The message is safe to show to the model."""
+
+
+@dataclass(frozen=True)
+class Place:
+    name: str
+    display_name: str
+    kind: str  # "class/type" as reported by OSM, e.g. "natural/water"
+    lon: float
+    lat: float
+    bbox: tuple[float, float, float, float]  # west, south, east, north
+    importance: float
+    osm: str  # "relation/123"
+
+
+def user_agent(contact: str | None = None) -> str:
+    ua = f"earthdiff-mcp/{__version__} (+{REPO_URL})"
+    if contact:
+        ua += f" contact:{clean_text(contact, 80)}"
+    return ua
+
+
+def _place_from(raw: dict[str, Any]) -> Place | None:
+    try:
+        south, north, west, east = (float(x) for x in raw["boundingbox"])
+        lon, lat = float(raw["lon"]), float(raw["lat"])
+    except (KeyError, TypeError, ValueError):
+        return None
+    vals = (south, north, west, east, lon, lat)
+    if not all(math.isfinite(v) for v in vals) or not (-90 <= south <= north <= 90 and -180 <= west <= east <= 180):
+        return None
+    display = clean_text(raw.get("display_name", ""), 240)
+    name = clean_text(raw.get("name") or display.split(",")[0], 120)
+    return Place(
+        name=name,
+        display_name=display,
+        kind=clean_text(f"{raw.get('category') or raw.get('class', '')}/{raw.get('type', '')}", 60),
+        lon=lon,
+        lat=lat,
+        bbox=(west, south, east, north),
+        importance=float(raw.get("importance") or 0.0),
+        osm=clean_text(f"{raw.get('osm_type', '')}/{raw.get('osm_id', '')}", 40),
+    )
+
+
+class Nominatim:
+    """Rate-limited, caching Nominatim client. One instance per server process."""
+
+    def __init__(
+        self,
+        contact: str | None = None,
+        cache_path: Path | None = None,
+        client: httpx.Client | None = None,
+        min_interval_s: float = 1.1,
+        max_per_hour: int = 60,
+        ttl_s: float = 30 * 86400,
+        timeout_s: float = 15.0,
+        clock: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep,
+        now: Callable[[], float] = time.time,
+    ):
+        self._client = client or httpx.Client(
+            headers={"User-Agent": user_agent(contact), "Accept": "application/json"},
+            timeout=timeout_s,
+            follow_redirects=False,
+        )
+        self._cache_path = cache_path
+        self._min_interval = min_interval_s
+        self._max_per_hour = max_per_hour
+        self._ttl = ttl_s
+        self._clock, self._sleep, self._now = clock, sleep, now
+        self._lock = threading.Lock()
+        self._last = -1e9
+        self._sent: list[float] = []
+        self._cache: dict[str, dict[str, Any]] = self._load()
+
+    # -- cache
+    def _load(self) -> dict[str, dict[str, Any]]:
+        if not self._cache_path:
+            return {}
+        try:
+            data = json.loads(Path(self._cache_path).read_text(encoding="utf-8"))
+            return data if isinstance(data, dict) else {}
+        except (OSError, ValueError):
+            return {}
+
+    def _save(self) -> None:
+        if not self._cache_path:
+            return
+        try:
+            path = Path(self._cache_path)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            if len(self._cache) > 500:  # keep the newest entries only
+                keep = sorted(self._cache.items(), key=lambda kv: kv[1].get("t", 0), reverse=True)[:400]
+                self._cache = dict(keep)
+            tmp = path.with_suffix(".tmp")
+            tmp.write_text(json.dumps(self._cache, ensure_ascii=False), encoding="utf-8")
+            os.replace(tmp, path)
+        except OSError:
+            pass  # a cache that cannot be written is not an error
+
+    @staticmethod
+    def _key(q: str, countrycodes: str | None, language: str | None, limit: int) -> str:
+        return json.dumps([q.casefold(), countrycodes or "", (language or "").casefold(), limit], ensure_ascii=False)
+
+    # -- search
+    def search(self, q: str, countrycodes: str | None = None, language: str | None = None, limit: int = 5) -> tuple[list[Place], bool]:
+        """Return ``(places, from_cache)``. Raises :class:`GeocodeError`."""
+        q = clean_text(q, 200)
+        if len(q) < 2:
+            raise GeocodeError("the place query is too short")
+        key = self._key(q, countrycodes, language, limit)
+        with self._lock:
+            hit = self._cache.get(key)
+            if hit and self._now() - float(hit.get("t", 0)) < self._ttl:
+                return [p for p in (_place_from(r) for r in hit["data"]) if p], True
+
+            t = self._clock()
+            self._sent = [x for x in self._sent if t - x < 3600]
+            if len(self._sent) >= self._max_per_hour:
+                raise GeocodeError(
+                    f"place search limit reached ({self._max_per_hour} requests per hour per server, to respect the Nominatim usage policy); "
+                    "give a bounding box instead or try again later"
+                )
+            wait = self._min_interval - (t - self._last)
+            if wait > 0:
+                self._sleep(wait)  # <= 1 request per second, process wide
+            params: dict[str, Any] = {"q": q, "format": "jsonv2", "limit": limit, "addressdetails": 0, "dedupe": 1}
+            if countrycodes:
+                params["countrycodes"] = countrycodes
+            if language:
+                params["accept-language"] = language
+            self._last = self._clock()
+            self._sent.append(self._last)
+            try:
+                resp = self._client.get(NOMINATIM_URL, params=params)
+            except httpx.HTTPError as exc:
+                raise GeocodeError(f"place search failed ({type(exc).__name__}); try again or give a bounding box") from None
+            if resp.status_code in (403, 429, 503):
+                raise GeocodeError(
+                    f"the Nominatim service refused or throttled the request (HTTP {resp.status_code}); wait a minute or give a bounding box"
+                )
+            if resp.status_code != 200:
+                raise GeocodeError(f"the Nominatim service answered HTTP {resp.status_code}")
+            try:
+                data = resp.json()
+            except ValueError:
+                raise GeocodeError("the Nominatim service returned an unreadable answer") from None
+            if not isinstance(data, list):
+                raise GeocodeError("the Nominatim service returned an unexpected answer")
+            slim = [
+                {k: r.get(k) for k in ("name", "display_name", "category", "class", "type", "lon", "lat", "boundingbox", "importance", "osm_type", "osm_id")}
+                for r in data[:limit]
+                if isinstance(r, dict)
+            ]
+            self._cache[key] = {"t": self._now(), "data": slim}
+            self._save()
+            return [p for p in (_place_from(r) for r in slim) if p], False
+
+    def close(self) -> None:
+        self._client.close()

earthdiff/history.py

@@ -0,0 +1,86 @@
+"""When did a vegetation loss happen, and what was it? Using the in-between years.
+
+Comparing only the two ends hides events that happened in between and have partly recovered since: three years after a
+wildfire the burn scar is green again in places, so the before/after dNBR is weak and the loss looks "unclear". When the
+windows are years apart earthdiff already reads one pass per in-between year (``yearly.py``); here each vegetation-loss
+polygon gets a short series of NBR, NDVI and visible brightness (before, each in-between year, after), the largest
+one-step NBR drop is taken as the event, and the cause hint is judged on that step (same rules as ``cause.classify_cause``).
+
+The result is stored on each polygon: ``event_after`` (date of the first pass that shows the loss), ``event_before``
+(the pass just before), ``event_dnbr`` (NBR drop of that step) and, when the step says so, a new ``likely_cause``.
+It is a hint like the rest: one pass per year, at the coarse frame resolution."""
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from .cause import LABELS, _bincount_mean, _summary, classify_cause
+
+
+def composite_point(kind: str, date: str, comp, step: int) -> dict[str, Any] | None:
+    """A series point from a period composite, subsampled to the frame grid."""
+    b = comp.bands
+    if "swir22" not in b or "nir" not in b:
+        return None
+    return point(kind, date, {k: b[k][::step, ::step] for k in ("red", "green", "blue", "nir", "swir22")})
+
+
+def point(kind: str, date: str, bands: dict[str, np.ndarray]) -> dict[str, Any]:
+    nir, sw2, red = bands["nir"], bands["swir22"], bands["red"]
+    with np.errstate(invalid="ignore", divide="ignore"):
+        nbr = (nir - sw2) / (nir + sw2)
+        ndvi = (nir - red) / (nir + red)
+    vis = (bands["red"] + bands["green"] + bands["blue"]) / 3.0
+    return {"kind": kind, "date": date, "nbr": nbr.astype(np.float32), "ndvi": ndvi.astype(np.float32), "vis": vis.astype(np.float32)}
+
+
+def refine_with_history(result, series: list[dict[str, Any]], step: int) -> dict[str, Any] | None:
+    """Re-judge vegetation-loss polygons on their largest one-step NBR drop. Changes features in place; returns new cause totals."""
+    series = [s for s in series if s is not None]
+    if len(series) < 3 or not any(s["kind"] == "between" for s in series):
+        return None
+    labels = result.labels[::step, ::step]
+    h, w = labels.shape
+    n = int(result.labels.max())
+    if n == 0:
+        return None
+    flat = labels.ravel()
+    sel = flat > 0
+    lab = flat[sel]
+    means = []
+    for s in series:
+        means.append({k: _bincount_mean(lab, s[k][:h, :w].ravel()[sel], n) for k in ("nbr", "ndvi", "vis")})
+    changed = 0
+    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
+        nbr = [float(m["nbr"][lid]) for m in means]
+        ok = [i for i, v in enumerate(nbr) if np.isfinite(v)]
+        if len(ok) >= 3:
+            steps = [(nbr[a] - nbr[b], a, b) for a, b in zip(ok, ok[1:])]
+            drop, a, b = max(steps)
+            if drop > 0.05:
+                p["event_before"], p["event_after"] = series[a]["date"], series[b]["date"]
+                p["event_dnbr"] = round(drop, 3)
+                end = nbr[ok[0]] - nbr[ok[-1]]
+                # only re-judge when the step is clearly larger than the end-to-end difference (the scar has faded since)
+                if drop >= max(end + 0.05, 1.25 * end):
+                    shape = result.shape_stats.get(lid, {})
+                    m = {"dnbr": drop, "vis_after": float(means[b]["vis"][lid]), "vis_delta": float(means[b]["vis"][lid] - means[a]["vis"][lid]),
+                         "rectangularity": float(shape.get("rectangularity", p.get("rectangularity", 0.0))), "area_ha": float(p["area_ha"])}
+                    label, basis = classify_cause(m)
+                    if label != p.get("likely_cause"):
+                        changed += 1
+                    p["likely_cause"] = label
+                    p["likely_cause_basis"] = f"largest one-step drop between {series[a]['date']} and {series[b]['date']}; " + "; ".join(basis)
+                    p["likely_cause_from"] = "in-between years"
+        lc = p.get("likely_cause")
+        if lc in totals:
+            totals[lc]["polygons"] += 1
+            totals[lc]["area_ha"] = round(totals[lc]["area_ha"] + p["area_ha"], 2)
+    out = _summary(totals)
+    out["from_in_between_years"] = {"series_points": [s["date"] for s in series], "relabelled_polygons": changed}
+    return out