satchange 0.1.0__py3-none-any.whl

satchange/__init__.py

@@ -0,0 +1,8 @@
+"""satchange — multipurpose satellite change detection.
+
+Map deforestation, mining, urbanisation, floods, burns, surface-water change and
+multi-epoch urban growth from free Sentinel-1/2 and Landsat data, via Google
+Earth Engine or Microsoft Planetary Computer (no account needed). Pure Python.
+"""
+
+__version__ = "0.1.0"

satchange/detect.py

@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+"""Multipurpose satellite change detection.
+
+Pick a SCENARIO and a LOCATION; the scenario selects the remote-sensing method
+(NDVI/NDBI/NDWI/NBR change, SIRAD radar, or SAR flood water). Results download
+straight to disk as a PNG quick-look, a georeferenced GeoTIFF, and a stats JSON.
+
+Examples
+--------
+    # List available scenarios
+    python3 detect.py --list
+
+    # Deforestation around a coordinate (radius 6 km)
+    python3 detect.py -s deforestation --lat -3.333 --lon 122.25 -r 6
+
+    # Same, coordinate as "lat,lon" (quote/`=` because lat is negative)
+    python3 detect.py -s mining -l=-3.333,122.25
+
+    # Flood: baseline window vs event window (both required)
+    python3 detect.py -s flood --lat 24.9 --lon 67.9 \
+        --pre 2022-06-01:2022-06-30 --post 2022-08-15:2022-09-05
+
+    # Use a named preset from sites.py instead of a coordinate
+    python3 detect.py -s mining --site konawe
+
+Outputs (per run):
+    images/<scenario>_<product>_<name>.png     quick-look
+    data/<scenario>_<product>_<name>.tif       full-resolution GeoTIFF
+    data/<scenario>_<name>_stats.json          statistics
+"""
+
+import os
+import sys
+import json
+import uuid
+import argparse
+from datetime import datetime
+
+from .gee_utils import (
+    download_png, download_geotiff, initialize_ee, square_aoi)
+from .scenarios import SCENARIOS, run_optical_change
+from .indices import (
+    INDEX_FN, BUILTUP_METHODS, THERMAL_METHODS, METHOD_DEFAULTS)
+
+# Outputs and credentials are resolved against the current working directory,
+# so an installed package writes results where the user runs it (not site-packages).
+OUTPUT_ROOT = os.path.join(os.getcwd(), "output")
+CONFIG_KEY = os.path.join(os.getcwd(), "scripts", "config", "ee-geodetic.json")
+
+
+def new_run_dir(scenario, name):
+    """Create output/<timestamp>_<scenario>_<name>_<token>/ and return it."""
+    run_id = (f"{datetime.now():%Y%m%d-%H%M%S}_{scenario}_{name}"
+              f"_{uuid.uuid4().hex[:6]}")
+    run_dir = os.path.join(OUTPUT_ROOT, run_id)
+    os.makedirs(run_dir, exist_ok=True)
+    return run_id, run_dir
+
+
+def list_outputs(run_dir):
+    """Print the run folder and everything written to it."""
+    print(f"\nAll outputs → output/{os.path.basename(run_dir)}/")
+    for f in sorted(os.listdir(run_dir)):
+        print(f"  {f}")
+
+
+def parse_period(text):
+    """'YYYY-MM-DD:YYYY-MM-DD' -> (start, end)."""
+    try:
+        start, end = text.split(":")
+        return start.strip(), end.strip()
+    except ValueError:
+        raise SystemExit(f"Bad date window '{text}'. Use START:END "
+                         "(e.g. 2023-01-01:2023-12-31).")
+
+
+def parse_location(text):
+    """'lat,lon' -> (lat, lon)."""
+    try:
+        lat, lon = (float(x) for x in text.split(","))
+        return lat, lon
+    except ValueError:
+        raise SystemExit(f"Bad location '{text}'. Use 'lat,lon' "
+                         "(e.g. -3.333,122.25).")
+
+
+def safe_name(text):
+    return (text.replace(" ", "_").replace(",", "_")
+                .replace(".", "p").replace("-", "m"))
+
+
+def print_scenarios():
+    print("Available scenarios (-s):\n")
+    for key, cfg in SCENARIOS.items():
+        print(f"  {key:<14} {cfg['label']}")
+    print(f"\nBuilt-up methods (--method) · Sentinel-2: {', '.join(BUILTUP_METHODS)}")
+    print(f"                            · Landsat (thermal, auto): {', '.join(THERMAL_METHODS)}")
+    print("\nLocation: --lat LAT --lon LON  |  -l 'lat,lon'  |  --site NAME")
+
+
+def resolve_location(args):
+    """Return (lat, lon, radius_km, name)."""
+    if args.site:
+        from .sites import get_site
+        site = get_site(["--site", args.site])
+        return site["lat"], site["lon"], site["radius_km"], args.site
+    if args.location:
+        lat, lon = parse_location(args.location)
+    elif args.lat is not None and args.lon is not None:
+        lat, lon = args.lat, args.lon
+    else:
+        raise SystemExit("Provide a location: --lat/--lon, -l 'lat,lon', "
+                         "or --site NAME. See --help.")
+    name = args.name or safe_name(f"{lat}_{lon}")
+    return lat, lon, None, name
+
+
+def build_params(scenario, args):
+    """Assemble the params dict a scenario's run() expects."""
+    cfg = SCENARIOS[scenario]
+    needs = cfg.get("needs")
+    p = {}
+
+    if needs in ("sirad", "epochs"):
+        # Both take exactly 3 date windows (R/G/B). --epochs overrides the
+        # scenario default; SIRAD stores them as sirad_periods, urban-trend as epochs.
+        default = cfg["sirad_periods"] if needs == "sirad" else cfg["epochs"]
+        windows = ([parse_period(w) for w in args.epochs.split(",")]
+                   if args.epochs else default)
+        if len(windows) != 3:
+            raise SystemExit("--epochs needs exactly 3 windows: W1,W2,W3 "
+                             "(each START:END, e.g. 2024-01-01:2024-12-31)")
+        p["sirad_periods" if needs == "sirad" else "epochs"] = windows
+        return p
+
+    # pre/post windows (optical + flood)
+    pre = parse_period(args.pre) if args.pre else cfg.get("pre")
+    post = parse_period(args.post) if args.post else cfg.get("post")
+    if needs == "pre_post_required" and (not pre or not post):
+        raise SystemExit(
+            f"Scenario '{scenario}' needs explicit windows: "
+            "--pre START:END --post START:END")
+    p["pre"], p["post"] = pre, post
+    return p
+
+
+def apply_overrides(cfg, args):
+    """Return a cfg copy with --method/--thr/--severe applied (optical only)."""
+    cfg = dict(cfg)
+    if cfg.get("method") != "optical":
+        if args.method:
+            print(f"(--method ignored — '{args.scenario}' is not index-based)")
+        return cfg
+    if args.method:
+        m = args.method.upper()
+        if m not in INDEX_FN:
+            raise SystemExit(f"Unknown --method '{args.method}'. "
+                             f"Options: {', '.join(sorted(INDEX_FN))}")
+        direction, thr, severe, vmax = METHOD_DEFAULTS[m]
+        sensor = "Landsat" if m in THERMAL_METHODS else "Sentinel-2"
+        cfg.update(index=m, direction=direction, thr=thr, severe=severe, vmax=vmax,
+                   label=f"{args.scenario.capitalize()} — {m} change ({sensor})")
+    cfg.setdefault("vmax", METHOD_DEFAULTS.get(cfg["index"], (None, 0, 0, 0.6))[3])
+    if args.thr is not None:
+        cfg["thr"] = args.thr
+    if args.severe is not None:
+        cfg["severe"] = args.severe
+    return cfg
+
+
+def _write_gee_product(prod, aoi, run_dir, common, do_map, basemap):
+    """Download one GEE product (png + tif), write its meta, optionally its map."""
+    base = f"{common['scenario']}_{prod['key']}_{common['name']}"
+    png = os.path.join(run_dir, base + ".png")
+    tif = os.path.join(run_dir, base + ".tif")
+    print(f"Downloading {prod['key']} PNG...")
+    download_png(prod["thumb"], aoi, png, vis=prod["thumb_vis"])
+    print(f"Downloading {prod['key']} GeoTIFF...")
+    tif_ok = download_geotiff(prod["tif"], aoi, tif, scale=prod.get("scale", 10))
+
+    is_rgb = "bands" in prod["thumb_vis"]
+    vis = dict(prod["thumb_vis"])
+    if not is_rgb and "label" not in vis:
+        k = prod["key"]
+        vis["label"] = ("Δ" + k[1:].upper()) if k.startswith("d") else k.upper()
+    meta = {"tif": tif, "product_key": prod["key"], "vis": vis, "is_rgb": is_rgb,
+            "metric": vis.get("label"), **common}
+    with open(os.path.join(run_dir, base + ".meta.json"), "w") as mf:
+        json.dump(meta, mf, indent=2)
+
+    if do_map and tif_ok:
+        from .mapmaker import render_map
+        render_map(meta, os.path.join(run_dir, base + "_map"), basemap=basemap)
+    elif do_map:
+        print("  (map skipped — GeoTIFF unavailable for this product)")
+
+
+def run_gee(args, cfg, lat, lon, radius, name, params, run_dir, run_id, provider, window):
+    """Run the Google Earth Engine backend and write outputs to run_dir."""
+    try:
+        import ee  # noqa: F401 — GEE backend only
+    except ImportError:
+        sys.exit("The GEE backend needs earthengine-api: "
+                 "pip install 'satchange[gee]'  (or use --backend mpc)")
+    initialize_ee(CONFIG_KEY)
+    aoi = square_aoi(lon, lat, radius)  # square clip (not a circle)
+
+    if cfg.get("method") == "optical":
+        result = run_optical_change(aoi, params, cfg["index"], cfg["direction"],
+                                    cfg["thr"], cfg["severe"], cfg.get("vmax", 0.6))
+    else:
+        result = cfg["run"](aoi, params)
+
+    common = {"scenario": args.scenario, "label": cfg["label"], "name": name,
+              "run_id": run_id, "source": "Google Earth Engine", "provider": provider,
+              "lat": lat, "lon": lon, "radius_km": radius, "window": window,
+              "interpretation": result.get("interpretation",
+                                           cfg.get("interpretation", "")),
+              "stats": result["stats"]}
+    for prod in result["products"]:
+        _write_gee_product(prod, aoi, run_dir, common, args.map, args.basemap)
+
+    stats = {"run_id": run_id, "scenario": args.scenario,
+             "location": {"lat": lat, "lon": lon},
+             "radius_km": radius, "results": result["stats"]}
+    with open(os.path.join(run_dir, "stats.json"), "w") as f:
+        json.dump(stats, f, indent=2)
+    print("\n=== Results ===")
+    print(json.dumps(result["stats"], indent=2))
+    print(f"\n{result.get('interpretation', cfg.get('interpretation', ''))}")
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Multipurpose satellite change detection.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__)
+    ap.add_argument("-s", "--scenario", choices=list(SCENARIOS))
+    ap.add_argument("-l", "--location", help="'lat,lon' (use -l=-3.3,122.2 if lat<0)")
+    ap.add_argument("--lat", type=float)
+    ap.add_argument("--lon", type=float)
+    ap.add_argument("--site", help="named preset from sites.py")
+    ap.add_argument("-r", "--radius", type=float, help="AOI radius in km")
+    ap.add_argument("--pre", help="baseline window START:END")
+    ap.add_argument("--post", help="recent/event window START:END")
+    ap.add_argument("--epochs", help="three date windows W1,W2,W3 (each "
+                    "START:END) for urban-trend epochs OR mining SIRAD periods "
+                    "(R/G/B), e.g. 2024-01-01:2024-12-31,2025-...,2026-...")
+    ap.add_argument("-n", "--name", help="output label (default from coords)")
+    ap.add_argument("--map", action="store_true",
+                    help="also render an A4 map layout (PDF + PNG) per product")
+    ap.add_argument("--basemap", choices=["osm", "gray", "none"], default="osm",
+                    help="map basemap (default osm)")
+    ap.add_argument("--backend", choices=["gee", "mpc"], default="gee",
+                    help="data backend: gee (Earth Engine) or mpc "
+                         "(Microsoft Planetary Computer, no account needed)")
+    ap.add_argument("--method", help="override the index for optical scenarios "
+                    "(e.g. urbanization: NDBI|UI|BU|IBI; also NDVI/NDWI/NBR)")
+    ap.add_argument("--thr", type=float, help="override the 'affected' threshold")
+    ap.add_argument("--severe", type=float, help="override the 'severe' threshold")
+    ap.add_argument("--list", action="store_true", help="list scenarios and exit")
+    args = ap.parse_args()
+
+    if args.list or not args.scenario:
+        print_scenarios()
+        return
+
+    cfg = SCENARIOS[args.scenario]
+    lat, lon, site_radius, name = resolve_location(args)
+    radius = args.radius or site_radius or cfg["radius"]
+    params = build_params(args.scenario, args)
+
+    cfg = apply_overrides(cfg, args)
+
+    print(f"=== Change detection: {args.scenario} ===")
+    print(f"{cfg['label']}")
+    print(f"Location: {lat}, {lon}  radius {radius} km  [{name}]\n")
+
+    # temporal window label for the map subtitle (both backends)
+    if params.get("pre"):
+        window = f"{params['pre'][0]} → {params['post'][1]}"
+    elif params.get("sirad_periods"):
+        sp = params["sirad_periods"]
+        window = f"{sp[0][0]} → {sp[-1][1]}"
+    elif params.get("epochs"):
+        ep = params["epochs"]
+        window = " · ".join(w[0][:4] for w in ep)
+    else:
+        window = None
+
+    landsat = cfg.get("method") == "trend" or cfg.get("index") in THERMAL_METHODS
+    provider = "Landsat C2-L2 (USGS/NASA)" if landsat else "Copernicus Sentinel (ESA)"
+
+    run_id, run_dir = new_run_dir(args.scenario, name)
+    print(f"Output folder: output/{run_id}/\n")
+
+    if args.backend == "mpc":
+        from .mpc_backend import run_mpc
+        run_mpc(args.scenario, cfg, lat, lon, radius, name, params,
+                run_dir, run_id, window, provider,
+                do_map=args.map, basemap=args.basemap)
+        list_outputs(run_dir)
+        return
+
+    run_gee(args, cfg, lat, lon, radius, name, params,
+            run_dir, run_id, provider, window)
+    list_outputs(run_dir)
+
+
+if __name__ == "__main__":
+    main()

