zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/urban_form.py

@@ -0,0 +1,326 @@
+"""Urban-design indicators: pedestrian Green View Index and solar envelope.
+
+* :func:`green_view_index` - panoramic pedestrian-level green view percentage
+  on a 2.5-D raster (tree crowns plus vegetated ground within 30 m), occluded
+  by buildings.
+* :func:`solar_envelope` - Knowles (1981) / BRE right-to-light maximum
+  buildable heights and floor counts that keep sun on existing facades.
+
+Grids may be flat (row-major from the north-west cell) or ``(rows, cols)``;
+returned grids are ``(rows, cols)``.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Callable, Optional, Sequence
+
+import numpy as np
+
+__all__ = ["GVI_CLASSES", "gvi_class", "green_view_index", "solar_envelope"]
+
+GVI_CLASSES: list[dict[str, Any]] = [
+    {"min": 0, "max": 10, "key": "bare", "label": "Bare / low green", "color": "#d73027"},
+    {"min": 10, "max": 20, "key": "moderate", "label": "Moderate green", "color": "#fee08b"},
+    {"min": 20, "max": 35, "key": "street", "label": "Green street", "color": "#a6d96a"},
+    {"min": 35, "max": 100, "key": "high", "label": "High biophilic canopy", "color": "#1a9850"},
+]
+
+
+def _jsround(x: float) -> int:
+    """JavaScript ``Math.round`` (halves round up, not to even)."""
+    return int(math.floor(x + 0.5))
+
+
+def gvi_class(pct: float) -> Optional[dict[str, Any]]:
+    """Qualitative tier of a Green View Index percentage (``None`` if not finite)."""
+    if pct is None or not math.isfinite(pct):
+        return None
+    if pct < 10:
+        return GVI_CLASSES[0]
+    if pct < 20:
+        return GVI_CLASSES[1]
+    if pct < 35:
+        return GVI_CLASSES[2]
+    return GVI_CLASSES[3]
+
+
+def _add_interval(intervals: list[list[float]], start: float, end: float) -> list[list[float]]:
+    """Insert ``[start, end]`` into a sorted list of disjoint intervals."""
+    if end <= start:
+        return intervals
+    s, e = start, end
+    out: list[list[float]] = []
+    inserted = False
+    for a, b in intervals:
+        if b < s:
+            out.append([a, b])
+        elif a > e:
+            if not inserted:
+                out.append([s, e])
+                inserted = True
+            out.append([a, b])
+        else:
+            s, e = min(s, a), max(e, b)
+    if not inserted:
+        out.append([s, e])
+    return out
+
+
+def green_view_index(
+    *,
+    building_heights: Any,
+    cols: int,
+    rows: int,
+    cell: float,
+    tree_obstacles: Optional[Sequence[Sequence[float]]] = None,
+    green_mask: Any = None,
+    min_x: float = 0.0,
+    max_y: float = 0.0,
+    eye_height: float = 1.6,
+    max_radius: float = 80.0,
+    azimuth_steps: int = 24,
+    on_progress: Optional[Callable[[float], None]] = None,
+) -> np.ndarray:
+    """Pedestrian Green View Index in percent (0..100); NaN inside buildings.
+
+    Args:
+        building_heights: obstacle height above ground per cell (0 = open).
+        tree_obstacles: ``[(x, y, radius, height), ...]`` tree crowns.
+        green_mask: 1 where the ground is vegetated.
+        min_x, max_y: west edge and north edge of the grid (tree rasterisation
+            uses cell centres at ``min_x + (c + 0.5) * cell``).
+        eye_height: pedestrian eye level in metres.
+        max_radius: sight distance in metres.
+        azimuth_steps: horizontal rays across 360 degrees.
+
+    Only the +/-45 degree vertical field of view counts.
+    """
+    n = cols * rows
+    bh = (
+        np.zeros((rows, cols))
+        if building_heights is None
+        else np.nan_to_num(np.asarray(building_heights, dtype=float).reshape(rows, cols))
+    )
+    gm = None if green_mask is None else np.asarray(green_mask, dtype=float).reshape(rows, cols)
+    tree_top = np.zeros((rows, cols))
+    tree_base = np.zeros((rows, cols))
+    for tx, ty, trad, th in tree_obstacles or []:
+        if not th > 0:
+            continue
+        rad = max(trad, cell * 0.5)
+        c0 = max(0, math.floor((tx - rad - min_x) / cell))
+        c1 = min(cols - 1, math.ceil((tx + rad - min_x) / cell))
+        r0 = max(0, math.floor((max_y - ty - rad) / cell))
+        r1 = min(rows - 1, math.ceil((max_y - ty + rad) / cell))
+        tb = max(1.2, 0.35 * th)
+        for r in range(r0, r1 + 1):
+            for c in range(c0, c1 + 1):
+                cx = min_x + (c + 0.5) * cell
+                cy = max_y - (r + 0.5) * cell
+                if math.hypot(cx - tx, cy - ty) <= rad and th > tree_top[r, c]:
+                    tree_top[r, c] = th
+                    tree_base[r, c] = tb
+
+    bl, tt, tbl = bh.tolist(), tree_top.tolist(), tree_base.tolist()
+    gl = gm.tolist() if gm is not None else None
+    step = cell
+    max_steps = int(math.ceil(max_radius / step))
+    total_vfov = math.pi / 2
+    half_vfov = total_vfov / 2
+    dirs = [
+        (math.cos(a * 2 * math.pi / azimuth_steps), -math.sin(a * 2 * math.pi / azimuth_steps))
+        for a in range(azimuth_steps)
+    ]
+    out = np.empty(n).reshape(rows, cols)
+    for r in range(rows):
+        for c in range(cols):
+            if bl[r][c] > 0:
+                out[r, c] = math.nan
+                continue
+            total = 0.0
+            for dc, dr in dirs:
+                max_tan = 0.0
+                intervals: list[list[float]] = []
+                ground = 0.0
+                for s in range(1, max_steps + 1):
+                    dist = s * step
+                    cc = _jsround(c + (dist / cell) * dc)
+                    rr = _jsround(r + (dist / cell) * dr)
+                    if cc < 0 or cc >= cols or rr < 0 or rr >= rows:
+                        break
+                    b = bl[rr][cc]
+                    if b > 0:
+                        bt = (b - eye_height) / dist
+                        if bt > max_tan:
+                            max_tan = bt
+                        if max_tan > 2.5:
+                            break
+                    top = tt[rr][cc]
+                    if top > eye_height:
+                        top_h = top - eye_height
+                        bot_h = max(0.0, tbl[rr][cc] - eye_height, dist * max_tan)
+                        if top_h > bot_h:
+                            phi_top = min(half_vfov, math.atan2(top_h, dist))
+                            phi_bot = math.atan2(bot_h, dist)
+                            if phi_top > phi_bot:
+                                intervals = _add_interval(intervals, phi_bot, phi_top)
+                    if gl is not None and gl[rr][cc] > 0 and dist <= 30 and max_tan <= 0:
+                        d_near = max(cell * 0.5, dist - cell * 0.5)
+                        d_far = dist + cell * 0.5
+                        g = min(half_vfov, math.atan2(eye_height, d_near)) - min(
+                            half_vfov, math.atan2(eye_height, d_far)
+                        )
+                        if g > 0:
+                            ground += g
+                green = sum(b - a for a, b in intervals) + ground
+                total += min(100.0, max(0.0, green / total_vfov * 100))
+            out[r, c] = total / azimuth_steps
+        if on_progress is not None:
+            on_progress((r + 1) / rows)
+    return out
+
+
+def solar_envelope(
+    *,
+    building_heights: Any,
+    cols: int,
+    rows: int,
+    cell: float,
+    ids: Any = None,
+    sun_vectors: Optional[Sequence[dict[str, Any]]] = None,
+    min_sun_hours: float = 2.0,
+    step_hours: float = 0.5,
+    max_buildable_height: float = 80.0,
+    floor_height: float = 3.2,
+    target_mask: Any = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Maximum buildable height and floor count per cell.
+
+    Receptors are the perimeter cells of existing buildings and the open cells
+    next to them. From each receptor, rays towards the active sun directions
+    cap the height of every cell they cross at ``distance * tan(altitude)``,
+    unless an existing building already shades that ray.
+
+    Args:
+        sun_vectors: ``[{"dir": (east, up, south), "weight": hours}, ...]`` in
+            scene axes (``-z`` north). The highest suns adding up to
+            ``min_sun_hours`` are used; default is a 45 degree noon sun.
+        target_mask: development site cells (neither buildings nor receptors).
+
+    Returns:
+        ``(max_height, max_floors)`` arrays of shape ``(rows, cols)``.
+    """
+    n = cols * rows
+    if cols <= 0 or rows <= 0:
+        return np.zeros((0, 0)), np.zeros((0, 0))
+    if cell <= 0:
+        raise ValueError("cell size must be positive")
+    max_h = np.full(n, float(max_buildable_height))
+    bh = (
+        np.zeros(n)
+        if building_heights is None
+        else np.asarray(building_heights, dtype=float).ravel()
+    )
+    idf = None if ids is None else np.asarray(ids).ravel()
+    tm = (
+        np.zeros(n, dtype=bool)
+        if target_mask is None
+        else np.asarray(target_mask).ravel().astype(bool)
+    )
+    is_b = (bh > 0) if idf is None else ((bh > 0) | (idf > 0))
+    is_b &= ~tm
+    if not is_b.any():
+        return max_h.reshape(rows, cols), np.maximum(0, np.floor(max_h / floor_height)).reshape(
+            rows, cols
+        )
+
+    receptors: list[tuple[int, int]] = []
+    is_rec = np.zeros(n, dtype=bool)
+    for r in range(rows):
+        for c in range(cols):
+            i = r * cols + c
+            if tm[i] or not is_b[i]:
+                continue
+            perim = c == 0 or c == cols - 1 or r == 0 or r == rows - 1
+            if not perim and (
+                not is_b[i - 1] or not is_b[i + 1] or not is_b[i - cols] or not is_b[i + cols]
+            ):
+                perim = True
+            if perim and not is_rec[i]:
+                is_rec[i] = True
+                receptors.append((c, r))
+    for k in range(len(receptors)):
+        rc, rr = receptors[k]
+        for dr in (-1, 0, 1):
+            for dc in (-1, 0, 1):
+                nc, nr = rc + dc, rr + dr
+                if 0 <= nc < cols and 0 <= nr < rows:
+                    ni = nr * cols + nc
+                    if not is_b[ni] and not tm[ni] and not is_rec[ni]:
+                        is_rec[ni] = True
+                        receptors.append((nc, nr))
+
+    active = [
+        sv for sv in (sun_vectors or []) if sv and sv.get("dir") is not None and sv["dir"][1] > 0.05
+    ]
+    if not active:
+        active = [{"dir": (0.0, math.sqrt(0.5), math.sqrt(0.5)), "weight": min_sun_hours}]
+
+    def weight(sv: dict[str, Any]) -> float:
+        return sv.get("weight") or step_hours
+
+    if sum(weight(sv) for sv in active) > min_sun_hours:
+        active = sorted(active, key=lambda sv: -sv["dir"][1])
+        subset = []
+        cum = 0.0
+        for sv in active:
+            subset.append(sv)
+            cum += weight(sv)
+            if cum >= min_sun_hours:
+                break
+        active = subset
+
+    for sv in active:
+        dx, dy, dz = (float(v) for v in sv["dir"])
+        ux, uy = dx, -dz
+        hlen = math.hypot(ux, uy)
+        if hlen < 1e-5:
+            continue
+        hx, hy = ux / hlen, uy / hlen
+        tan_alt = dy / hlen
+        max_d = max_buildable_height / tan_alt
+        step = cell * 0.5
+        for rc, rr in receptors:
+            rec_idx = rr * cols + rc
+            rec_id = idf[rec_idx] if idf is not None else 0
+            path: list[tuple[int, float]] = []
+            own = bool(is_b[rec_idx])
+            shaded = False
+            d = step
+            while d <= max_d:
+                ic = _jsround(rc + hx * d / cell)
+                ir = _jsround(rr - hy * d / cell)
+                d += step
+                if ic < 0 or ic >= cols or ir < 0 or ir >= rows:
+                    break
+                t = ir * cols + ic
+                if t == rec_idx:
+                    continue
+                if own:
+                    if is_b[t] and (idf is None or not rec_id or idf[t] == rec_id):
+                        continue
+                    own = False
+                allowed = math.hypot((ic - rc) * cell, (ir - rr) * cell) * tan_alt
+                if is_b[t] and bh[t] > allowed:
+                    shaded = True
+                    break
+                path.append((t, allowed))
+            if shaded:
+                continue
+            for t, allowed in path:
+                if allowed < max_h[t]:
+                    max_h[t] = allowed
+    max_h = np.clip(max_h, 0, max_buildable_height)
+    floors = np.maximum(0, np.floor(max_h / floor_height))
+    return max_h.reshape(rows, cols), floors.reshape(rows, cols)

