Skip to main content

lstcalc

PyPI version Python versions CI License: MIT

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.

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

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:

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:

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.

Command line

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

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

Academic citation

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

See also CITATION.cff.

License

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

Metadata

Release files for lstcalc 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lstcalc 0.1.1
File Size Uploaded Provenance Actions
lstcalc-0.1.1.tar.gz 37.7 kB With provenance Details for lstcalc-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lstcalc 0.1.1
File Interpreter ABI Platform Actions
lstcalc-0.1.1-py3-none-any.whl Python 3 none any Details for lstcalc-0.1.1-py3-none-any.whl

Total release size: 67.0 kB

Release files / lstcalc-0.1.1.tar.gz

Download URL lstcalc-0.1.1.tar.gz
Size 37.7 kB
Tags Source
SHA-256 checksum
How to use checksums
a9a2de3da5e5bc7497198031871d5296c59429a8cf9f5c045229062dbae0d54f
BLAKE2b-256 checksum
How to use checksums
c0123a1be2679fe110dc08de87c0f8aefb35a4f7549c5f08fdae5e4985ce5750
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / lstcalc-0.1.1-py3-none-any.whl

Download URL lstcalc-0.1.1-py3-none-any.whl
Size 29.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c6119c4170e32c846eb83933cf538e5dda4837ab663bcfb8d88018939e06cabd
BLAKE2b-256 checksum
How to use checksums
cf1db24d496c31fe1910ecd88c395661e18ae21c69358acf8f5d03b2375043ba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for lstcalc 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for lstcalc-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page