TerraPulse 4D — Guide

TerraPulse simulates a real ~960 m × 960 m neighborhood block — heat, flooding, and vegetation — over a 10-year horizon. It's not a static visualization: a physics-based engine (hydrology, thermal, and vegetation models) recomputes the block year by year, and every intervention you place actually changes those numbers.

1. You land on a real, already-placed demo plan for Downtown Singapore, auto-run so results are visible immediately — nothing to configure to see it working.
2. Pick a different location from the dropdown, top-left, if you'd like — it clears the plan and auto-runs a do-nothing baseline for the new city.
3. Pick an intervention in the left panel, then click the terrain to place it (up to 5 of each type).
4. Press Run simulation to recompute all 11 years with your interventions.
5. Scrub the timeline and switch data layers (bottom bar) to compare outcomes.
6. Check the Action plan tab for suggestions — click one to preselect that intervention type.
7. Press Share (top-right) to copy a link that reproduces this exact location and plan for anyone who opens it.

• Ground color = whichever data layer is selected (see below).
• Buildings are real, from OpenStreetMap — each one extruded from its actual building footprint polygon (not a uniform box), at its real or estimated height. Material tones follow the location's real character — pastel Art Deco for Miami, sandstone/adobe for Phoenix, brick and dark glass for Rotterdam, glass towers for Singapore — and taller buildings skew toward each city's glass/modern tone, the way real skylines mix glass towers among low-rises. If a location's OpenStreetMap data has no building footprints (or terrain fell back to the procedural generator), you'll instead see windowed per-cell blocks with pitched roofs on low-rises (roughly 14 m and under) — a stand-in, not real geometry.
• Dark strips = real streets.
• Small static green shapes in parks = decorative trees over real grass/park cells, sized and colored for the location's climate (denser and brighter for tropical Singapore, sparse and dusty for desert Phoenix). Larger, growing ones = canopy from your interventions maturing over the run.
• Sunlight color and brightness shift per location too — warm desert light for Phoenix, cooler light for Rotterdam, and so on.
• Colored ring around a marker = that intervention's effect radius.
• A white pulsing ring/badge = the intervention currently selected in the left panel's list.
• Faint (row, col) labels at the four corners = grid coordinates.

Each type has a default effect radius (edit it after placing, via the +/− stepper) and a cap of 5 placed at once, to keep a run fast and the scene legible. Effects fade linearly from full strength at the center to zero at the edge of the radius, and apply in full from the year you place them — except canopy-driven effects (shade, evapotranspiration cooling, carbon), which mature over the run following a logistic growth curve.

Roof types (green roof, cool roof) only affect building cells within range — placing one over open ground is never blocked, but the marker stays inert with no effect.

Cost. Each type carries a rough unit cost (fixed mobilization/design + a per-cell area cost, scaling with radius — see the numbers above), ballparked from public green-infrastructure cost guidance: bioswales and cool-roof coatings are cheap per unit area, permeable pavement and green roofs cost more, retention ponds carry the largest fixed engineering cost. The left panel shows a running total as you place interventions; once a run finishes, the Metrics tab also shows $ per Resilience point gained. These are illustrative figures for relative comparison, not a real quote — the Resilience Score itself doesn't account for cost at all, so a cheap-but-effective plan and an expensive-but-effective plan can score identically.

• Resilience Score (0–100): 30% heat + 30% flood + 20% carbon + 20% soil moisture, weighted and normalized. The headline number — climbs as the block improves.
• Heat Island (UHI Δ°C): mean surface temperature of built cells minus the mean of vegetated/water cells.
• Peak Surface Temp: the hottest single cell that year.
• Flood Risk Area: % of cells above the flood-risk threshold.
• Carbon Stored: cumulative CO₂e sequestered by canopy, plus a small fixed annual stock from bioswales and green roofs.
• "vs baseline": every metric also shows the delta against a do-nothing run of the same location and year — computed automatically on every run, free to view.
• Resilience over time (small chart below the stat tiles): the current run's Resilience Score across all 11 years next to the baseline's, so the trend is visible without scrubbing year by year. Hover to read any year; click to jump the timeline there.
• "What changed" callout: after a run, if you've run this location before, a one-line summary compares this run's Resilience Score to your last one and names whichever intervention type changed count the most — a quick sanity check that your last edit actually helped.

After a run finishes, the model looks at that year's hotspots and either asks Claude for a short assessment and prioritized recommendations, or — if no API key is configured, or the call fails — falls back to a deterministic rule-based recommender (hottest built cells → tree canopy or cool roof; highest flood-risk cells → bioswale or retention pond; low soil moisture → permeable pavement). Either path returns the same shape: a title, a plain-language reason, and a priority. The small label above the list says which one produced it. Click a suggestion to preselect its intervention type, then place it on the terrain.

• Streets, buildings, water, parks: real, pulled live from OpenStreetMap for the exact coordinates you pick, redrawn every time you load a new location.
• Building height: real where OSM tags it (height or building:levels), otherwise a ~3-story (9 m) estimate.
• Elevation: real, but compressed. Free elevation datasets are surface models — a sample point in a dense downtown can land on a rooftop instead of the ground. We despike that and cap total relief at 22 m across the block so hills stay directionally correct without turning a flat city into a fake mountain.
• Climate baseline: real. The warm-season reference temperature and the design-storm depth used by the thermal and hydrology models are pulled from the last year of actual daily weather at your coordinates (Open-Meteo's free historical archive) — the warm-season reference is the mean daily high across the hottest quarter of the year, and the design storm is the single heaviest rain day recorded. That's why Phoenix runs genuinely hotter and drier than Rotterdam instead of both using the same fixed constants with only the terrain differing. One year of data is a proxy, not a multi-decade engineering return period — hover the status dot next to the location dropdown to see the resolved numbers and whether they came from live weather data or the fixed fallback.
• Small park trees: decorative, scattered over real grass/park cells — not individually mapped (OSM rarely maps individual street trees).
• Building materials, tree color, and light: styled per location's known regional character (a fixed tag per preset city, not measured from data) — real buildings, streets, and water; stylistic finish.
• Coverage varies by city. Well-mapped urban cores are quite accurate; sparser regions return thinner data. If the live map services are unreachable (rate limits, timeouts), the block falls back to a deterministic synthetic layout so the app never breaks — the status dot next to the location dropdown says which one you got.
• Three tiers, not two. For the 4 preset locations specifically, there's a middle tier between live and synthetic: a real snapshot captured earlier and bundled with the app. If the live APIs are throttled or briefly down, you still see real streets and buildings, just not fetched this instant — the status tooltip says “real data (cached snapshot from <date>)” when this happened.