A previous release had provenance metadata, but this release does not. View details.
lstcalc
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.txtandMTL.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_B10andSR_Bnscaling; 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 whenrasteriois 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.
suhi, utfvi and zonal treat the raster's own nodata value as missing unless
--nodata gives another one.
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_gammaor atmospheric parameters. The authors note that the water-vapour fit degrades forw > 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
EmissivityParamsif you have them. Water, snow and built-up materials are not modelled separately unless you setwater_emissivity. - NDVI from TOA reflectance (as in
lst_from_level1) is not atmospherically corrected. block_meandoes 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_CONSTANTStable were not checked against a primary source for this release; all are parameters you can override.
Development
git clone https://gitlab.com/geophilo1/lstcalc_sdk.git
cd lstcalc_sdk
pip install -e ".[dev,raster]"
python -m pytest
python -m ruff check . && python -m mypy
Academic citation
@software{eminoglu_lstcalc,
author = {Eminoğlu, Yusuf},
title = {lstcalc},
year = {2026},
version = {0.1.2},
doi = {10.5281/zenodo.24122209},
url = {https://gitlab.com/geophilo1/lstcalc_sdk}
}
See also CITATION.cff.
Related Geophilo SDKs
- heatstress: heat stress indices (heat index, WBGT, UTCI, humidex) and heatwave detection.
- lczlite: Local Climate Zone classification from urban canopy parameters.
- skyview: sky view factor, topographic openness and street-canyon H/W metrics.
- greenrule: urban green space provision and exposure indicators, including NDVI buffer exposure.
License
MIT License. Copyright (c) 2026 Yusuf Eminoğlu. See LICENSE.
Metadata
Release files for lstcalc 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Loss of provenance
These files do not have provenance metadata, despite files in a prior release including this data.
We recommend further investigation before installing these files. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| lstcalc-0.1.2.tar.gz | 39.7 kB | Without provenance | Details for lstcalc-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lstcalc-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for lstcalc-0.1.2-py3-none-any.whl |
Total release size: 69.7 kB
Release files / lstcalc-0.1.2.tar.gz
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | lstcalc-0.1.2.tar.gz |
|---|---|
| Size | 39.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f236ec362418b16046dc70751bed047e7696134fdaba028388a17b9dca53a6f0
|
|
BLAKE2b-256 checksum How to use checksums |
58bafe12312b386ef4e5155d9e32b174c9748e7fd3978d0aa06100d850993978
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / lstcalc-0.1.2-py3-none-any.whl
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | lstcalc-0.1.2-py3-none-any.whl |
|---|---|
| Size | 30.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bfa11f503e43e6f8f096738e39ef5f68a1fa700e8e008b32d1f456a3fd151da9
|
|
BLAKE2b-256 checksum How to use checksums |
f34c0429bf968edbf8c7babb8b358bb96fda02c873a1008c8b3b817279ec3d5b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for lstcalc 0.1.2
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.
Loss of provenance
A previous release of these files had provenance metadata, but this release does not.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Release comparison
- Removed 0.1.1 2 files With provenance
- Added 0.1.2 2 files Without provenance
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.