Regenerative Thermal Analysis with infrared.city

Urban greening is sold as cooling. Often it is. But canopy changes a microclimate for better or for worse, and which one depends on the street's form. A broad crown over an open plaza shades a hot surface and cools it. The same crown packed into a narrow, deep canyon can trap the longwave heat the buildings radiate and choke the wind that would carry it away.

So the regenerative question is not "how many trees" but "what does this canopy do to this street's heat and air". That is a measurement question, and this module is how you measure it.

The Universal Thermal Climate Index answers "what does a body feel here", folding air temperature, mean radiant temperature, wind speed and humidity into one equivalent temperature in °C. It is the index the infrared.city thermal-comfort model returns.

The assessment scale sorts that number into stress bands. The module uses these exact thresholds (Błażejczyk et al. 2013):

Two figures drive the whole assessment:

• Heat-stress % = the share of the grid above 26°C (moderate heat and worse).
• Severe-heat % = the share above 38°C (strong heat and worse).

A single mean flattens a street into one verdict. Alberti's planetary-urbanism lens asks a richer question: how many distinct thermal conditions does a place offer, and how evenly are they mixed. A street with shade pockets, sunny edges and ventilated gaps gives a body somewhere to move to. The module operationalises this as the Thermal Assembly Complexity Index (TACI), grid-native.

It is built from the UTCI band map of the grid:

• Zone diversity, a Shannon index over the occupied stress bands.
• Spatial complexity, how interleaved those zones are across the grid.

One install, one key. The client reads INFRARED_API_KEY from your environment and auto-loads a local .env on import. Treat the key as a password; never commit it (the toolkit's .gitignore already excludes .env).

# pip install infrared-sdk numpy matplotlib
import infrared_sdk as ir

# reads INFRARED_API_KEY from your .env automatically
client = ir.InfraredClient()

# a square around your site, lon/lat, closed ring
polygon = [[-8.486,51.897],[-8.482,51.897],
           [-8.482,51.899],[-8.486,51.899],[-8.486,51.897]]

# PREVIEW: tiles the area, no job is submitted, nothing is billed.
# always pass analysis_type (wind grid = 256 m, solar/thermal = 512 m)
preview = client.preview_area(polygon, analysis_type="solar")
print(preview.tile_count, "tiles ready, 0 cost")

A real run submits a model request over your polygon and waits for the grid. This is the billable step, so the module teaches it with the cost guard switched on from the start.

from infrared_sdk.models import TimePeriod
import regenerative_metrics as rm

# a solar run needs no weather file; UTCI does (see the toolkit's fetch helper)
request = ir.SolarModelRequest(time_period=TimePeriod.SUMMER)

# BILLABLE. run_area_and_wait submits a real job. cap tiles while learning.
baseline = client.run_area_and_wait(
    request, polygon,
    on_progress=lambda p: print(f"  {p:.0%}"),
)
grid = baseline.merged_grid          # numpy array, NaN outside the site
print(rm.utci_stats(grid).line())

Now run the same polygon again with vegetation injected, so the only thing that changed is the trees:

# real street trees, fetched and shaped by the SDK's vegetation service
veg = client.vegetation.get_area(polygon)
print(veg.total_trees, "trees on this site")

intervention = client.run_area_and_wait(request, polygon, vegetation=veg)
print(rm.utci_stats(intervention.merged_grid).line())

The metrics module reads a numpy grid and returns the figures the scorecard compares. Nothing here is billed; it is pure post-processing of grids you already have.

import regenerative_metrics as rm

base = rm.utci_stats(baseline.merged_grid)
trees = rm.utci_stats(intervention.merged_grid)

print(f"heat-stress  {base.heat_stress_pct:.1f}% -> {trees.heat_stress_pct:.1f}%")
print(f"mean UTCI    {base.mean:.1f} -> {trees.mean:.1f} °C")

# the assembly view: did the street gain thermal-zone diversity?
taci = rm.assembly_index(intervention.merged_grid)
print(f"zone diversity (Shannon)  {taci.spatial_diversity:.2f}")

Run the probe on a deep, narrow Mediterranean street and add a broad canopy, and the heat-stress fraction goes up. The crowns lower the sky-view factor, so the longwave heat the walls radiate at night is trapped under the leaves, and the same crowns slow the cross-street wind that would have flushed it.

This is not a bug in the model. It is the model telling you the truth about that street. Marseille below is the worked example: heat-stress rises from 79.1% to 83.0% after planting, because the intervention was canopy in a canyon.

These are the measured deltas from running the probe over each city's site. They are not tidy. That is the honest result, and the teaching point: the method is constant, the verdict is local.

Cork is the regenerative case: no heat stress to begin with, and planting widened the mix of thermal zones (the assembly gain). Marseille and Rome are the cautionary cases, where dense form and sparse ground make canopy a weaker lever than airflow. Same code, three different streets, three different truths.

The module is the front door. Each of these takes the same finding somewhere concrete: