zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/daylight.py

@@ -0,0 +1,337 @@
+"""Daylight to neighbouring windows after BRE 209 and party-wall detection.
+
+Seen from the centre of a neighbour's lowest window, in a section at right
+angles to the window wall, new building rising more than 25 degrees above the
+horizontal may take noticeable daylight; it then passes if the window keeps at
+least 0.8 times its former vertical sky component (VSC). The VSC is that of a
+long obstruction at the subtended angle under the CIE overcast sky (closed
+form :func:`vsc_long`), a screening on the safe side.
+
+:func:`prepare_rule` is run once for a set of neighbour walls and buildings
+whose heights change; :func:`check_rule` then costs a few operations per
+window, so it can sit inside an optimiser.
+
+Rings are sequences of ``(x, y)`` in local metres.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any, Optional, Sequence
+
+import numpy as np
+
+__all__ = [
+    "BRE_FACTOR",
+    "VSC_OPEN",
+    "VSC_TARGET",
+    "vsc_long",
+    "ray_to_rings",
+    "wall_samples",
+    "RulePrep",
+    "prepare_rule",
+    "check_rule",
+    "vsc_directions",
+    "allowed_angle",
+    "reach25",
+    "cover_index",
+    "cover_at",
+    "is_open",
+]
+
+Ring = Sequence[Sequence[float]]
+
+_TAN25 = math.tan(math.radians(25))
+#: BRE 209: a loss to less than 0.8 times the former value is noticeable.
+BRE_FACTOR = 0.8
+
+
+def vsc_long(angle: float) -> float:
+    """VSC (0..1) of a window facing a long obstruction ``angle`` radians high.
+
+    ``VSC(t) = [(pi/2)(1 - sin t) + (4/3) cos^2 t] / (7 pi / 3)`` under the
+    CIE standard overcast sky: 39.6 % for an open window, 27.3 % at 25 deg.
+    """
+    t = max(0.0, min(math.pi / 2, angle))
+    return ((math.pi / 2) * (1 - math.sin(t)) + (4 / 3) * math.cos(t) ** 2) / (7 * math.pi / 3)
+
+
+#: VSC of an unobstructed vertical window (0.396).
+VSC_OPEN = vsc_long(0.0)
+#: BRE 209: a window with a VSC of 27 % or more keeps enough daylight.
+VSC_TARGET = 0.27
+
+
+def _signed_area(ring: Ring) -> float:
+    a = 0.0
+    j = len(ring) - 1
+    for i in range(len(ring)):
+        a += ring[j][0] * ring[i][1] - ring[i][0] * ring[j][1]
+        j = i
+    return a / 2
+
+
+def ray_to_rings(px: float, py: float, dx: float, dy: float, rings: Sequence[Ring]) -> float:
+    """Distance along the ray ``p + t d`` (t > 0) to the nearest ring edge, or ``inf``."""
+    best = math.inf
+    for ring in rings:
+        j = len(ring) - 1
+        for i in range(len(ring)):
+            ax, ay = ring[j][0], ring[j][1]
+            ex, ey = ring[i][0] - ax, ring[i][1] - ay
+            j = i
+            den = dx * ey - dy * ex
+            if abs(den) < 1e-12:
+                continue
+            wx, wy = ax - px, ay - py
+            t = (wx * ey - wy * ex) / den
+            u = (wx * dy - wy * dx) / den
+            if t > 1e-9 and 0 <= u <= 1 and t < best:
+                best = t
+    return best
+
+
+def _inside_ring(x: float, y: float, ring: Ring) -> bool:
+    odd = False
+    j = len(ring) - 1
+    for i in range(len(ring)):
+        xi, yi = ring[i][0], ring[i][1]
+        xj, yj = ring[j][0], ring[j][1]
+        if (yi > y) != (yj > y) and x < (xj - xi) * (y - yi) / (yj - yi) + xi:
+            odd = not odd
+        j = i
+    return odd
+
+
+def _inside(x: float, y: float, rings: Sequence[Ring]) -> bool:
+    odd = False
+    for ring in rings:
+        if _inside_ring(x, y, ring):
+            odd = not odd
+    return odd
+
+
+def wall_samples(ring: Ring, step: float = 3.0) -> list[dict[str, float]]:
+    """Window samples every ``step`` metres on the walls, with outward normals.
+
+    Returns dicts with ``x``, ``y``, ``nx``, ``ny``; edges shorter than 1 m
+    are skipped. Works for either ring orientation.
+    """
+    out: list[dict[str, float]] = []
+    ccw = _signed_area(ring) > 0
+    j = len(ring) - 1
+    for i in range(len(ring)):
+        ax, ay = ring[j][0], ring[j][1]
+        ex, ey = ring[i][0] - ax, ring[i][1] - ay
+        j = i
+        length = math.hypot(ex, ey)
+        if length < 1:
+            continue
+        nx = (ey if ccw else -ey) / length
+        ny = (-ex if ccw else ex) / length
+        n = max(1, int(math.floor(length / step + 0.5)))
+        for k in range(n):
+            s = (k + 0.5) / n
+            out.append({"x": ax + ex * s, "y": ay + ey * s, "nx": nx + 0.0, "ny": ny + 0.0})
+    return out
+
+
+@dataclass
+class RulePrep:
+    """Window/target pairs prepared by :func:`prepare_rule`."""
+
+    windows: int
+    sample_z: np.ndarray
+    now_tan: np.ndarray
+    owner: np.ndarray
+    pair_start: np.ndarray
+    pair_target: np.ndarray
+    pair_dist: np.ndarray
+
+
+def prepare_rule(
+    neighbours: Sequence[dict[str, Any]],
+    targets: Sequence[dict[str, Any]],
+    tops_now: Sequence[float],
+    *,
+    step: float = 3.0,
+    max_dist: float = 200.0,
+    party_wall: float = 1.0,
+) -> RulePrep:
+    """Pair neighbour windows with the target buildings in front of them.
+
+    Args:
+        neighbours: ``[{"ring": ring, "window_z": z}, ...]`` outer ring and
+            absolute window-centre height of each neighbour.
+        targets: ``[{"rings": [ring, ...]}, ...]`` footprints whose heights change.
+        tops_now: current absolute roof heights of the targets.
+        max_dist: targets farther than this are ignored.
+        party_wall: hits closer than this are a shared wall, not a window.
+    """
+    sample_z: list[float] = []
+    now_tan: list[float] = []
+    owner: list[int] = []
+    pair_start = [0]
+    pair_target: list[int] = []
+    pair_dist: list[float] = []
+    for k, nb in enumerate(neighbours):
+        wz = float(nb.get("window_z", nb.get("windowZ", 0.0)))
+        for s in wall_samples(nb["ring"], step):
+            before = len(pair_target)
+            shared = False
+            for ti, t in enumerate(targets):
+                off = party_wall * 0.5
+                if _inside(s["x"] + s["nx"] * off, s["y"] + s["ny"] * off, t["rings"]):
+                    shared = True
+                    break
+                d = ray_to_rings(s["x"], s["y"], s["nx"], s["ny"], t["rings"])
+                if d < party_wall:
+                    shared = True
+                    break
+                if d <= max_dist:
+                    pair_target.append(ti)
+                    pair_dist.append(d)
+            if shared or len(pair_target) == before:
+                del pair_target[before:]
+                del pair_dist[before:]
+                continue
+            now = 0.0
+            for p in range(before, len(pair_target)):
+                now = max(now, (tops_now[pair_target[p]] - wz) / pair_dist[p])
+            sample_z.append(wz)
+            now_tan.append(now)
+            owner.append(k)
+            pair_start.append(len(pair_target))
+    return RulePrep(
+        windows=len(sample_z),
+        sample_z=np.asarray(sample_z, dtype=float),
+        now_tan=np.asarray(now_tan, dtype=float),
+        owner=np.asarray(owner, dtype=np.int64),
+        pair_start=np.asarray(pair_start, dtype=np.int64),
+        pair_target=np.asarray(pair_target, dtype=np.int64),
+        pair_dist=np.asarray(pair_dist, dtype=float),
+    )
+
+
+def check_rule(prep: RulePrep, tops: Sequence[float]) -> dict[str, float]:
+    """Check a design against the 25-degree / 0.8 x VSC rule.
+
+    Returns ``{"failing", "excess_deg", "worst_deg", "neighbours_hit"}`` where
+    ``excess_deg`` sums how far failing windows' obstructions rise above the
+    highest angle they would still pass at.
+    """
+    failing = 0
+    excess = 0.0
+    worst = 0.0
+    hit: set[int] = set()
+    for s in range(prep.windows):
+        z = prep.sample_z[s]
+        tan = 0.0
+        for p in range(int(prep.pair_start[s]), int(prep.pair_start[s + 1])):
+            v = (tops[int(prep.pair_target[p])] - z) / prep.pair_dist[p]
+            if v > tan:
+                tan = v
+        if tan > worst:
+            worst = tan
+        if tan <= _TAN25 + 1e-12:
+            continue
+        allowed = allowed_angle(float(prep.now_tan[s]))
+        angle = math.atan(tan)
+        if angle > allowed + 1e-9:
+            failing += 1
+            excess += math.degrees(angle - allowed)
+            hit.add(int(prep.owner[s]))
+    return {
+        "failing": failing,
+        "excess_deg": excess,
+        "worst_deg": math.degrees(math.atan(worst)),
+        "neighbours_hit": len(hit),
+    }
+
+
+def vsc_directions(hemisphere: Sequence[Any]) -> list[dict[str, Any]]:
+    """Weight hemisphere directions so ``sum(w * vis * max(0, n.d))`` is the VSC.
+
+    ``hemisphere`` holds directions uniform in solid angle (y up), either as
+    dicts with a ``dir`` key or as plain 3-vectors.
+    """
+    n = len(hemisphere)
+    out = []
+    for d in hemisphere:
+        v = d["dir"] if isinstance(d, dict) else d
+        out.append({"dir": v, "weight": (6 / (7 * n)) * (1 + 2 * max(0.0, v[1]))})
+    return out
+
+
+_ALLOWED_CACHE: dict[int, float] = {}
+
+
+def allowed_angle(now_tan: float) -> float:
+    """Highest obstruction angle (radians) a window may have: 25 deg or 0.8 x its VSC now."""
+    key = int(math.floor(max(0.0, now_tan) * 1e4 + 0.5))
+    a = _ALLOWED_CACHE.get(key)
+    if a is not None:
+        return a
+    target = BRE_FACTOR * vsc_long(math.atan(key / 1e4))
+    lo, hi = 0.0, math.pi / 2
+    for _ in range(40):
+        mid = (lo + hi) / 2
+        if vsc_long(mid) > target:
+            lo = mid
+        else:
+            hi = mid
+    a = max(math.atan(_TAN25), lo)
+    if len(_ALLOWED_CACHE) < 50000:
+        _ALLOWED_CACHE[key] = a
+    return a
+
+
+def reach25(rise: float) -> float:
+    """Distance beyond which a roof ``rise`` metres above a window stays under 25 deg."""
+    return max(0.0, rise) / _TAN25
+
+
+# --------------------------------------------------------------------------- party walls
+
+
+def cover_index(buildings: Sequence[dict[str, Any]], cell: float = 25.0) -> dict[str, Any]:
+    """Grid index of footprint boxes for :func:`cover_at`.
+
+    ``buildings``: ``[{"id", "rings", "bottom", "top"}, ...]`` with outer rings
+    in local metres and absolute bottom / roof elevations.
+    """
+    cells: dict[tuple[int, int], list[int]] = {}
+    for k, b in enumerate(buildings):
+        pts = [p for ring in b["rings"] for p in ring]
+        if not pts:
+            continue
+        xs = [p[0] for p in pts]
+        ys = [p[1] for p in pts]
+        for cx in range(math.floor(min(xs) / cell), math.floor(max(xs) / cell) + 1):
+            for cy in range(math.floor(min(ys) / cell), math.floor(max(ys) / cell) + 1):
+                cells.setdefault((cx, cy), []).append(k)
+    return {"buildings": list(buildings), "cells": cells, "cell": cell}
+
+
+def cover_at(
+    index: dict[str, Any], x: float, y: float, own_id: Optional[Any] = None
+) -> list[list[float]]:
+    """``[bottom, top]`` spans of other buildings whose footprint holds ``(x, y)``."""
+    cell = index["cell"]
+    lst = index["cells"].get((math.floor(x / cell), math.floor(y / cell)))
+    if not lst:
+        return []
+    out = []
+    for k in lst:
+        b = index["buildings"][k]
+        if b["id"] == own_id:
+            continue
+        if any(_inside_ring(x, y, ring) for ring in b["rings"]):
+            out.append([b["bottom"], b["top"]])
+    return out
+
+
+def is_open(z: float, spans: Sequence[Sequence[float]]) -> bool:
+    """Whether a wall point at absolute height ``z`` is open to the air."""
+    return all(not (bottom <= z < top) for bottom, top in spans)

zero2geospatial3d/dispersion.py

@@ -0,0 +1,249 @@
+"""Street-canyon ventilation, normalised air age and traffic pollutant dispersion.
+
+OSPM-inspired screening: a Gaussian line-source plume downwind of road
+samples, a canyon recirculation trap where the sky view factor or the wind
+ratio is low, and deposition on tree foliage.
+
+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
+
+from .road_sources import is_solid, sample_road_lines, street_centrelines
+
+__all__ = [
+    "VENTILATION_CLASSES",
+    "ventilation_class",
+    "ventilation_efficiency",
+    "AIR_QUALITY_CLASSES",
+    "air_quality_class",
+    "pollutant_dispersion",
+]
+
+VENTILATION_CLASSES: list[dict[str, Any]] = [
+    {"min": 0.8, "max": math.inf, "label": "Well ventilated", "color": "#2b83ba"},
+    {"min": 0.5, "max": 0.8, "label": "Moderate exchange", "color": "#abdda4"},
+    {"min": 0.3, "max": 0.5, "label": "Low ventilation", "color": "#fdae61"},
+    {"min": 0, "max": 0.3, "label": "Stagnation risk", "color": "#d7191c"},
+]
+
+AIR_QUALITY_CLASSES: list[dict[str, Any]] = [
+    {"min": 0, "max": 20, "label": "Good", "color": "#2b83ba"},
+    {"min": 20, "max": 40, "label": "Moderate", "color": "#abdda4"},
+    {"min": 40, "max": 80, "label": "Elevated", "color": "#fdae61"},
+    {"min": 80, "max": math.inf, "label": "High", "color": "#d7191c"},
+]
+
+
+def ventilation_class(vei_value: float) -> Optional[dict[str, Any]]:
+    """Class dict for a Ventilation Efficiency Index value (``None`` if not finite)."""
+    if vei_value is None or not math.isfinite(vei_value):
+        return None
+    for c in VENTILATION_CLASSES:
+        if vei_value >= c["min"]:
+            return c
+    return VENTILATION_CLASSES[-1]
+
+
+def air_quality_class(ugm3: float) -> Optional[dict[str, Any]]:
+    """Class dict for a concentration in ug/m3 (``None`` if not finite)."""
+    if ugm3 is None or not math.isfinite(ugm3):
+        return None
+    for c in AIR_QUALITY_CLASSES:
+        if ugm3 < c["max"]:
+            return c
+    return AIR_QUALITY_CLASSES[-1]
+
+
+def _grid(a: Any, rows: int, cols: int) -> Optional[np.ndarray]:
+    return None if a is None else np.asarray(a, dtype=float).reshape(rows, cols)
+
+
+def ventilation_efficiency(
+    *,
+    heights: Any,
+    cols: int,
+    rows: int,
+    cell: float = 1.0,
+    wind_ratio_grid: Any = None,
+    porosity: Any = None,
+    svf: Any = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Ventilation Efficiency Index and normalised air age per cell.
+
+    ``vei = clip(0.7 * wind_ratio + 0.3 * svf, 0.02, 1.5)`` (missing inputs
+    default to 0.7); ``air_age = clip(1 / max(0.08, vei), 0.5, 12)``. Solid
+    building cells are NaN. Returns ``(vei, air_age)``.
+    """
+    h = _grid(heights, rows, cols)
+    assert h is not None
+    solid = is_solid(h, _grid(porosity, rows, cols))
+    w = _grid(wind_ratio_grid, rows, cols)
+    s = _grid(svf, rows, cols)
+    w = np.full((rows, cols), 0.7) if w is None else np.where(np.isfinite(w), w, 0.7)
+    s = np.full((rows, cols), 0.7) if s is None else np.where(np.isfinite(s), s, 0.7)
+    vei = np.clip(0.7 * w + 0.3 * s, 0.02, 1.5)
+    age = np.clip(1 / np.maximum(0.08, vei), 0.5, 12)
+    vei[solid] = np.nan
+    age[solid] = np.nan
+    return vei, age
+
+
+def _emission_sources(
+    roads: Any,
+    weights: Any,
+    cols: int,
+    rows: int,
+    cell: float,
+    heights: np.ndarray,
+    porosity: Optional[np.ndarray],
+    min_x: float,
+    max_y: float,
+) -> list[dict[str, float]]:
+    sources, given = sample_road_lines(roads, weights, max(2.0, cell))
+    if sources or given:
+        return sources
+    streets = street_centrelines(heights, porosity, cols, rows, cell, min_x, max_y, 25)
+    if streets:
+        return streets
+    mid_y = max_y - (rows // 2) * cell
+    return [{"x": min_x + c * cell, "y": mid_y, "length": cell} for c in range(cols)]
+
+
+def pollutant_dispersion(
+    *,
+    heights: Any,
+    cols: int,
+    rows: int,
+    cell: float,
+    porosity: Any = None,
+    wind_ratio_grid: Any = None,
+    svf: Any = None,
+    min_x: Optional[float] = None,
+    max_y: Optional[float] = None,
+    wind_from_deg: float = 270.0,
+    wind_speed10: float = 3.0,
+    roads: Optional[Sequence[Sequence[Sequence[float]]]] = None,
+    road_weights: Optional[Sequence[float]] = None,
+    emission_rate_ug_ms: float = 60.0,
+    background_ug_m3: float = 18.0,
+    tree_deposition_factor: float = 0.25,
+    on_progress: Optional[Callable[[float], None]] = None,
+) -> np.ndarray:
+    """Pedestrian-level traffic NO2 / PM2.5 concentration in ug/m3.
+
+    Solid building cells are NaN; other cells are clamped to
+    ``background .. 400``. ``wind_from_deg`` is the meteorological direction
+    the wind comes from (270 = westerly).
+    """
+    if min_x is None:
+        min_x = 0.5 * cell
+    if max_y is None:
+        max_y = (rows - 0.5) * cell
+    h = _grid(heights, rows, cols)
+    assert h is not None
+    por = _grid(porosity, rows, cols)
+    solid = is_solid(h, por)
+    wr = _grid(wind_ratio_grid, rows, cols)
+    sv = _grid(svf, rows, cols)
+    sources = _emission_sources(roads, road_weights, cols, rows, cell, h, por, min_x, max_y)
+
+    bin_size, reach, near = 25.0, 250.0, 30.0
+    far = 60.0
+    bins: dict[tuple[int, int], list[dict[str, float]]] = {}
+    for src in sources:
+        key = (math.floor(src["x"] / bin_size), math.floor(src["y"] / bin_size))
+        bins.setdefault(key, []).append(src)
+    merged: dict[tuple[int, int], list[dict[str, float]]] = {}
+    for key, members in bins.items():
+        length = sum(m["length"] for m in members)
+        if length > 0:
+            x = sum(m["x"] * m["length"] for m in members) / length
+            y = sum(m["y"] * m["length"] for m in members) / length
+            merged[key] = [{"x": x, "y": y, "length": length}]
+        else:
+            merged[key] = []
+    span = int(math.ceil(reach / bin_size)) + 1
+    to_rad = math.radians((wind_from_deg + 180) % 360)
+    wx, wy = math.sin(to_rad), math.cos(to_rad)
+    half_diag = bin_size * math.sqrt(0.5)
+
+    tree_near = np.zeros((rows, cols), dtype=bool)
+    if por is not None:
+        pz = por > 0
+        for dr in (-1, 0, 1):
+            for dc in (-1, 0, 1):
+                r0, r1 = max(0, -dr), min(rows, rows - dr)
+                c0, c1 = max(0, -dc), min(cols, cols - dc)
+                tree_near[r0:r1, c0:c1] |= pz[r0 + dr : r1 + dr, c0 + dc : c1 + dc]
+
+    exp_z_num = 0.5 * 1.5 * 1.5
+    out = np.empty((rows, cols))
+    for r in range(rows):
+        ry = max_y - r * cell
+        for c in range(cols):
+            if solid[r, c]:
+                out[r, c] = math.nan
+                continue
+            rx = min_x + c * cell
+            lw = wr[r, c] if wr is not None and math.isfinite(wr[r, c]) else 0.7
+            ls = sv[r, c] if sv is not None and math.isfinite(sv[r, c]) else 0.7
+            u = max(0.6, wind_speed10 * 0.65 * lw)
+            plume = 0.0
+            min_road = math.inf
+            bx0, by0 = math.floor(rx / bin_size), math.floor(ry / bin_size)
+            for gy in range(by0 - span, by0 + span + 1):
+                for gx in range(bx0 - span, bx0 + span + 1):
+                    if (gx, gy) not in bins:
+                        continue
+                    members = bins[(gx, gy)]
+                    ex = max(gx * bin_size - rx, 0.0, rx - (gx + 1) * bin_size)
+                    ey = max(gy * bin_size - ry, 0.0, ry - (gy + 1) * bin_size)
+                    edge = math.hypot(ex, ey)
+                    if edge > reach:
+                        continue
+                    if edge > far:
+                        members = merged[(gx, gy)]
+                    cxb = (gx + 0.5) * bin_size - rx
+                    cyb = (gy + 0.5) * bin_size - ry
+                    upwind = -(cxb * wx + cyb * wy) < -half_diag
+                    if upwind and edge > near:
+                        continue
+                    for src in members:
+                        dx = rx - src["x"]
+                        dy = ry - src["y"]
+                        dist = math.hypot(dx, dy)
+                        if dist < min_road:
+                            min_road = dist
+                        if dist > reach or upwind:
+                            continue
+                        d_along = dx * wx + dy * wy
+                        if d_along <= 0:
+                            continue
+                        d_cross = abs(dx * wy - dy * wx)
+                        sig_y = 2.5 + 0.18 * d_along
+                        sig_z = 1.8 + 0.12 * d_along
+                        if d_cross > 4 * sig_y:
+                            continue
+                        plume += (
+                            src["length"]
+                            * (emission_rate_ug_ms / u)
+                            / (math.pi * sig_y * sig_z)
+                            * math.exp(-0.5 * d_cross * d_cross / (sig_y * sig_y))
+                            * math.exp(-exp_z_num / (sig_z * sig_z))
+                        )
+            inc = plume
+            if min_road < 30 and (ls < 0.65 or lw < 0.45):
+                inc *= 1 + 1.4 * (1 - ls)
+            if tree_near[r, c]:
+                inc *= 1 - tree_deposition_factor
+            out[r, c] = max(background_ug_m3, min(400.0, background_ug_m3 + inc))
+        if on_progress is not None:
+            on_progress((r + 1) / rows)
+    return out