lstcalc 0.1.0__py3-none-any.whl

lstcalc/__init__.py

@@ -0,0 +1,117 @@
+"""lstcalc: land surface temperature and urban heat island metrics from Landsat 8/9.
+
+Quick start::
+
+    import numpy as np
+    from lstcalc import parse_mtl, lst_from_level1, suhi_intensity
+
+    mtl = parse_mtl(open("LC08_..._MTL.txt").read())
+    result = lst_from_level1(b10, mtl, red_dn=b4, nir_dn=b5, water_vapour=1.2)
+    print(np.nanmean(result.lst_celsius))
+    print(suhi_intensity(result.lst, urban_mask, rural_mask).intensity)
+"""
+
+from ._version import __version__
+from .emissivity import (
+    EmissivityParams,
+    emissivity_ndvi_threshold,
+    fractional_vegetation_cover,
+    ndvi,
+)
+from .errors import LstcalcError, MetadataError, OptionalDependencyError
+from .lst import (
+    B_GAMMA_TIRS1,
+    B_GAMMA_TIRS2,
+    PLANCK_C2_UM_K,
+    SC_COEFFS_TIRS1,
+    WAVELENGTH_TIRS1_UM,
+    WAVELENGTH_TIRS2_UM,
+    atmospheric_functions,
+    atmospheric_functions_from_parameters,
+    planck_lst,
+    single_channel_lst,
+)
+from .mtl import MTL, parse_mtl, read_mtl
+from .pipeline import METHODS, LSTResult, lst_from_level1, lst_from_level2
+from .radiometry import (
+    L2_SR_ADD,
+    L2_SR_MULT,
+    L2_ST_ADD,
+    L2_ST_MULT,
+    S2_BOA_ADD_OFFSET,
+    S2_QUANTIFICATION_VALUE,
+    THERMAL_CONSTANTS,
+    block_mean,
+    brightness_temperature,
+    celsius_to_kelvin,
+    dn_to_radiance,
+    dn_to_toa_reflectance,
+    kelvin_to_celsius,
+    l2_surface_reflectance,
+    l2_surface_temperature,
+    sentinel2_reflectance,
+)
+from .uhi import (
+    UTFVI_LABELS,
+    UTFVI_THRESHOLDS,
+    SUHIResult,
+    ZoneStats,
+    classify_utfvi,
+    hotspots,
+    suhi_intensity,
+    utfvi,
+    zonal_statistics,
+)
+
+__all__ = [
+    "B_GAMMA_TIRS1",
+    "B_GAMMA_TIRS2",
+    "L2_SR_ADD",
+    "L2_SR_MULT",
+    "L2_ST_ADD",
+    "L2_ST_MULT",
+    "METHODS",
+    "MTL",
+    "PLANCK_C2_UM_K",
+    "S2_BOA_ADD_OFFSET",
+    "S2_QUANTIFICATION_VALUE",
+    "SC_COEFFS_TIRS1",
+    "THERMAL_CONSTANTS",
+    "UTFVI_LABELS",
+    "UTFVI_THRESHOLDS",
+    "WAVELENGTH_TIRS1_UM",
+    "WAVELENGTH_TIRS2_UM",
+    "EmissivityParams",
+    "LSTResult",
+    "LstcalcError",
+    "MetadataError",
+    "OptionalDependencyError",
+    "SUHIResult",
+    "ZoneStats",
+    "__version__",
+    "atmospheric_functions",
+    "atmospheric_functions_from_parameters",
+    "block_mean",
+    "brightness_temperature",
+    "celsius_to_kelvin",
+    "classify_utfvi",
+    "dn_to_radiance",
+    "dn_to_toa_reflectance",
+    "emissivity_ndvi_threshold",
+    "fractional_vegetation_cover",
+    "hotspots",
+    "kelvin_to_celsius",
+    "l2_surface_reflectance",
+    "l2_surface_temperature",
+    "lst_from_level1",
+    "lst_from_level2",
+    "ndvi",
+    "parse_mtl",
+    "planck_lst",
+    "read_mtl",
+    "sentinel2_reflectance",
+    "single_channel_lst",
+    "suhi_intensity",
+    "utfvi",
+    "zonal_statistics",
+]

