zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/__init__.py

@@ -0,0 +1,105 @@
+"""zero2geospatial3d: headless 3D terrain and building analysis.
+
+A pure-Python (numpy) port of the 02 Geo3D Analyzer QGIS plugin
+("zero2geospatial3d"): sun position and sun hours, shadow casting, sky view
+factor, solar irradiation and PV yield, UTCI / PET thermal comfort, surface
+energy balance, pedestrian wind, ventilation and traffic dispersion, ISO
+9613-2 style noise screening, BRE 209 daylight rules, green view, solar
+envelopes, walkability, terrain derivatives, sections, flooding and cut/fill,
+plus EPW weather, OpenStreetMap download and a bundled browser viewer.
+
+Quick start::
+
+    from zero2geospatial3d import Scene, Building, shading
+
+    scene = Scene.flat(200, 200, cell=2, lat=38.42, lon=27.14, utc_offset=3)
+    ring = [[-10, -10], [10, -10], [10, 10], [-10, 10], [-10, -10]]
+    scene.buildings.append(Building([[ring]], height=24))
+    hours = shading.sun_hours(scene.surface(), scene.lat, scene.lon, scene.utc_offset,
+                              month=3, day=21)
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from . import (
+    acoustics,
+    classify,
+    comfort,
+    daylight,
+    dispersion,
+    epw,
+    geo,
+    microclimate,
+    morphology,
+    nsga2,
+    osm,
+    osm_tags,
+    results,
+    road_sources,
+    scene,
+    shading,
+    solar,
+    terrain,
+    urban_form,
+    walkability,
+    weather,
+    wind,
+)
+from .comfort import mean_radiant_temperature, pet, utci
+from .grid import Grid, make_grid
+from .scene import Building, Road, Scene, Tree, load_scene
+from .shading import shadow_mask, sky_view_factor, sun_hours, viewshed
+from .solar import solar_position, sun_path, sunrise_sunset
+from .weather import Weather, clear_sky_year, parse_epw, read_epw
+
+__all__ = [
+    "__version__",
+    # data model
+    "Grid",
+    "make_grid",
+    "Scene",
+    "Building",
+    "Tree",
+    "Road",
+    "load_scene",
+    # frequently used functions
+    "solar_position",
+    "sun_path",
+    "sunrise_sunset",
+    "shadow_mask",
+    "sun_hours",
+    "sky_view_factor",
+    "viewshed",
+    "utci",
+    "pet",
+    "mean_radiant_temperature",
+    "Weather",
+    "parse_epw",
+    "read_epw",
+    "clear_sky_year",
+    # modules
+    "acoustics",
+    "classify",
+    "comfort",
+    "daylight",
+    "dispersion",
+    "epw",
+    "geo",
+    "microclimate",
+    "morphology",
+    "nsga2",
+    "osm",
+    "osm_tags",
+    "results",
+    "road_sources",
+    "scene",
+    "shading",
+    "solar",
+    "terrain",
+    "urban_form",
+    "walkability",
+    "weather",
+    "wind",
+]

zero2geospatial3d/acoustics.py

@@ -0,0 +1,284 @@
+"""Urban road-noise propagation screening.
+
+ISO 9613-2 / CNOSSOS-EU inspired: geometric divergence, air absorption,
+ground attenuation, Maekawa single-edge barrier diffraction over buildings,
+foliage attenuation through trees and a facade reflection bonus. Levels are
+pedestrian-level dB(A) on an obstacle-height grid.
+
+Grids may be flat (row-major from the north-west cell) or ``(rows, cols)``;
+``(min_x, max_y)`` is the centre of the north-west cell.
+"""
+
+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__ = [
+    "maekawa_diffraction",
+    "NOISE_CLASSES",
+    "noise_class",
+    "noise_propagation",
+    "building_facade_noise",
+]
+
+
+def maekawa_diffraction(path_diff_metres: float, freq_hz: float = 500.0) -> float:
+    """Maekawa barrier attenuation in dB, capped at 20 dB (ISO 9613-2 single edge).
+
+    Args:
+        path_diff_metres: path difference in metres (<= 0 when unobstructed).
+        freq_hz: frequency in Hz.
+    """
+    if not path_diff_metres > 0:
+        return 0.0
+    lam = 343.0 / max(20.0, freq_hz)
+    n = (2.0 / lam) * path_diff_metres
+    val = 10 * math.log10(max(1.0, 3 + 20 * max(0.0, n)))
+    return min(20.0, max(0.0, val))
+
+
+NOISE_CLASSES: list[dict[str, Any]] = [
+    {"min": 0, "max": 55, "label": "Quiet", "color": "#2b83ba"},
+    {"min": 55, "max": 65, "label": "Moderate", "color": "#abdda4"},
+    {"min": 65, "max": 70, "label": "Loud", "color": "#fdae61"},
+    {"min": 70, "max": math.inf, "label": "High noise", "color": "#d7191c"},
+]
+
+
+def noise_class(dba: float) -> Optional[dict[str, Any]]:
+    """Noise class dict for a level in dB(A), ``None`` for a non-finite value."""
+    if dba is None or not math.isfinite(dba):
+        return None
+    for c in NOISE_CLASSES:
+        if dba < c["max"]:
+            return c
+    return NOISE_CLASSES[-1]
+
+
+Source = dict[str, Any]
+
+
+def _noise_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[Source]:
+    step = max(3.0, cell * 1.5)
+    sources, given = sample_road_lines(roads, weights, step)
+    if sources or given:
+        return sources
+    streets = street_centrelines(heights, porosity, cols, rows, cell, min_x, max_y, 25)
+    if streets:
+        return streets
+    sy = max_y - (rows - 1) * cell
+    grid_step = max(1, int(math.floor(step / cell + 0.5)))
+    return [{"x": min_x + c * cell, "y": sy, "length": step} for c in range(0, cols, grid_step)]
+
+
+def _cluster(items: Sequence[Source], size: float) -> list[Source]:
+    bins: dict[tuple[int, int], Source] = {}
+    for s in items:
+        if not s["length"] > 0:
+            continue
+        key = (math.floor(s["x"] / size), math.floor(s["y"] / size))
+        b = bins.get(key)
+        if b is None:
+            b = {"x": 0.0, "y": 0.0, "length": 0.0, "members": []}
+            bins[key] = b
+        b["x"] += s["x"] * s["length"]
+        b["y"] += s["y"] * s["length"]
+        b["length"] += s["length"]
+        b["members"].append(s)
+    out = list(bins.values())
+    for b in out:
+        b["x"] /= b["length"]
+        b["y"] /= b["length"]
+    return out
+
+
+def _near_solid_facades(solid: np.ndarray, cell: float) -> np.ndarray:
+    """Open cells with a solid building within 12 m."""
+    rows, cols = solid.shape
+    rad = int(math.ceil(12 / cell))
+    near = np.zeros_like(solid)
+    for dr in range(-rad, rad + 1):
+        for dc in range(-rad, rad + 1):
+            if math.hypot(dc * cell, dr * cell) > 12:
+                continue
+            shifted = np.zeros_like(solid)
+            r0, r1 = max(0, -dr), min(rows, rows - dr)
+            c0, c1 = max(0, -dc), min(cols, cols - dc)
+            if r0 >= r1 or c0 >= c1:
+                continue
+            shifted[r0:r1, c0:c1] = solid[r0 + dr : r1 + dr, c0 + dc : c1 + dc]
+            near |= shifted
+    return near & ~solid
+
+
+def noise_propagation(
+    *,
+    heights: Any,
+    cols: int,
+    rows: int,
+    cell: float,
+    porosity: Any = None,
+    min_x: Optional[float] = None,
+    max_y: Optional[float] = None,
+    roads: Optional[Sequence[Sequence[Sequence[float]]]] = None,
+    road_weights: Optional[Sequence[float]] = None,
+    sound_power_db: float = 82.0,
+    receiver_height: float = 1.5,
+    source_height: float = 0.5,
+    ground_factor: float = 0.5,
+    max_dist: float = 400.0,
+    on_progress: Optional[Callable[[float], None]] = None,
+) -> np.ndarray:
+    """Pedestrian-level road noise Lden in dB(A), shape ``(rows, cols)``.
+
+    Solid building cells are NaN; open cells are clamped to 35..90 dB(A).
+    Without roads, street centrelines between buildings (or the south edge of
+    a scene without buildings) act as sources. Distant sources are merged in
+    two cluster levels exactly as in the web viewer.
+    """
+    if min_x is None:
+        min_x = 0.5 * cell
+    if max_y is None:
+        max_y = (rows - 0.5) * cell
+    h = np.asarray(heights, dtype=float).reshape(rows, cols)
+    por = None if porosity is None else np.asarray(porosity, dtype=float).reshape(rows, cols)
+    solid = is_solid(h, por)
+    porous = por > 0 if por is not None else np.zeros_like(solid)
+    sources = _noise_sources(roads, road_weights, cols, rows, cell, h, por, min_x, max_y)
+    cluster_size = max(8.0, 2 * max(3.0, cell * 1.5))
+    big_size = 4 * cluster_size
+    clusters = _cluster(sources, cluster_size)
+    big = _cluster(clusters, big_size)
+    near = 8 * cluster_size
+    mid = 5 * big_size
+    near_facades = _near_solid_facades(solid, cell)
+    dz = receiver_height - source_height
+    hl = h.tolist()
+    pl = porous.tolist()
+
+    def energy_from(rx: float, ry: float, src: Source, step_m: float, bonus: float) -> float:
+        dx = rx - src["x"]
+        dy = ry - src["y"]
+        dist2d = math.hypot(dx, dy)
+        if dist2d > max_dist:
+            return 0.0
+        d_direct = math.sqrt(dx * dx + dy * dy + dz * dz)
+        d = max(2.0, d_direct)
+        max_pd = 0.0
+        d_tree = 0.0
+        if dist2d >= 1:
+            n_steps = max(2, int(math.ceil(dist2d / step_m)))
+            seg = dist2d / n_steps
+            for k in range(1, n_steps):
+                t = k / n_steps
+                gc = math.floor((src["x"] + t * dx - min_x) / cell + 0.5)
+                gr = math.floor((max_y - (src["y"] + t * dy)) / cell + 0.5)
+                if gc < 0 or gc >= cols or gr < 0 or gr >= rows:
+                    continue
+                hh = hl[gr][gc]
+                if pl[gr][gc]:
+                    d_tree += seg
+                elif hh > 0 and hh > source_height + t * dz:
+                    d1 = t * dist2d
+                    d2 = (1 - t) * dist2d
+                    pd = (
+                        math.hypot(d1, hh - source_height)
+                        + math.hypot(d2, hh - receiver_height)
+                        - d_direct
+                    )
+                    if pd > max_pd:
+                        max_pd = pd
+        a_bar = maekawa_diffraction(max_pd)
+        a_tree = min(4.0, 0.08 * d_tree)
+        a_div = 20 * math.log10(d) + 8
+        a_air = 0.0019 * d  # ISO 9613-2 Table 2 at 500 Hz: about 1.9 dB/km
+        a_ground = 1.5 * ground_factor * math.log10(max(1.0, d / 2))
+        lw = sound_power_db + 10 * math.log10(max(0.1, src["length"]))
+        return 10 ** ((lw - a_div - a_air - a_ground - a_bar - a_tree + bonus) / 10)
+
+    fine = max(1.0, cell)
+    coarse = 2 * fine
+    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
+            bonus = 1.8 if near_facades[r, c] else 0.0
+            e = 0.0
+            for big_k in big:
+                d_k = math.hypot(rx - big_k["x"], ry - big_k["y"])
+                if d_k > max_dist + big_size:
+                    continue
+                if d_k > mid:
+                    e += energy_from(rx, ry, big_k, max(coarse, d_k / 24), bonus)
+                    continue
+                for k in big_k["members"]:
+                    dk = math.hypot(rx - k["x"], ry - k["y"])
+                    if dk > max_dist + cluster_size:
+                        continue
+                    if dk > near:
+                        e += energy_from(rx, ry, k, max(coarse, dk / 24), bonus)
+                    else:
+                        for src in k["members"]:
+                            e += energy_from(rx, ry, src, fine, bonus)
+            out[r, c] = max(35.0, min(90.0, 10 * math.log10(e))) if e > 0 else 35.0
+        if on_progress is not None:
+            on_progress((r + 1) / rows)
+    return out
+
+
+def building_facade_noise(
+    noise_grid: Any, ids: Any, cols: int, rows: int
+) -> dict[int, dict[str, float]]:
+    """Per-building facade noise statistics from the open cells within 2 cells.
+
+    Returns ``{building_id: {"max", "min", "mean", "quiet_facade"}}``;
+    ``quiet_facade`` is 1 when one side is below 55 dB(A) or the facades
+    differ by at least 6 dB(A).
+    """
+    result: dict[int, dict[str, float]] = {}
+    if ids is None:
+        return result
+    idf = np.asarray(ids).ravel()
+    if idf.size != cols * rows:
+        return result
+    noise = np.asarray(noise_grid, dtype=float).reshape(rows, cols)
+    idg = idf.reshape(rows, cols)
+    finite = np.isfinite(noise)
+    for key in np.unique(idf[idf > 0]):
+        mine = idg == key
+        ring = np.zeros_like(mine)
+        for dr in range(-2, 3):
+            for dc in range(-2, 3):
+                if dr == 0 and dc == 0:
+                    continue
+                r0, r1 = max(0, -dr), min(rows, rows - dr)
+                c0, c1 = max(0, -dc), min(cols, cols - dc)
+                ring[r0:r1, c0:c1] |= mine[r0 + dr : r1 + dr, c0 + dc : c1 + dc]
+        ring &= (idg != key) & finite
+        vals = noise[ring]
+        if vals.size == 0:
+            result[int(key)] = {"max": 35.0, "min": 35.0, "mean": 35.0, "quiet_facade": 1}
+            continue
+        mx, mn = float(vals.max()), float(vals.min())
+        quiet = 1 if (mn < 55 or (mx - mn) >= 6) else 0
+        result[int(key)] = {"max": mx, "min": mn, "mean": float(vals.mean()), "quiet_facade": quiet}
+    return result