Metadata-Version: 2.4
Name: lstcalc
Version: 0.1.0
Summary: Land surface temperature (LST) and urban heat island metrics from Landsat 8/9 Collection 2 and Sentinel-2 NDVI on numpy arrays: MTL parsing, brightness temperature, NDVI-threshold emissivity, single-channel and Planck LST, Level-2 ST scaling, SUHI, UTFVI, hot spots and zonal statistics.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/YusufEminoglu/lstcalc_sdk
Project-URL: Repository, https://github.com/YusufEminoglu/lstcalc_sdk
Project-URL: Issues, https://github.com/YusufEminoglu/lstcalc_sdk/issues
Project-URL: Changelog, https://github.com/YusufEminoglu/lstcalc_sdk/blob/main/CHANGELOG.md
Keywords: land-surface-temperature,lst,urban-heat-island,suhi,utfvi,landsat,landsat-8,landsat-9,sentinel-2,ndvi,emissivity,remote-sensing,thermal-infrared,gis
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Provides-Extra: raster
Requires-Dist: rasterio>=1.2; extra == "raster"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# lstcalc

[![PyPI version](https://img.shields.io/pypi/v/lstcalc.svg)](https://pypi.org/project/lstcalc/)
[![Python versions](https://img.shields.io/pypi/pyversions/lstcalc.svg)](https://pypi.org/project/lstcalc/)
[![CI](https://github.com/YusufEminoglu/lstcalc_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/lstcalc_sdk/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/YusufEminoglu/lstcalc_sdk/blob/main/LICENSE)

**Land surface temperature and urban heat island metrics from Landsat 8/9, on numpy arrays.**

`lstcalc` takes you from Landsat 8/9 Collection 2 digital numbers to land surface temperature
(LST) and on to the usual urban heat island indicators, with every formula traceable to its
source:

- **MTL parsing**: `MTL.txt` and `MTL.json`, group-aware (Level-1 and Level-2 coefficients that
  share a key name are kept apart).
- **Radiometry**: DN to TOA radiance, TOA reflectance (sun-angle corrected), brightness
  temperature; Level-2 `ST_B10` and `SR_Bn` scaling; Sentinel-2 reflectance.
- **Vegetation and emissivity**: NDVI, fractional vegetation cover and the NDVI threshold
  emissivity method (Sobrino et al. 2004).
- **LST**: generalised single-channel algorithm with the Landsat 8 TIRS band 10 coefficients
  (Jimenez-Munoz et al. 2014), and the emissivity-corrected Planck method.
- **Urban heat island**: SUHI intensity from urban/rural masks, UTFVI and its six-class
  evaluation, hot spots, zonal statistics by a label raster.
- **CLI**: `lstcalc scene <folder>` processes a whole scene folder when `rasterio` is installed.

The core depends only on numpy. Raster I/O is an optional extra.

```bash
pip install lstcalc              # numpy only, works on arrays
pip install "lstcalc[raster]"    # + rasterio for GeoTIFF I/O and the scene CLI
```

Requires Python 3.9 or newer.

## Quick start

```python
import numpy as np
from lstcalc import read_mtl, lst_from_level1, suhi_intensity, utfvi, classify_utfvi

mtl = read_mtl("LC08_L1TP_180032_20230715_20230725_02_T1_MTL.txt")
# b10, b4, b5: numpy arrays of the TIRS band 10 and OLI band 4/5 DNs (same 30 m grid)
res = lst_from_level1(b10, mtl, red_dn=b4, nir_dn=b5, water_vapour=1.4)  # w in g/cm2

print(np.nanmean(res.lst_celsius))            # LST in degC
res.brightness_temperature, res.emissivity    # intermediate products are kept

suhi = suhi_intensity(res.lst, urban_mask, rural_mask)
print(suhi.intensity, suhi.urban_mean, suhi.rural_mean)

classes = classify_utfvi(utfvi(res.lst))      # 0 = excellent ... 5 = worst
```

Level-2 surface temperature needs no algorithm, just scaling:

```python
from lstcalc import lst_from_level2
st_kelvin = lst_from_level2(st_b10_dn, mtl)   # 0.00341802 * DN + 149.0, fill (0) -> NaN
```

Sentinel-2 NDVI (10 m) can replace the Landsat NDVI once it is on the Landsat grid:

```python
from lstcalc import sentinel2_reflectance, ndvi, block_mean
s2_ndvi = ndvi(sentinel2_reflectance(b08), sentinel2_reflectance(b04))
s2_ndvi_30m = block_mean(s2_ndvi, 3)          # only if the grids are co-registered
res = lst_from_level1(b10, mtl, ndvi=s2_ndvi_30m, method="planck")
```

A self-contained example on synthetic data is in [`examples/quickstart.py`](examples/quickstart.py).

## Command line

```bash
lstcalc mtl LC08_..._MTL.txt                               # coefficients as JSON (no rasterio)
lstcalc scene ./LC08_scene --out lst.tif --water-vapour 1.4 --celsius
lstcalc scene ./LC08_L2SP_scene --out lst.tif              # auto: Level-2 ST_B10 scaling
lstcalc suhi lst.tif --urban urban.tif --rural rural.tif
lstcalc utfvi lst.tif --out utfvi_class.tif --hotspots-out hot.tif
lstcalc zonal lst.tif --labels districts.tif --csv districts.csv
```

`scene --method auto` uses Level-2 `ST_B10` if the folder has it, otherwise the
single-channel method when `--water-vapour` is given, otherwise the Planck method.

## API overview

| Area | Functions |
| --- | --- |
| Metadata | `parse_mtl`, `read_mtl`, `MTL.radiance_coeffs`, `.reflectance_coeffs`, `.surface_reflectance_coeffs`, `.thermal_constants`, `.surface_temperature_coeffs`, `.sun_elevation`, `.summary` |
| Radiometry | `dn_to_radiance`, `dn_to_toa_reflectance`, `brightness_temperature`, `l2_surface_temperature`, `l2_surface_reflectance`, `sentinel2_reflectance`, `kelvin_to_celsius`, `block_mean` |
| Emissivity | `ndvi`, `fractional_vegetation_cover`, `emissivity_ndvi_threshold`, `EmissivityParams` |
| LST | `single_channel_lst`, `atmospheric_functions`, `atmospheric_functions_from_parameters`, `planck_lst`, `lst_from_level1`, `lst_from_level2` |
| Heat island | `suhi_intensity`, `utfvi`, `classify_utfvi`, `hotspots`, `zonal_statistics` |
| Raster I/O (extra) | `lstcalc.io.read_band`, `write_band`, `find_mtl`, `find_band_file` |

All array functions return `float64`, propagate `NaN` and treat DN `0` as fill by default.

## Methods and sources

**Radiometric conversion** (USGS, *Using the USGS Landsat Level-1 Data Product*):
`L = M_L * Q_cal + A_L`, `rho = (M_rho * Q_cal + A_rho) / sin(theta_SE)`,
`BT = K2 / ln(K1 / L + 1)`, with all coefficients read from the MTL file.

**Level-2 scaling** (USGS FAQ *How do I use a scale factor with Landsat Level-2 science
products?*, checked 2026-11-09): surface temperature `0.00341802 * DN + 149.0` K, surface
reflectance `0.0000275 * DN - 0.2`.

**Emissivity, NDVI threshold method** (Sobrino, Jimenez-Munoz & Paolini 2004, *Remote Sensing
of Environment* 90, 434-440, checked against the paper):

| NDVI | Emissivity |
| --- | --- |
| `< 0.2` | bare soil, `e_s` (default 0.97) or `a + b * rho_red` if you supply `(a, b)` |
| `0.2 - 0.5` | `e_v Pv + e_s (1 - Pv) + (1 - e_s)(1 - Pv) F e_v`, `F = 0.55` |
| `> 0.5` | `e_v` (0.99) |

with `Pv = ((NDVI - 0.2) / (0.5 - 0.2))^2`. The defaults give the paper's
`e = 0.004 Pv + 0.986` (eq. 13). Every value is a field of `EmissivityParams`.

**Single-channel LST** (Jimenez-Munoz & Sobrino 2003, *JGR* 108(D22); Landsat 8 coefficients
from Jimenez-Munoz, Sobrino, Skokovic, Mattar & Cristobal 2014, *IEEE GRSL* 11(10), 1840-1843,
checked against the paper):

```
Ts = gamma * [ (psi1 * L + psi2) / e + psi3 ] + delta
gamma = T^2 / (b_gamma * L),  delta = T - T^2 / b_gamma,  b_gamma = 1324 K (TIRS-1)
psi = C [w^2, w, 1]^T,   C = [[ 0.04019,  0.02916,  1.01523],
                              [-0.38333, -1.50294,  0.20324],
                              [ 0.00918,  1.36072, -0.27514]]
```

`w` is total column water vapour in g cm-2. If you have radiative-transfer outputs (for
example from the NASA Atmospheric Correction Parameter Calculator) use
`atmospheric_functions_from_parameters(tau, Lu, Ld)` instead: `psi1 = 1/tau`,
`psi2 = -Ld - Lu/tau`, `psi3 = Ld`.

**Planck method** (Artis & Carnahan 1982, *Remote Sensing of Environment* 12, 313-329):
`LST = BT / (1 + (lambda BT / rho) ln e)`, `rho = h c / k_B = 14387.77 um K`,
`lambda = 10.904 um` (TIRS-1 effective wavelength, Jimenez-Munoz et al. 2014).

**SUHI intensity**: mean LST over the urban mask minus mean LST over the rural mask
(e.g. Peng et al. 2012, *Environ. Sci. Technol.* 46, 696-703). The masks are yours to define.

**UTFVI** (Liu & Zhang 2011, *Remote Sensing* 3, 1535-1552): `(Ts - T_mean) / Ts`, classified
with the breaks 0, 0.005, 0.010, 0.015, 0.020 into none/excellent ... strongest/worst.

**Hot spots**: `LST > mean + 2 std` (Guha et al. 2018, *European Journal of Remote Sensing*
51, 667-678); `k` is a parameter.

## Limitations

- The single-channel water-vapour coefficients are for Landsat 8 TIRS band 10. For band 11, or
  for Landsat 9, pass your own `coeffs`/`b_gamma` or atmospheric parameters. The authors note
  that the water-vapour fit degrades for `w > 3 g cm-2`.
- The default emissivities are the Sobrino et al. (2004) TM6 values, commonly reused for
  TIRS band 10; supply band-specific values through `EmissivityParams` if you have them.
  Water, snow and built-up materials are not modelled separately unless you set
  `water_emissivity`.
- NDVI from TOA reflectance (as in `lst_from_level1`) is not atmospherically corrected.
- `block_mean` does not reproject; Sentinel-2 and Landsat grids must already be aligned.
- No cloud masking: apply the QA_PIXEL band yourself before computing statistics.
- The UTFVI class breaks, the Sentinel-2 offset (-1000 from processing baseline 04.00) and
  quantification value (10000), and the fallback `THERMAL_CONSTANTS` table were not checked
  against a primary source for this release; all are parameters you can override.

## Development

```bash
pip install -e ".[dev,raster]"
python -m pytest
python -m ruff check . && python -m mypy src
```

## Academic citation

```bibtex
@software{eminoglu_lstcalc,
  author  = {Eminoğlu, Yusuf},
  title   = {lstcalc},
  year    = {2026},
  version = {0.1.0},
  url     = {https://github.com/YusufEminoglu/lstcalc_sdk}
}
```

See also [`CITATION.cff`](CITATION.cff).

## License

MIT License. Copyright (c) 2026 Yusuf Eminoğlu. See [LICENSE](LICENSE).