satchange/gee_utils.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Helpers to download Earth Engine results directly to local disk.
+
+Two ways to get a result out of GEE:
+  * download_png()     — a quick-look RGB thumbnail (capped resolution)
+  * download_geotiff() — the full-resolution, georeferenced GeoTIFF you can
+                         open in QGIS/rasterio. Uses ee.Image.getDownloadURL,
+                         which has a per-request size limit (~32-48 MB); for
+                         very large AOIs, fall back to a Drive export.
+"""
+
+import os
+import sys
+import requests
+
+
+def _fetch(url, out_path):
+    resp = requests.get(url, stream=True)
+    resp.raise_for_status()
+    os.makedirs(os.path.dirname(out_path), exist_ok=True)
+    with open(out_path, "wb") as f:
+        for chunk in resp.iter_content(chunk_size=8192):
+            f.write(chunk)
+    return out_path
+
+
+def download_png(image, region, out_path, dimensions="1920x1920", vis=None):
+    """Download an RGB quick-look PNG thumbnail."""
+    params = {"region": region, "dimensions": dimensions, "format": "png"}
+    if vis:
+        params.update(vis)
+    _fetch(image.getThumbURL(params), out_path)
+    print(f"Saved: {os.path.normpath(out_path)}")
+    return out_path
+
+
+def download_geotiff(image, region, out_path, scale=10, max_scale_mult=16):
+    """Download a full-resolution single-file GeoTIFF.
+
+    Earth Engine's direct download has a per-request size/compute limit, so a
+    large AOI can 400. Retry at progressively coarser scale until it fits.
+    Returns the path on success, or None if it fails even coarsened.
+    """
+    s, mult = scale, 1
+    last_err = None
+    while mult <= max_scale_mult:
+        try:
+            url = image.getDownloadURL({
+                "region": region, "scale": s,
+                "format": "GEO_TIFF", "filePerBand": False,
+            })
+            _fetch(url, out_path)  # the pixel fetch can also fail for large AOIs
+            size_mb = os.path.getsize(out_path) / 1e6
+            note = f" (coarsened to {s:.0f} m to fit)" if s != scale else ""
+            print(f"Saved: {os.path.normpath(out_path)} ({size_mb:.1f} MB GeoTIFF){note}")
+            return out_path
+        except Exception as e:  # noqa: BLE001 — retry coarser
+            last_err = e
+            mult *= 2
+            s = scale * mult
+    print(f"NOTE: GeoTIFF download failed even at {scale * max_scale_mult:.0f} m "
+          f"({last_err}).")
+    print("      Reduce --radius, or add --drive to export the full-res GeoTIFF "
+          "to Google Drive.")
+    return None
+
+
+def wants_drive_export(argv=None):
+    """True if the user passed --drive (opt-in full-res Drive export)."""
+    argv = sys.argv if argv is None else argv
+    return "--drive" in argv
+
+
+def square_aoi(lon, lat, radius_km):
+    """Square AOI centred on (lon, lat), half-side = radius_km.
+
+    Side length = 2 * radius_km (the square that circumscribes the old circle),
+    axis-aligned in lon/lat. Use instead of Point.buffer() (a circle).
+    """
+    import ee
+    return ee.Geometry.Point([lon, lat]).buffer(radius_km * 1000).bounds()
+
+
+def mask_s2_clouds(img):
+    """Mask cloud / shadow / cirrus / snow using Sentinel-2 SCL band.
+
+    Applied per pixel so a median of many scenes yields a near cloud-free
+    composite even when individual scenes are partly cloudy.
+    """
+    scl = img.select("SCL")
+    keep = (scl.neq(3)       # cloud shadow
+            .And(scl.neq(8))    # cloud medium probability
+            .And(scl.neq(9))    # cloud high probability
+            .And(scl.neq(10))   # thin cirrus
+            .And(scl.neq(11)))  # snow / ice
+    return img.updateMask(keep)
+
+
+def initialize_ee(config_key=None):
+    """Initialise Earth Engine with a service-account key if one is present."""
+    import json
+    import ee
+
+    candidates = [
+        p for p in (config_key,
+                    os.path.expanduser("~/.config/earthengine/ee-geodetic.json"))
+        if p
+    ]
+    for key_path in candidates:
+        if os.path.exists(key_path):
+            with open(key_path) as f:
+                email = json.load(f).get("client_email")
+            ee.Initialize(ee.ServiceAccountCredentials(email, key_file=key_path))
+            print(f"GEE: service account {email}")
+            return
+    ee.Initialize()  # falls back to `earthengine authenticate`
+    print("GEE: user credentials (earthengine authenticate)")

satchange/indices.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Spectral indices, composites, and Sentinel-1 helpers for change detection.
+
+All functions operate server-side in Google Earth Engine. Sentinel-2 composites
+mask cloud per pixel (SCL) and take a median over many scenes, so the result is
+near cloud-free regardless of any single scene's cloud cover.
+"""
+
+try:
+    import ee  # only needed for the GEE backend
+except ImportError:
+    ee = None
+from .gee_utils import mask_s2_clouds
+
+S2 = "COPERNICUS/S2_SR_HARMONIZED"
+S1 = "COPERNICUS/S1_GRD"
+ORBITS = ("ASCENDING", "DESCENDING")
+
+
+def s2_median(aoi, start, end, scene_cloud_max=60):
+    """Cloud-masked median Sentinel-2 SR composite over a date window.
+
+    Returns (image, scene_count). scene_count is a Python int.
+    """
+    coll = (ee.ImageCollection(S2)
+            .filterBounds(aoi)
+            .filterDate(start, end)
+            .filter(ee.Filter.lte("CLOUDY_PIXEL_PERCENTAGE", scene_cloud_max))
+            .map(mask_s2_clouds))
+    return coll.median(), coll.size().getInfo()
+
+
+# --- Normalised-difference indices on a Sentinel-2 SR image ---
+def ndvi(img):  # vegetation
+    return img.normalizedDifference(["B8", "B4"]).rename("NDVI")
+
+
+def ndbi(img):  # built-up
+    return img.normalizedDifference(["B11", "B8"]).rename("NDBI")
+
+
+def ndwi(img):  # open water (McFeeters)
+    return img.normalizedDifference(["B3", "B8"]).rename("NDWI")
+
+
+def nbr(img):   # burn
+    return img.normalizedDifference(["B8", "B12"]).rename("NBR")
+
+
+# --- Alternative built-up indices (all computable on Sentinel-2) ---
+def ui(img):    # Urban Index — (SWIR2-NIR)/(SWIR2+NIR)
+    return img.normalizedDifference(["B12", "B8"]).rename("UI")
+
+
+def _savi(img, L=0.5):  # Soil-Adjusted Vegetation Index (reflectance-scaled)
+    nir = img.select("B8").divide(10000)
+    red = img.select("B4").divide(10000)
+    return nir.subtract(red).multiply(1 + L).divide(nir.add(red).add(L))
+
+
+def bu(img):    # Built-Up index = NDBI - NDVI (Kawamura 1996)
+    return ndbi(img).subtract(ndvi(img)).rename("BU")
+
+
+def ibi(img):   # Index-Based Built-up Index (Xu 2008)
+    nd = img.normalizedDifference(["B11", "B8"])            # NDBI
+    mndwi = img.normalizedDifference(["B3", "B11"])         # water
+    x = _savi(img).add(mndwi).divide(2)
+    # The ratio form is unstable where the denominator crosses zero; clamp it.
+    return nd.subtract(x).divide(nd.add(x)).clamp(-1, 1).rename("IBI")
+
+
+INDEX_FN = {"NDVI": ndvi, "NDBI": ndbi, "NDWI": ndwi, "NBR": nbr,
+            "UI": ui, "BU": bu, "IBI": ibi}
+# Interchangeable built-up methods for the urbanization scenario (Sentinel-2).
+# NDISI/EBBI need a thermal band (Landsat), so they are NOT listed here.
+BUILTUP_METHODS = ["NDBI", "UI", "BU", "IBI"]
+
+# Per-method change-detection defaults: (direction, affected_thr, severe_thr, vmax).
+# Different indices have different ranges, so each needs its own thresholds.
+METHOD_DEFAULTS = {
+    "NDVI": ("loss", -0.15, -0.30, 0.6),
+    "NDBI": ("gain", 0.10, 0.20, 0.5),
+    "UI":   ("gain", 0.08, 0.18, 0.5),
+    "BU":   ("gain", 0.10, 0.25, 0.8),
+    "IBI":  ("gain", 0.10, 0.25, 1.0),
+    "NDWI": ("gain", 0.10, 0.25, 0.6),
+    "NBR":  ("loss", -0.10, -0.27, 0.6),
+}
+
+
+# --- Landsat 8/9 Collection-2 Level-2 (adds a thermal band for NDISI/EBBI) ---
+L8_COL, L9_COL = "LANDSAT/LC08/C02/T1_L2", "LANDSAT/LC09/C02/T1_L2"
+
+
+def _l2_prep(img):
+    """Scale a Landsat C2-L2 scene to reflectance + °C and mask clouds."""
+    qa = img.select("QA_PIXEL")
+    clear = qa.bitwiseAnd((1 << 0) | (1 << 1) | (1 << 2) | (1 << 3) | (1 << 4)).eq(0)
+    opt = (img.select(["SR_B3", "SR_B4", "SR_B5", "SR_B6", "SR_B7"])
+           .multiply(0.0000275).add(-0.2))
+    tir = img.select("ST_B10").multiply(0.00341802).add(149.0).subtract(273.15)
+    return (opt.addBands(tir)
+               .rename(["GREEN", "RED", "NIR", "SWIR1", "SWIR2", "TIR"])
+               .updateMask(clear))
+
+
+def l2_median(aoi, start, end, cloud_max=60):
+    """Cloud-masked median Landsat 8/9 composite. Returns (image, scene_count)."""
+    col = (ee.ImageCollection(L8_COL).merge(ee.ImageCollection(L9_COL))
+           .filterBounds(aoi).filterDate(start, end)
+           .filter(ee.Filter.lt("CLOUD_COVER", cloud_max)).map(_l2_prep))
+    return col.median(), col.size().getInfo()
+
+
+def _prep_l_sr(img, bands):
+    """Scale a Landsat C2-L2 scene to surface reflectance (no thermal), masked."""
+    qa = img.select("QA_PIXEL")
+    clear = qa.bitwiseAnd((1 << 0) | (1 << 1) | (1 << 2) | (1 << 3) | (1 << 4)).eq(0)
+    opt = img.select(bands).multiply(0.0000275).add(-0.2)
+    return opt.rename(["GREEN", "RED", "NIR", "SWIR1", "SWIR2"]).updateMask(clear)
+
+
+def l_sr_median(aoi, start, end, cloud_max=60):
+    """Median Landsat surface-reflectance composite (archive back to 1984).
+
+    Uses Landsat 5 (TM) and 8/9 (OLI); Landsat 7 is EXCLUDED because its
+    Scan Line Corrector failed in 2003 (SLC-off gaps stripe every scene).
+    Uniform band naming across sensors so historical epochs (e.g. 2010) work.
+    """
+    tm = (ee.ImageCollection("LANDSAT/LT05/C02/T1_L2")  # L5 TM (no SLC-off; ends 2011)
+          .filterBounds(aoi).filterDate(start, end)
+          .filter(ee.Filter.lt("CLOUD_COVER", cloud_max))
+          .map(lambda i: _prep_l_sr(i, ["SR_B2", "SR_B3", "SR_B4", "SR_B5", "SR_B7"])))
+    oli = (ee.ImageCollection("LANDSAT/LC08/C02/T1_L2")
+           .merge(ee.ImageCollection("LANDSAT/LC09/C02/T1_L2"))
+           .filterBounds(aoi).filterDate(start, end)
+           .filter(ee.Filter.lt("CLOUD_COVER", cloud_max))
+           .map(lambda i: _prep_l_sr(i, ["SR_B3", "SR_B4", "SR_B5", "SR_B6", "SR_B7"])))
+    col = tm.merge(oli)
+    return col.median(), col.size().getInfo()
+
+
+def _norm01(band, lo, hi):
+    return band.subtract(lo).divide(hi - lo).clamp(0, 1)
+
+
+def ndisi(img):   # Normalized Difference Impervious Surface Index (Xu 2010)
+    tir = _norm01(img.select("TIR"), 0, 50)                 # °C -> [0,1]
+    nir = img.select("NIR").clamp(0, 1)
+    swir1 = img.select("SWIR1").clamp(0, 1)
+    mndwi = img.normalizedDifference(["GREEN", "SWIR1"]).add(1).divide(2)  # ->[0,1]
+    x = mndwi.add(nir).add(swir1).divide(3)
+    return tir.subtract(x).divide(tir.add(x)).clamp(-1, 1).rename("NDISI")
+
+
+def ebbi(img):    # Enhanced Built-up & Bareness Index (As-syakur 2012), x100
+    swir1, nir, tir = img.select("SWIR1"), img.select("NIR"), img.select("TIR")
+    denom = swir1.add(tir).max(1e-6).sqrt().multiply(10)
+    return swir1.subtract(nir).divide(denom).multiply(100).rename("EBBI")
+
+
+INDEX_FN.update({"NDISI": ndisi, "EBBI": ebbi})
+
+# Which sensor each index needs. Thermal indices require Landsat (not Sentinel-2).
+SENSOR = {k: "S2" for k in ("NDVI", "NDBI", "NDWI", "NBR", "UI", "BU", "IBI")}
+SENSOR.update({"NDISI": "L8", "EBBI": "L8"})
+THERMAL_METHODS = ["NDISI", "EBBI"]  # Landsat-only built-up/impervious methods
+
+METHOD_DEFAULTS.update({
+    "NDISI": ("gain", 0.05, 0.12, 0.5),
+    "EBBI": ("gain", 0.10, 0.25, 1.0),
+})
+
+
+# --- Sentinel-1 SAR helpers ---
+def s1(aoi, start, end, orbit, pol):
+    """Sentinel-1 IW collection for one polarisation and orbit direction."""
+    return (ee.ImageCollection(S1)
+            .filterBounds(aoi)
+            .filterDate(start, end)
+            .filter(ee.Filter.listContains("transmitterReceiverPolarisation", pol))
+            .filter(ee.Filter.eq("instrumentMode", "IW"))
+            .filter(ee.Filter.eq("orbitProperties_pass", orbit))
+            .select(pol))
+
+
+def best_orbit(aoi, periods, pol="VH", forced=None):
+    """Pick the orbit direction (ASC/DESC) that has imagery in every period.
+
+    `periods` is a list of (start, end) tuples. Returns (orbit, covered, counts).
+    """
+    orbits = [forced] if forced else list(ORBITS)
+    best = None  # (covered, total, orbit, counts)
+    for orbit in orbits:
+        counts = [s1(aoi, s, e, orbit, pol).size().getInfo() for (s, e) in periods]
+        cand = (all(c > 0 for c in counts), sum(counts), orbit, counts)
+        if best is None or cand[:2] > best[:2]:
+            best = cand
+    covered, _total, orbit, counts = best
+    return orbit, covered, counts