lstcalc/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m lstcalc``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

lstcalc/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

lstcalc/cli.py

@@ -0,0 +1,212 @@
+"""Command-line interface: ``lstcalc mtl|scene|suhi|utfvi|zonal``.
+
+``mtl`` works with the core install; the raster commands need ``lstcalc[raster]``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+import numpy as np
+
+from . import io as rio
+from ._version import __version__
+from .errors import LstcalcError
+from .mtl import read_mtl
+from .pipeline import lst_from_level1, lst_from_level2
+from .uhi import classify_utfvi, hotspots, suhi_intensity, utfvi, zonal_statistics
+
+__all__ = ["build_parser", "main"]
+
+
+def _stats(values: np.ndarray) -> Dict[str, Any]:
+    finite = values[np.isfinite(values)]
+    if finite.size == 0:
+        return {"count": 0}
+    return {
+        "count": int(finite.size),
+        "mean": round(float(finite.mean()), 4),
+        "std": round(float(finite.std()), 4),
+        "min": round(float(finite.min()), 4),
+        "max": round(float(finite.max()), 4),
+    }
+
+
+def _cmd_mtl(args: argparse.Namespace) -> int:
+    print(json.dumps(read_mtl(args.path).summary(), indent=2))
+    return 0
+
+
+def _resolve_method(args: argparse.Namespace, folder: Path, mtl: Any) -> str:
+    if args.method != "auto":
+        return str(args.method)
+    try:
+        rio.find_band_file(folder, "ST_B10", mtl)
+        return "level2"
+    except FileNotFoundError:
+        pass
+    return "single_channel" if args.water_vapour is not None else "planck"
+
+
+def _cmd_scene(args: argparse.Namespace) -> int:
+    folder = Path(args.folder)
+    mtl = rio.load_scene_mtl(folder)
+    method = _resolve_method(args, folder, mtl)
+    extra: Dict[str, Any] = {}
+    if method == "level2":
+        st, profile = rio.read_band(rio.find_band_file(folder, "ST_B10", mtl))
+        lst = lst_from_level2(st, mtl)
+    else:
+        thermal, profile = rio.read_band(rio.find_band_file(folder, f"B{args.band}", mtl))
+        red, _ = rio.read_band(rio.find_band_file(folder, "B4", mtl))
+        ndvi = None
+        nir = None
+        if args.ndvi:
+            ndvi, _ = rio.read_band(args.ndvi)
+        else:
+            nir, _ = rio.read_band(rio.find_band_file(folder, "B5", mtl))
+        result = lst_from_level1(
+            thermal,
+            mtl,
+            red_dn=red,
+            nir_dn=nir,
+            ndvi=ndvi,
+            method=method,
+            water_vapour=args.water_vapour,
+            thermal_band=args.band,
+        )
+        lst = result.lst
+        if args.emissivity_out:
+            rio.write_band(args.emissivity_out, result.emissivity, profile)
+            extra["emissivity_out"] = str(args.emissivity_out)
+    unit = "K"
+    if args.celsius:
+        lst = lst - 273.15
+        unit = "degC"
+    rio.write_band(args.out, lst, profile)
+    report = {"method": method, "unit": unit, "out": str(args.out), **_stats(lst), **extra}
+    print(json.dumps(report, indent=2))
+    return 0
+
+
+def _cmd_suhi(args: argparse.Namespace) -> int:
+    lst, _ = rio.read_band(args.lst)
+    urban, _ = rio.read_band(args.urban)
+    rural, _ = rio.read_band(args.rural)
+    lst = np.asarray(lst, dtype=np.float64)
+    if args.nodata is not None:
+        lst[lst == args.nodata] = np.nan
+    print(json.dumps(suhi_intensity(lst, urban > 0, rural > 0).to_dict(), indent=2))
+    return 0
+
+
+def _cmd_utfvi(args: argparse.Namespace) -> int:
+    lst, profile = rio.read_band(args.lst)
+    lst = np.asarray(lst, dtype=np.float64)
+    if args.nodata is not None:
+        lst[lst == args.nodata] = np.nan
+    if args.celsius_input:
+        lst = lst + 273.15
+    index = utfvi(lst)
+    classes = classify_utfvi(index).astype(np.float64)
+    classes[classes < 0] = np.nan
+    rio.write_band(args.out, classes, profile)
+    report: Dict[str, Any] = {"out": str(args.out), "utfvi": _stats(index)}
+    counts = {int(c): int((classes == c).sum()) for c in range(6)}
+    report["class_counts"] = counts
+    if args.hotspots_out:
+        hot = hotspots(lst, k=args.k).astype(np.float64)
+        rio.write_band(args.hotspots_out, hot, profile)
+        report["hotspot_pixels"] = int(hot.sum())
+    print(json.dumps(report, indent=2))
+    return 0
+
+
+def _cmd_zonal(args: argparse.Namespace) -> int:
+    values, _ = rio.read_band(args.values)
+    labels, _ = rio.read_band(args.labels)
+    values = np.asarray(values, dtype=np.float64)
+    if args.nodata is not None:
+        values[values == args.nodata] = np.nan
+    stats = zonal_statistics(values, labels)
+    rows: List[Dict[str, Any]] = [s.to_dict() for s in stats.values()]
+    if args.csv:
+        with open(args.csv, "w", newline="", encoding="utf-8") as fh:
+            writer = csv.DictWriter(fh, fieldnames=["label", "count", "mean", "std", "min", "max"])
+            writer.writeheader()
+            writer.writerows(rows)
+    print(json.dumps(rows, indent=2))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="lstcalc",
+        description="Land surface temperature and urban heat island metrics from Landsat 8/9.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("mtl", help="print LST-relevant coefficients from an MTL file as JSON")
+    p.add_argument("path", type=Path)
+    p.set_defaults(func=_cmd_mtl)
+
+    p = sub.add_parser("scene", help="compute LST for a Landsat scene folder (needs rasterio)")
+    p.add_argument("folder", type=Path)
+    p.add_argument("--out", type=Path, required=True, help="output GeoTIFF")
+    p.add_argument(
+        "--method",
+        choices=("auto", "single_channel", "planck", "level2"),
+        default="auto",
+        help="auto: level2 if ST_B10 exists, else single_channel with --water-vapour, else planck",
+    )
+    p.add_argument("--water-vapour", type=float, default=None, help="g cm-2")
+    p.add_argument("--band", type=int, choices=(10, 11), default=10)
+    p.add_argument("--ndvi", type=Path, default=None, help="external NDVI raster, same grid")
+    p.add_argument("--emissivity-out", type=Path, default=None)
+    p.add_argument("--celsius", action="store_true", help="write degrees Celsius")
+    p.set_defaults(func=_cmd_scene)
+
+    p = sub.add_parser("suhi", help="SUHI intensity from LST and urban/rural mask rasters")
+    p.add_argument("lst", type=Path)
+    p.add_argument("--urban", type=Path, required=True)
+    p.add_argument("--rural", type=Path, required=True)
+    p.add_argument("--nodata", type=float, default=None)
+    p.set_defaults(func=_cmd_suhi)
+
+    p = sub.add_parser("utfvi", help="UTFVI classes and optional hot-spot map")
+    p.add_argument("lst", type=Path)
+    p.add_argument("--out", type=Path, required=True)
+    p.add_argument("--hotspots-out", type=Path, default=None)
+    p.add_argument("--k", type=float, default=2.0, help="hot spot: mean + k * std")
+    p.add_argument("--celsius-input", action="store_true", help="input LST is in degC")
+    p.add_argument("--nodata", type=float, default=None)
+    p.set_defaults(func=_cmd_utfvi)
+
+    p = sub.add_parser("zonal", help="zonal statistics of a raster by a label raster")
+    p.add_argument("values", type=Path)
+    p.add_argument("--labels", type=Path, required=True)
+    p.add_argument("--csv", type=Path, default=None)
+    p.add_argument("--nodata", type=float, default=None)
+    p.set_defaults(func=_cmd_zonal)
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Entry point for the ``lstcalc`` console script."""
+    args = build_parser().parse_args(argv)
+    try:
+        return int(args.func(args))
+    except (LstcalcError, FileNotFoundError, ValueError) as exc:
+        print(f"lstcalc: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

lstcalc/emissivity.py

@@ -0,0 +1,138 @@
+"""NDVI, fractional vegetation cover and land surface emissivity (NDVI threshold method).
+
+Primary source (checked against the paper's text):
+    Sobrino, J. A., Jimenez-Munoz, J. C., & Paolini, L. (2004). Land surface temperature
+    retrieval from LANDSAT TM 5. *Remote Sensing of Environment*, 90(4), 434-440.
+    https://doi.org/10.1016/j.rse.2004.02.003
+
+    * NDVI < NDVI_s (0.2): bare soil, emissivity from red reflectance (the paper gives no
+      coefficients for this branch; see :class:`EmissivityParams`).
+    * NDVI > NDVI_v (0.5): fully vegetated, emissivity 0.99.
+    * otherwise: ``e = e_v * Pv + e_s * (1 - Pv) + de`` with
+      ``de = (1 - e_s) * (1 - Pv) * F * e_v`` and ``F = 0.55`` (eqs. 8 and 10), and
+      ``Pv = ((NDVI - NDVI_min) / (NDVI_max - NDVI_min)) ** 2`` (Carlson & Ripley 1997, eq. 9).
+    * With ``e_s = 0.97``, ``e_v = 0.99`` this reduces to ``e = 0.004 * Pv + 0.986`` (eq. 13).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+__all__ = [
+    "EmissivityParams",
+    "emissivity_ndvi_threshold",
+    "fractional_vegetation_cover",
+    "ndvi",
+]
+
+FloatArray = NDArray[np.float64]
+
+
+def ndvi(nir: ArrayLike, red: ArrayLike) -> FloatArray:
+    """Normalised difference vegetation index ``(NIR - Red) / (NIR + Red)``.
+
+    Works with Landsat 8/9 (B5, B4) or Sentinel-2 (B8, B4) reflectances. Pixels where
+    ``NIR + Red == 0`` or where an input is NaN return NaN.
+    """
+    n = np.asarray(nir, dtype=np.float64)
+    r = np.asarray(red, dtype=np.float64)
+    total = n + r
+    with np.errstate(divide="ignore", invalid="ignore"):
+        out: FloatArray = np.where(total != 0, (n - r) / total, np.nan)
+    return out
+
+
+def fractional_vegetation_cover(
+    ndvi_values: ArrayLike, ndvi_soil: float = 0.2, ndvi_veg: float = 0.5
+) -> FloatArray:
+    """Proportion of vegetation ``Pv = ((NDVI - NDVI_s) / (NDVI_v - NDVI_s))**2``, clipped to [0, 1].
+
+    Defaults follow Sobrino et al. (2004): ``NDVI_s = 0.2``, ``NDVI_v = 0.5``. Scene-based
+    thresholds (e.g. NDVI percentiles) can be passed instead.
+    """
+    if ndvi_veg <= ndvi_soil:
+        raise ValueError("ndvi_veg must be greater than ndvi_soil")
+    v = np.asarray(ndvi_values, dtype=np.float64)
+    scaled = np.clip((v - ndvi_soil) / (ndvi_veg - ndvi_soil), 0.0, 1.0)
+    out: FloatArray = scaled**2
+    return out
+
+
+@dataclass(frozen=True)
+class EmissivityParams:
+    """Parameters of the NDVI threshold method. All values are overridable.
+
+    Attributes:
+        ndvi_soil: NDVI below which a pixel is bare soil (Sobrino et al. 2004: 0.2).
+        ndvi_veg: NDVI above which a pixel is fully vegetated (Sobrino et al. 2004: 0.5).
+        emissivity_soil: Soil emissivity ``e_s`` (Sobrino et al. 2004, TM6: 0.97).
+        emissivity_veg: Vegetation emissivity ``e_v`` (Sobrino et al. 2004, TM6: 0.99).
+        shape_factor: Geometrical factor ``F`` of the cavity term (Sobrino et al. 2004: 0.55).
+        soil_red_coeffs: Optional ``(a, b)`` so that bare-soil emissivity is
+            ``a + b * rho_red``. When ``None`` (default) bare soil gets ``emissivity_soil``.
+            A commonly quoted TM6 pair is ``(0.979, -0.035)`` (Sobrino et al. 2008, IEEE
+            TGRS 46(2)); it is NOT verified in this release and not used by default.
+        water_emissivity: If given, pixels with ``NDVI < water_ndvi`` get this emissivity
+            (0.991 is often used for water; NOT verified, so not applied by default).
+        water_ndvi: NDVI threshold for water when ``water_emissivity`` is set.
+
+    The defaults reproduce the TM6 calibration of the paper. For Landsat 8/9 TIRS band 10
+    users often keep these values; supply band-specific emissivities if you have them.
+    """
+
+    ndvi_soil: float = 0.2
+    ndvi_veg: float = 0.5
+    emissivity_soil: float = 0.97
+    emissivity_veg: float = 0.99
+    shape_factor: float = 0.55
+    soil_red_coeffs: Optional[Tuple[float, float]] = None
+    water_emissivity: Optional[float] = None
+    water_ndvi: float = 0.0
+
+    @property
+    def mixed_coeffs(self) -> Tuple[float, float]:
+        """``(m, n)`` of ``e = m * Pv + n`` for mixed pixels (Sobrino et al. 2004, eq. 12)."""
+        es, ev, f = self.emissivity_soil, self.emissivity_veg, self.shape_factor
+        cavity = (1.0 - es) * f * ev
+        return ev - es - cavity, es + cavity
+
+
+def emissivity_ndvi_threshold(
+    ndvi_values: ArrayLike,
+    red: Optional[ArrayLike] = None,
+    params: Optional[EmissivityParams] = None,
+) -> FloatArray:
+    """Land surface emissivity by the NDVI threshold method of Sobrino et al. (2004).
+
+    Args:
+        ndvi_values: NDVI array.
+        red: Red reflectance, needed only when ``params.soil_red_coeffs`` is set.
+        params: Method parameters; defaults to :class:`EmissivityParams()`.
+
+    Returns:
+        Emissivity array; NaN where NDVI is NaN.
+    """
+    p = params or EmissivityParams()
+    v = np.asarray(ndvi_values, dtype=np.float64)
+    pv = fractional_vegetation_cover(v, p.ndvi_soil, p.ndvi_veg)
+    m, n = p.mixed_coeffs
+    eps = m * pv + n
+
+    soil = v < p.ndvi_soil
+    if p.soil_red_coeffs is not None:
+        if red is None:
+            raise ValueError("red reflectance is required when soil_red_coeffs is set")
+        a, b = p.soil_red_coeffs
+        r = np.broadcast_to(np.asarray(red, dtype=np.float64), v.shape)
+        eps = np.where(soil, a + b * r, eps)
+    else:
+        eps = np.where(soil, p.emissivity_soil, eps)
+    eps = np.where(v > p.ndvi_veg, p.emissivity_veg, eps)
+    if p.water_emissivity is not None:
+        eps = np.where(v < p.water_ndvi, p.water_emissivity, eps)
+    out: FloatArray = np.where(np.isnan(v), np.nan, eps)
+    return out

lstcalc/errors.py

@@ -0,0 +1,17 @@
+"""Exceptions raised by lstcalc."""
+
+from __future__ import annotations
+
+__all__ = ["LstcalcError", "MetadataError", "OptionalDependencyError"]
+
+
+class LstcalcError(Exception):
+    """Base class for all lstcalc errors."""
+
+
+class MetadataError(LstcalcError, ValueError):
+    """An MTL file is malformed or lacks a required key."""
+
+
+class OptionalDependencyError(LstcalcError, ImportError):
+    """An optional dependency (such as rasterio) is required but not installed."""

lstcalc/io.py

@@ -0,0 +1,90 @@
+"""Optional raster I/O through rasterio (``pip install "lstcalc[raster]"``).
+
+The core library never imports rasterio; only these helpers and the ``scene`` / ``suhi`` /
+``zonal`` CLI commands need it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .errors import OptionalDependencyError
+from .mtl import MTL, read_mtl
+
+__all__ = ["find_band_file", "find_mtl", "read_band", "write_band"]
+
+PathLike = Union[str, Path]
+
+
+def _rasterio() -> Any:
+    try:
+        import rasterio
+    except ImportError as exc:  # pragma: no cover - depends on the environment
+        raise OptionalDependencyError(
+            'raster I/O needs rasterio: pip install "lstcalc[raster]"'
+        ) from exc
+    return rasterio
+
+
+def read_band(path: PathLike, band: int = 1) -> Tuple[NDArray[Any], Dict[str, Any]]:
+    """Read one band; returns ``(array, profile)`` where ``profile`` is rasterio's profile."""
+    rasterio = _rasterio()
+    with rasterio.open(path) as src:
+        return src.read(band), dict(src.profile)
+
+
+def write_band(
+    path: PathLike,
+    array: NDArray[Any],
+    profile: Dict[str, Any],
+    nodata: Optional[float] = float("nan"),
+) -> None:
+    """Write a single-band float32 GeoTIFF using a template ``profile``."""
+    rasterio = _rasterio()
+    prof = dict(profile)
+    prof.update(driver="GTiff", count=1, dtype="float32", nodata=nodata)
+    data = np.asarray(array, dtype=np.float32)
+    with rasterio.open(path, "w", **prof) as dst:
+        dst.write(data, 1)
+
+
+def find_mtl(folder: PathLike) -> Path:
+    """Locate the ``*_MTL.txt`` (preferred) or ``*_MTL.json`` file in a scene folder."""
+    root = Path(folder)
+    for pattern in ("*_MTL.txt", "*_MTL.json", "*MTL*.txt", "*MTL*.json"):
+        hits = sorted(root.glob(pattern))
+        if hits:
+            return hits[0]
+    raise FileNotFoundError(f"no MTL file found in {root}")
+
+
+def find_band_file(folder: PathLike, band: str, mtl: Optional[MTL] = None) -> Path:
+    """Locate a band file such as ``"B10"``, ``"B4"``, ``"ST_B10"`` or ``"SR_B4"``.
+
+    The MTL ``FILE_NAME_BAND_*`` entry is used first, then a ``*_<band>.TIF`` glob.
+    """
+    root = Path(folder)
+    if mtl is not None:
+        key = band[1:] if band.startswith("B") else band
+        name = mtl.file_name(key)
+        if name and (root / name).exists():
+            return root / name
+    candidates: List[Path] = []
+    for ext in ("TIF", "tif", "TIFF", "tiff"):
+        candidates.extend(root.glob(f"*_{band}.{ext}"))
+    if band.upper().startswith("B"):
+        # "*_B10.TIF" must not pick up Level-2 "*_ST_B10.TIF" / "*_SR_B4.TIF" files.
+        level2 = (f"_ST_{band}".upper(), f"_SR_{band}".upper())
+        candidates = [p for p in candidates if not p.stem.upper().endswith(level2)]
+    if not candidates:
+        raise FileNotFoundError(f"no file for band {band} in {root}")
+    return sorted(set(candidates))[0]
+
+
+def load_scene_mtl(folder: PathLike) -> MTL:
+    """Find and parse the scene MTL file."""
+    return read_mtl(find_mtl(folder))