UHI-Pipe

How it works

The pipeline connects to Microsoft Planetary Computer, a free STAC catalog that hosts petabytes of satellite data. It downloads only the pixels at your specific coordinates, applies cloud and quality masking, composites across your time window, and caches everything so re-runs are instant.

Sentinel-2 is the backbone of the pipeline. It captures 11 spectral bands ranging from visible light to shortwave infrared, giving us enough spectral resolution to distinguish vegetation from concrete, water from bare soil, and everything in between. The L2A product is already atmospherically corrected, so the reflectance values represent surface properties rather than atmospheric noise.

The 5×5 neighborhood median is important. Rather than extracting just the nearest pixel to each coordinate, the pipeline takes the median value in a 5×5 grid around the point. This reduces noise from GPS coordinate error and sub-pixel heterogeneity, at the cost of smoothing out features smaller than 5 pixels across.

Spectral index library

The 19 features above come from these formulas. Each index is a mathematical combination of Sentinel-2 bands designed to isolate a specific surface property. Vegetation indices use the contrast between red absorption and near-infrared reflection. Built-up indices exploit how impervious surfaces reflect shortwave infrared. Water indices flip the vegetation logic.

Landsat-8 matters here for one reason: thermal infrared. Sentinel-2 does not have a thermal band, so it cannot measure surface temperature directly. Landsat's Band 10 captures longwave infrared radiation emitted by the ground, which is how we derive land surface temperature. The visible and NIR bands also give us a second, independent NDVI measurement that feeds into the emissivity correction.

Without emissivity correction, the thermal band gives you brightness temperature, what the sensor sees at the top of the atmosphere. The mono-window method adjusts for how efficiently different surfaces emit radiation. Bare soil (ε ≈ 0.97) emits differently than full vegetation (ε ≈ 0.99). The pipeline derives emissivity from Landsat NDVI using Sobrino et al. (2004) thresholds, then corrects the brightness temperature to get actual ground temperature in °C.

Elevation matters because higher ground is cooler. Hilltop neighborhoods experience different heat dynamics than low-lying river valleys, even when the land cover is identical. The Copernicus GLO-30 DEM provides consistent global elevation data at 30-meter resolution. Unlike the satellite imagery sources, this is a static dataset. No date parameter, no cloud masking, no compositing. The pipeline downloads the tiles once, mosaics them, and extracts the elevation at each point.

Because the DEM is static, it gets special treatment in the caching layer. During a resolution sweep (running 7 resolutions across 3 cities), the pipeline extracts DEM once per city instead of 21 times. The cache key ignores resolution and date parameters for this source.

Satellite imagery tells you what the surface looks like from above, but it cannot tell you how tall the buildings are or how densely packed they are. Building footprint data fills that gap. The pipeline accepts either a pre-computed CSV with density values or a raw shapefile of building polygons. When given a shapefile, it computes building density within a configurable buffer (default 100m) around each sample point.

Building data is the most uneven source in terms of global availability. 3D-GloBFP has good coverage for major cities but gaps elsewhere. When building data is unavailable, the pipeline runs without it. The corresponding columns return NaN, and the rest of the DataFrame is unaffected. This makes the building source optional rather than a hard dependency.

Usage

All four sources converge into one function call, but each can also run independently. The tabs below show both approaches.

from uhi_pipe import extract_sentinel
from uhi_pipe.features import sentinel_features
# Extract raw bands at your coordinates
raw = extract_sentinel(
    points=my_points,
    bbox=(-33.88, -71.05, -33.23, -70.04),
    time_window="2024-01-15/2024-02-15",
    resolution=100,
    max_cloud=30,
)
# → Latitude, Longitude, B01-B12 (raw DN values)
# Compute all 19 spectral indices
features = sentinel_features(raw)
# → Adds NDVI, EVI, SAVI, NDBI, Albedo, ... (19 columns)

Pre-configured locations

Three cities ship as built-in configurations for quick testing. These are the cities from the UHI-Explorer classification project, but the pipeline works with any bounding box and coordinates.

Resolution sweep

The pipeline supports resolutions from 10m to 1000m. Below 30m, the fused dataset hits a floor. Landsat thermal is natively 100m (resampled to 30m), and the DEM is 30m. Sentinel-2 bands go down to 10m, but combining them with coarser sources introduces spatial mismatch at fine scales.

Assumptions and limitations