lstcalc 0.1.0__tar.gz

lstcalc-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-09
+### Added
+- `parse_mtl` / `read_mtl`: Landsat Collection 2 (and Collection 1) `MTL.txt` and `MTL.json`
+  parsing with group-aware accessors for radiance, TOA reflectance, surface reflectance,
+  thermal constants and Level-2 surface temperature coefficients.
+- Radiometry: DN to radiance, TOA reflectance (sun-angle corrected), brightness temperature,
+  Level-2 `ST_B10` and `SR_Bn` scaling, Sentinel-2 reflectance, `block_mean` aggregation.
+- NDVI, fractional vegetation cover and NDVI-threshold emissivity (Sobrino et al. 2004)
+  with overridable parameters.
+- LST: generalised single-channel algorithm with Landsat 8 TIRS-1 coefficients
+  (Jimenez-Munoz et al. 2014), or with user atmospheric parameters; Planck
+  emissivity-corrected brightness temperature.
+- `lst_from_level1` / `lst_from_level2` end-to-end array workflows.
+- Urban heat island metrics: SUHI intensity, UTFVI with six-class evaluation, hot spots,
+  zonal statistics by label raster.
+- `lstcalc` CLI (`mtl`, `scene`, `suhi`, `utfvi`, `zonal`); raster commands use the optional
+  `rasterio` extra.

lstcalc-0.1.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Eminoğlu"
+    given-names: "Yusuf"
+    email: "geospacephilo@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "lstcalc"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://github.com/YusufEminoglu/lstcalc_sdk"
+url: "https://pypi.org/project/lstcalc/"
+abstract: "Land surface temperature (LST) and urban heat island metrics from Landsat 8/9 Collection 2 Level-1 and Level-2 data and Sentinel-2 NDVI on numpy arrays: MTL parsing, brightness temperature, NDVI-threshold emissivity, single-channel and Planck LST, SUHI intensity, UTFVI, hot spots and zonal statistics."
+keywords:
+  - land surface temperature
+  - urban heat island
+  - landsat
+  - remote sensing
+  - gis

lstcalc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lstcalc-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/lstcalc/py.typed
+recursive-include src/lstcalc *.py
+recursive-include tests *.py
+recursive-include examples *.py

lstcalc-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+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).

lstcalc-0.1.0/README.md

@@ -0,0 +1,191 @@
+# 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).

lstcalc-0.1.0/examples/quickstart.py

@@ -0,0 +1,74 @@
+"""lstcalc quick start on a synthetic Landsat 8 scene (no files or network needed).
+
+Run with:  python examples/quickstart.py
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from lstcalc import (
+    classify_utfvi,
+    hotspots,
+    lst_from_level1,
+    parse_mtl,
+    suhi_intensity,
+    utfvi,
+    zonal_statistics,
+)
+
+MTL = """GROUP = LANDSAT_METADATA_FILE
+  GROUP = IMAGE_ATTRIBUTES
+    SPACECRAFT_ID = "LANDSAT_8"
+    SUN_ELEVATION = 55.0
+  END_GROUP = IMAGE_ATTRIBUTES
+  GROUP = LEVEL1_RADIOMETRIC_RESCALING
+    RADIANCE_MULT_BAND_10 = 3.3420E-04
+    RADIANCE_ADD_BAND_10 = 0.10000
+    REFLECTANCE_MULT_BAND_4 = 2.0000E-05
+    REFLECTANCE_ADD_BAND_4 = -0.100000
+    REFLECTANCE_MULT_BAND_5 = 2.0000E-05
+    REFLECTANCE_ADD_BAND_5 = -0.100000
+  END_GROUP = LEVEL1_RADIOMETRIC_RESCALING
+  GROUP = LEVEL1_THERMAL_CONSTANTS
+    K1_CONSTANT_BAND_10 = 774.8853
+    K2_CONSTANT_BAND_10 = 1321.0789
+  END_GROUP = LEVEL1_THERMAL_CONSTANTS
+END_GROUP = LANDSAT_METADATA_FILE
+END
+"""
+
+
+def main() -> None:
+    rng = np.random.default_rng(42)
+    shape = (60, 60)
+    city = np.zeros(shape, dtype=bool)
+    city[20:40, 20:40] = True
+
+    # Synthetic DNs: the city core is warmer and less vegetated than its surroundings.
+    b10 = np.where(city, 31500, 29000) + rng.integers(-300, 300, shape)
+    b4 = np.where(city, 11000, 8000) + rng.integers(-200, 200, shape)
+    b5 = np.where(city, 14000, 22000) + rng.integers(-200, 200, shape)
+
+    mtl = parse_mtl(MTL)
+    res = lst_from_level1(b10, mtl, red_dn=b4, nir_dn=b5, water_vapour=1.5)
+    print(f"mean LST: {np.nanmean(res.lst_celsius):.2f} degC")
+    print(f"mean emissivity urban/rural: {res.emissivity[city].mean():.4f} / "
+          f"{res.emissivity[~city].mean():.4f}")  # fmt: skip
+
+    rural = np.zeros(shape, dtype=bool)
+    rural[:10, :] = True
+    suhi = suhi_intensity(res.lst, city, rural)
+    print(f"SUHI intensity: {suhi.intensity:.2f} K")
+
+    classes = classify_utfvi(utfvi(res.lst))
+    print("UTFVI class counts:", np.bincount(classes[classes >= 0], minlength=6).tolist())
+    print("hot-spot pixels:", int(hotspots(res.lst).sum()))
+
+    zones = city.astype(int) + 1  # 1 = periphery, 2 = core
+    for label, stats in zonal_statistics(res.lst_celsius, zones).items():
+        print(f"zone {label}: mean {stats.mean:.2f} degC (n={stats.count})")
+
+
+if __name__ == "__main__":
+    main()