zero2geospatial3d/walkability.py

@@ -0,0 +1,380 @@
+"""Pedestrian Cool Walkability Index (PCWI) and A* cool-route finder.
+
+Combines thermal comfort (UTCI), solar shade, Green View Index (3-30-300 rule),
+road traffic noise (WHO 53/65 dB thresholds) and terrain slope into a 0-100
+pedestrian quality index, and compares the shortest obstacle-free route
+against the coolest / highest-comfort route across an open-ground grid.
+
+Grids may be passed flat (row-major from the north-west cell) or as
+``(rows, cols)`` arrays; returned grids are ``(rows, cols)``.
+"""
+
+from __future__ import annotations
+
+import heapq
+import math
+from typing import Any, Callable, Optional, Sequence
+
+import numpy as np
+
+__all__ = [
+    "WALKABILITY_CLASSES",
+    "walkability_class",
+    "thermal_subscore",
+    "shade_subscore",
+    "green_subscore",
+    "quiet_subscore",
+    "slope_subscore",
+    "pedestrian_walkability_index",
+    "find_cool_route",
+]
+
+WALKABILITY_CLASSES: list[dict[str, Any]] = [
+    {"min": 75, "max": 101, "label": "Excellent (cool, shaded & quiet)", "color": "#1d8f5f"},
+    {"min": 55, "max": 75, "label": "Good pedestrian comfort", "color": "#6dbf67"},
+    {"min": 35, "max": 55, "label": "Moderate (exposed or noisy)", "color": "#f0b429"},
+    {"min": 0, "max": 35, "label": "Poor (heat stress / high noise / steep)", "color": "#d64545"},
+]
+
+
+def _finite(v: Any) -> bool:
+    try:
+        return math.isfinite(float(v))
+    except (TypeError, ValueError):
+        return False
+
+
+def walkability_class(score: float) -> Optional[dict[str, Any]]:
+    """Class dict for a 0-100 score, or ``None`` for a non-finite value."""
+    if not _finite(score):
+        return None
+    s = max(0.0, min(100.0, float(score)))
+    for c in WALKABILITY_CLASSES:
+        if c["min"] <= s < c["max"]:
+            return c
+    return WALKABILITY_CLASSES[-1]
+
+
+def thermal_subscore(utci_c: float) -> float:
+    """100 inside the UTCI no-stress band (9..26 C), falling to 0 at 42 C and -10 C."""
+    if not _finite(utci_c):
+        return math.nan
+    u = float(utci_c)
+    if 9 <= u <= 26:
+        return 100.0
+    if u > 26:
+        return max(0.0, min(100.0, 100 * (1 - (u - 26) / 16)))
+    return max(0.0, min(100.0, 100 * (1 - (9 - u) / 19)))
+
+
+def shade_subscore(shade_val: float) -> float:
+    """Shade fraction (0..1) or percentage (0..100) as a 0..100 score."""
+    if not _finite(shade_val):
+        return math.nan
+    v = float(shade_val)
+    frac = v / 100 if v > 1.01 else v
+    return max(0.0, min(100.0, frac * 100))
+
+
+def green_subscore(gvi_pct: float) -> float:
+    """Green View Index percentage; 30 % (the 3-30-300 rule) scores 100."""
+    if not _finite(gvi_pct):
+        return math.nan
+    return max(0.0, min(100.0, (float(gvi_pct) / 30) * 100))
+
+
+def quiet_subscore(noise_dba: float) -> float:
+    """100 at or below 50 dB(A), 0 at or above 75 dB(A), linear between."""
+    if not _finite(noise_dba):
+        return math.nan
+    n = float(noise_dba)
+    if n <= 50:
+        return 100.0
+    if n >= 75:
+        return 0.0
+    return 100 * (1 - (n - 50) / 25)
+
+
+def slope_subscore(slope_deg: float) -> float:
+    """100 up to 2 degrees, 0 from 12 degrees, linear between."""
+    if not _finite(slope_deg):
+        return math.nan
+    s = float(slope_deg)
+    if s <= 2:
+        return 100.0
+    if s >= 12:
+        return 0.0
+    return 100 * (1 - (s - 2) / 10)
+
+
+def _flat(a: Any) -> Optional[np.ndarray]:
+    if a is None:
+        return None
+    return np.asarray(a, dtype=float).ravel()
+
+
+def _vec(fn: Callable[[float], float], arr: np.ndarray) -> np.ndarray:
+    return np.array([fn(v) for v in arr], dtype=float)
+
+
+def pedestrian_walkability_index(
+    *,
+    cols: int,
+    rows: int,
+    ids: Any = None,
+    utci_grid: Any = None,
+    shade_grid: Any = None,
+    gvi_grid: Any = None,
+    noise_grid: Any = None,
+    slope_deg_grid: Any = None,
+    weights: Optional[dict[str, float]] = None,
+) -> np.ndarray:
+    """0-100 Pedestrian Cool Walkability Index on open ground.
+
+    Building cells (``ids != 0``) and cells without any input are NaN. Missing
+    subscores are left out of the weighted mean. Default weights: thermal 0.35,
+    shade 0.25, green 0.15, quiet 0.15, slope 0.10.
+    """
+    w = weights or {}
+    n = cols * rows
+    parts = [
+        (utci_grid, thermal_subscore, max(0.0, w.get("thermal", 0.35))),
+        (shade_grid, shade_subscore, max(0.0, w.get("shade", 0.25))),
+        (gvi_grid, green_subscore, max(0.0, w.get("green", 0.15))),
+        (noise_grid, quiet_subscore, max(0.0, w.get("quiet", 0.15))),
+        (slope_deg_grid, slope_subscore, max(0.0, w.get("slope", 0.10))),
+    ]
+    total = np.zeros(n)
+    wsum = np.zeros(n)
+    for grid, fn, wt in parts:
+        g = _flat(grid)
+        if g is None:
+            continue
+        s = _vec(fn, g)
+        ok = np.isfinite(s)
+        total[ok] += wt * s[ok]
+        wsum[ok] += wt
+    out = np.full(n, np.nan)
+    good = wsum > 0
+    out[good] = np.clip(total[good] / wsum[good], 0, 100)
+    idf = _flat(ids)
+    if idf is not None:
+        out[idf != 0] = np.nan
+    return out.reshape(rows, cols)
+
+
+def _nearest_walkable(
+    ok: np.ndarray,
+    cols: int,
+    rows: int,
+    cell: float,
+    min_x: float,
+    max_y: float,
+    xy: Sequence[float],
+) -> int:
+    c0 = max(0, min(cols - 1, int(math.floor((xy[0] - min_x) / cell + 0.5))))
+    r0 = max(0, min(rows - 1, int(math.floor((max_y - xy[1]) / cell + 0.5))))
+    if ok[r0 * cols + c0]:
+        return r0 * cols + c0
+    for rad in range(1, max(cols, rows) + 1):
+        best, best_d = -1, math.inf
+        for r in range(max(0, r0 - rad), min(rows - 1, r0 + rad) + 1):
+            for c in range(max(0, c0 - rad), min(cols - 1, c0 + rad) + 1):
+                if abs(r - r0) != rad and abs(c - c0) != rad:
+                    continue
+                idx = r * cols + c
+                if not ok[idx]:
+                    continue
+                d = (r - r0) ** 2 + (c - c0) ** 2
+                if d < best_d:
+                    best_d, best = d, idx
+        if best >= 0:
+            return best
+    return -1
+
+
+_DR = (-1, -1, -1, 0, 0, 1, 1, 1)
+_DC = (-1, 0, 1, -1, 1, -1, 0, 1)
+_DL = (math.sqrt(2), 1.0, math.sqrt(2), 1.0, 1.0, math.sqrt(2), 1.0, math.sqrt(2))
+
+
+def _a_star(
+    cols: int, rows: int, start: int, end: int, ok: np.ndarray, penalty: np.ndarray
+) -> Optional[list[int]]:
+    """8-connected A* without corner cutting; returns cell indices start..end."""
+    n = cols * rows
+    g = np.full(n, math.inf)
+    prev = np.full(n, -1, dtype=np.int64)
+    closed = np.zeros(n, dtype=bool)
+    end_r, end_c = divmod(end, cols)
+    g[start] = 0.0
+    sr, sc = divmod(start, cols)
+    heap: list[tuple[float, int, int]] = [(math.hypot(sr - end_r, sc - end_c), 0, start)]
+    counter = 1
+    while heap:
+        _, _, cur = heapq.heappop(heap)
+        if cur == end:
+            break
+        if closed[cur]:
+            continue
+        closed[cur] = True
+        r, c = divmod(cur, cols)
+        base = g[cur]
+        for k in range(8):
+            nr, nc = r + _DR[k], c + _DC[k]
+            if nr < 0 or nr >= rows or nc < 0 or nc >= cols:
+                continue
+            nxt = nr * cols + nc
+            if closed[nxt] or not ok[nxt]:
+                continue
+            if _DR[k] != 0 and _DC[k] != 0 and (not ok[r * cols + nc] or not ok[nr * cols + c]):
+                continue
+            cand = base + _DL[k] * penalty[nxt]
+            if cand < g[nxt]:
+                g[nxt] = cand
+                prev[nxt] = cur
+                heapq.heappush(heap, (cand + math.hypot(nr - end_r, nc - end_c), counter, nxt))
+                counter += 1
+    if not math.isfinite(g[end]):
+        return None
+    cells = []
+    cur = end
+    while cur >= 0:
+        cells.append(int(cur))
+        if cur == start:
+            break
+        cur = int(prev[cur])
+    cells.reverse()
+    return cells
+
+
+def _summarize(
+    cells: list[int],
+    route_type: str,
+    label: str,
+    color: str,
+    cols: int,
+    cell: float,
+    min_x: float,
+    max_y: float,
+    grids: dict[str, Optional[np.ndarray]],
+) -> dict[str, Any]:
+    coords = [(min_x + (i % cols) * cell, max_y - (i // cols) * cell) for i in cells]
+    length = sum(
+        math.hypot(coords[i][0] - coords[i - 1][0], coords[i][1] - coords[i - 1][1])
+        for i in range(1, len(coords))
+    )
+
+    def mean_of(arr: Optional[np.ndarray]) -> float:
+        if arr is None:
+            return math.nan
+        v = arr[cells]
+        v = v[np.isfinite(v)]
+        return float(v.mean()) if v.size else math.nan
+
+    shade_pct = math.nan
+    sh = grids["shade"]
+    if sh is not None:
+        v = sh[cells]
+        v = v[np.isfinite(v)]
+        if v.size:
+            shade_pct = float(np.where(v > 1.01, v, v * 100).mean())
+    return {
+        "route_type": route_type,
+        "label": label,
+        "color": color,
+        "cells": cells,
+        "coords": coords,
+        "length_m": length,
+        "mean_utci_c": mean_of(grids["utci"]),
+        "shade_pct": shade_pct,
+        "mean_gvi_pct": mean_of(grids["gvi"]),
+        "mean_noise_dba": mean_of(grids["noise"]),
+        "walk_score": mean_of(grids["walk"]),
+    }
+
+
+def find_cool_route(
+    *,
+    walk_score: Any,
+    cols: int,
+    rows: int,
+    cell: float,
+    min_x: float,
+    max_y: float,
+    start_xy: Sequence[float],
+    end_xy: Sequence[float],
+    ids: Any = None,
+    utci_grid: Any = None,
+    shade_grid: Any = None,
+    gvi_grid: Any = None,
+    noise_grid: Any = None,
+    cool_bias: float = 2.8,
+) -> Optional[dict[str, Any]]:
+    """Compare the shortest obstacle-free route with the coolest route.
+
+    Step costs of the cool route are ``1 + bias * discomfort**1.5`` with
+    ``discomfort = (100 - walk_score) / 100``. Returns ``None`` when no route
+    exists, else a dict with ``shortest``, ``coolest``, ``detour_pct``,
+    ``utci_delta_c``, ``shade_gain_pct`` and ``walk_score_gain``.
+    """
+    n = cols * rows
+    ws = _flat(walk_score)
+    idf = _flat(ids)
+    ok = np.ones(n, dtype=bool)
+    if idf is not None:
+        ok &= idf == 0
+    if ws is not None:
+        ok &= np.isfinite(ws)
+    start = _nearest_walkable(ok, cols, rows, cell, min_x, max_y, start_xy)
+    end = _nearest_walkable(ok, cols, rows, cell, min_x, max_y, end_xy)
+    if start < 0 or end < 0:
+        return None
+    shortest_cells = _a_star(cols, rows, start, end, ok, np.ones(n))
+    if shortest_cells is None:
+        return None
+    bias = max(0.2, cool_bias)
+    sc = np.full(n, 50.0) if ws is None else np.where(np.isfinite(ws), ws, 50.0)
+    discomfort = np.clip((100 - sc) / 100, 0, 1)
+    coolest_cells = _a_star(cols, rows, start, end, ok, 1 + bias * discomfort**1.5)
+    if coolest_cells is None:
+        coolest_cells = shortest_cells
+    grids = {
+        "walk": ws,
+        "utci": _flat(utci_grid),
+        "shade": _flat(shade_grid),
+        "gvi": _flat(gvi_grid),
+        "noise": _flat(noise_grid),
+    }
+    shortest = _summarize(
+        shortest_cells, "shortest", "Shortest path", "#e4572e", cols, cell, min_x, max_y, grids
+    )
+    coolest = _summarize(
+        coolest_cells,
+        "coolest",
+        "Coolest & shaded path",
+        "#1d8f5f",
+        cols,
+        cell,
+        min_x,
+        max_y,
+        grids,
+    )
+
+    def delta(key: str) -> float:
+        a, b = coolest[key], shortest[key]
+        return a - b if math.isfinite(a) and math.isfinite(b) else math.nan
+
+    detour = (
+        (coolest["length_m"] - shortest["length_m"]) / shortest["length_m"] * 100
+        if shortest["length_m"] > 0
+        else 0.0
+    )
+    return {
+        "shortest": shortest,
+        "coolest": coolest,
+        "detour_pct": detour,
+        "utci_delta_c": delta("mean_utci_c"),
+        "shade_gain_pct": delta("shade_pct"),
+        "walk_score_gain": delta("walk_score"),
+    }