zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/results.py

@@ -0,0 +1,231 @@
+"""Analysis results: payload decoding, per-building aggregation and file output.
+
+Headless counterpart of the plugin's QGIS result writer. Results are plain
+numpy arrays on a :class:`~zero2geospatial3d.grid.Grid`; they can be
+
+* summarised per building with :func:`aggregate_by_id` (mean / min / max /
+  area, as the viewer does for its ``*_roof`` fields),
+* written as an ESRI ASCII grid (:func:`write_ascii_grid`, no dependencies),
+  a ``.npy`` + JSON sidecar, or a GeoTIFF when ``rasterio`` is installed
+  (:func:`write_geotiff`, ``pip install zero2geospatial3d-sdk[geo]``),
+* received from the browser viewer (``grid`` / ``features`` / ``routes``
+  payloads posted to ``/api/result``) with :func:`save_result`.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+from typing import Any, Optional
+
+import numpy as np
+
+from .grid import Grid
+
+__all__ = [
+    "ResultError",
+    "decode_float32",
+    "encode_float32",
+    "aggregate_by_id",
+    "grid_stats",
+    "write_ascii_grid",
+    "write_geotiff",
+    "write_grid_npy",
+    "save_result",
+]
+
+
+class ResultError(RuntimeError):
+    """A malformed result payload."""
+
+
+def decode_float32(data_b64: str, count: int) -> np.ndarray:
+    """Little-endian float32 array from the viewer's base64 payload."""
+    raw = base64.b64decode(data_b64)
+    if len(raw) != count * 4:
+        raise ResultError(f"grid payload has {len(raw)} bytes, expected {count * 4}")
+    return np.frombuffer(raw, dtype="<f4").astype(np.float32)
+
+
+def encode_float32(values: np.ndarray) -> str:
+    """Inverse of :func:`decode_float32`."""
+    return base64.b64encode(np.asarray(values, dtype="<f4").tobytes()).decode("ascii")
+
+
+def grid_stats(values: np.ndarray) -> dict[str, float]:
+    """count/min/max/mean/std of the finite values (zeros when there are none)."""
+    v = np.asarray(values, dtype=float)
+    v = v[np.isfinite(v)]
+    if not v.size:
+        return {"count": 0, "min": 0.0, "max": 0.0, "mean": 0.0, "std": 0.0}
+    return {
+        "count": int(v.size),
+        "min": float(v.min()),
+        "max": float(v.max()),
+        "mean": float(v.mean()),
+        "std": float(v.std()),
+    }
+
+
+def aggregate_by_id(
+    ids: np.ndarray, values: np.ndarray, cell_area: float = 1.0
+) -> dict[int, dict[str, float]]:
+    """Per-id ``mean``, ``min``, ``max``, ``total`` (value x area) and ``area``.
+
+    Id 0 (open ground) and non-finite values are skipped.
+    """
+    ids = np.asarray(ids).ravel()
+    vals = np.asarray(values, dtype=float).ravel()
+    ok = (ids != 0) & np.isfinite(vals)
+    out: dict[int, dict[str, float]] = {}
+    if not ok.any():
+        return out
+    ids = ids[ok]
+    vals = vals[ok]
+    order = np.argsort(ids, kind="stable")
+    ids = ids[order]
+    vals = vals[order]
+    uniq, start = np.unique(ids, return_index=True)
+    ends = list(start[1:]) + [len(ids)]
+    for u, a, b in zip(uniq, start, ends):
+        chunk = vals[a:b]
+        out[int(u)] = {
+            "mean": float(chunk.mean()),
+            "min": float(chunk.min()),
+            "max": float(chunk.max()),
+            "total": float(chunk.sum() * cell_area),
+            "area": float(len(chunk) * cell_area),
+        }
+    return out
+
+
+def _key(text: Any) -> str:
+    return re.sub(r"[^a-z0-9_]+", "_", str(text or "").lower()).strip("_")[:60] or "result"
+
+
+def _unique_path(path: str) -> str:
+    if not os.path.exists(path):
+        return path
+    stem, ext = os.path.splitext(path)
+    k = 2
+    while os.path.exists(f"{stem}_{k}{ext}"):
+        k += 1
+    return f"{stem}_{k}{ext}"
+
+
+def write_ascii_grid(
+    path: str,
+    grid: Grid,
+    values: Optional[np.ndarray] = None,
+    origin: tuple[float, float] = (0.0, 0.0),
+    nodata: float = -9999.0,
+) -> str:
+    """Write an ESRI ASCII grid (``.asc``) in the scene's CRS (``origin`` added)."""
+    v = grid.values if values is None else np.asarray(values, dtype=float)
+    left = origin[0] + grid.min_x - grid.cell / 2
+    bottom = origin[1] + grid.max_y + grid.cell / 2 - grid.rows * grid.cell
+    with open(path, "w", encoding="ascii") as handle:
+        handle.write(f"ncols {grid.cols}\nnrows {grid.rows}\n")
+        handle.write(f"xllcorner {left!r}\nyllcorner {bottom!r}\n")
+        handle.write(f"cellsize {grid.cell!r}\nNODATA_value {nodata!r}\n")
+        for row in np.where(np.isfinite(v), v, nodata):
+            handle.write(" ".join(f"{x:.6g}" for x in row) + "\n")
+    return path
+
+
+def write_grid_npy(
+    path: str,
+    grid: Grid,
+    values: Optional[np.ndarray] = None,
+    meta: Optional[dict[str, Any]] = None,
+) -> str:
+    """Save ``values`` as ``.npy`` and the georeference as a ``.json`` sidecar."""
+    v = grid.values if values is None else np.asarray(values)
+    np.save(path, v)
+    side = os.path.splitext(path)[0] + ".json"
+    info = {
+        "cols": grid.cols,
+        "rows": grid.rows,
+        "cell": grid.cell,
+        "minX": grid.min_x,
+        "maxY": grid.max_y,
+    }
+    info.update(meta or {})
+    with open(side, "w", encoding="utf-8") as handle:
+        json.dump(info, handle, indent=1)
+    return path
+
+
+def write_geotiff(
+    path: str,
+    grid: Grid,
+    values: Optional[np.ndarray] = None,
+    *,
+    crs: Optional[str] = None,
+    origin: tuple[float, float] = (0.0, 0.0),
+) -> str:
+    """Write a float32 GeoTIFF (needs ``rasterio``; NaN is no data)."""
+    try:
+        import rasterio
+        from rasterio.transform import from_origin
+    except ImportError as exc:  # pragma: no cover - optional dependency
+        raise ImportError(
+            "write_geotiff needs rasterio: pip install zero2geospatial3d-sdk[geo]"
+        ) from exc
+    v = (grid.values if values is None else np.asarray(values)).astype("float32")
+    left = origin[0] + grid.min_x - grid.cell / 2
+    top = origin[1] + grid.max_y + grid.cell / 2
+    with rasterio.open(  # pragma: no cover - optional dependency
+        path,
+        "w",
+        driver="GTiff",
+        width=grid.cols,
+        height=grid.rows,
+        count=1,
+        dtype="float32",
+        crs=crs or None,
+        transform=from_origin(left, top, grid.cell, grid.cell),
+        nodata=float("nan"),
+        compress="deflate",
+    ) as dst:
+        dst.write(v, 1)
+    return path  # pragma: no cover
+
+
+def save_result(payload: dict[str, Any], out_dir: str) -> str:
+    """Store one viewer result payload under ``out_dir``; returns the file path.
+
+    ``grid`` payloads become ``<key>.npy`` + ``<key>.json``; ``features`` and
+    ``routes`` payloads are written as JSON.
+    """
+    if not isinstance(payload, dict):
+        raise ResultError("payload must be a dict")
+    kind = payload.get("type")
+    os.makedirs(out_dir, exist_ok=True)
+    name = str(payload.get("name") or payload.get("layer") or "result")
+    key = _key(payload.get("key") or name)
+    if kind == "grid":
+        g = payload.get("grid") or {}
+        try:
+            cols, rows, cell = int(g["cols"]), int(g["rows"]), float(g["cell"])
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ResultError("grid payload without cols/rows/cell") from exc
+        if cols <= 0 or rows <= 0 or cols * rows > 40_000_000 or not cell > 0:
+            raise ResultError("grid size out of range")
+        values = decode_float32(payload["data"], cols * rows).reshape(rows, cols)
+        grid = Grid(values, cell, float(g.get("minX", 0.0)), float(g.get("maxY", 0.0)))
+        path = _unique_path(os.path.join(out_dir, f"{key}.npy"))
+        return write_grid_npy(
+            path,
+            grid,
+            values,
+            {"name": name, "unit": payload.get("unit", ""), "style": payload.get("style") or {}},
+        )
+    if kind in ("features", "routes"):
+        path = _unique_path(os.path.join(out_dir, f"{key}.json"))
+        with open(path, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, ensure_ascii=False)
+        return path
+    raise ResultError(f"unknown result type {kind!r}")

zero2geospatial3d/road_sources.py

@@ -0,0 +1,141 @@
+"""Road line sources shared by the noise and traffic dispersion models.
+
+Given polylines are sampled into points that carry their share of road length
+times relative traffic; without roads, street centrelines are found between
+the buildings (the ridge of the distance to the nearest solid building).
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Optional, Sequence
+
+import numpy as np
+
+__all__ = ["STREET_TRAFFIC", "road_weight", "sample_road_lines", "street_centrelines", "is_solid"]
+
+#: Relative traffic of the streets found when no roads are given (a residential
+#: street, as for OSM ``highway=residential``).
+STREET_TRAFFIC = 0.4
+
+Source = dict[str, float]
+
+
+def road_weight(weights: Optional[Sequence[float]], q: int) -> float:
+    """Relative traffic of polyline ``q``: 1 without weights, never negative."""
+    if weights is None:
+        return 1.0
+    try:
+        w = float(weights[q])
+    except (TypeError, ValueError, IndexError):
+        return 1.0
+    return max(0.0, w) if math.isfinite(w) else 1.0
+
+
+def sample_road_lines(
+    roads: Optional[Sequence[Sequence[Sequence[float]]]],
+    weights: Optional[Sequence[float]],
+    step: float,
+) -> tuple[list[Source], bool]:
+    """Points about ``step`` metres apart along road polylines.
+
+    Each point's ``length`` is the road length it stands for times the road's
+    traffic. ``given`` is True when at least one usable polyline was passed,
+    even if all carry zero traffic (those roads stay silent, no fallback).
+    """
+    sources: list[Source] = []
+    given = False
+    if roads is None:
+        return sources, given
+    for q, poly in enumerate(roads):
+        if poly is None or len(poly) < 2:
+            continue
+        given = True
+        w = road_weight(weights, q)
+        if w == 0:
+            continue
+        for p in range(len(poly) - 1):
+            x1, y1 = float(poly[p][0]), float(poly[p][1])
+            x2, y2 = float(poly[p + 1][0]), float(poly[p + 1][1])
+            length = math.hypot(x2 - x1, y2 - y1)
+            if not length > 0:
+                continue
+            count = max(1, int(math.floor(length / step + 0.5)))
+            seg = length / count
+            for k in range(count):
+                t = (k + 0.5) / count
+                sources.append(
+                    {"x": x1 + t * (x2 - x1), "y": y1 + t * (y2 - y1), "length": seg * w}
+                )
+    return sources, given
+
+
+def is_solid(heights: np.ndarray, porosity: Optional[np.ndarray]) -> np.ndarray:
+    """Boolean mask of solid obstacle cells (height > 0 and not porous foliage)."""
+    solid = heights > 0
+    if porosity is not None:
+        solid &= ~(porosity > 0)
+    return solid
+
+
+def street_centrelines(
+    heights: Any,
+    porosity: Any,
+    cols: int,
+    rows: int,
+    cell: float,
+    min_x: float,
+    max_y: float,
+    max_half_width: float = 25.0,
+) -> list[Source]:
+    """Street centreline sources between buildings (empty without buildings).
+
+    One source per ridge cell of the two-pass chamfer distance to the nearest
+    solid building, standing for ``cell`` metres of residential street.
+    """
+    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)
+    if not solid.any():
+        return []
+    big = 1e9
+    dist = np.where(solid, 0.0, big)
+    a, b = cell, cell * math.sqrt(2)
+    # Two-pass chamfer distance; row-wise loops keep the sequential dependency.
+    for r in range(rows):
+        row = dist[r]
+        if r > 0:
+            up = dist[r - 1]
+            cand = up + a
+            cand[1:] = np.minimum(cand[1:], up[:-1] + b)
+            cand[:-1] = np.minimum(cand[:-1], up[1:] + b)
+            np.minimum(row, cand, out=row)
+        for c in range(1, cols):
+            v = row[c - 1] + a
+            if v < row[c]:
+                row[c] = v
+    for r in range(rows - 1, -1, -1):
+        row = dist[r]
+        if r < rows - 1:
+            dn = dist[r + 1]
+            cand = dn + a
+            cand[:-1] = np.minimum(cand[:-1], dn[1:] + b)
+            cand[1:] = np.minimum(cand[1:], dn[:-1] + b)
+            np.minimum(row, cand, out=row)
+        for c in range(cols - 2, -1, -1):
+            v = row[c + 1] + a
+            if v < row[c]:
+                row[c] = v
+    sources: list[Source] = []
+    for r in range(1, rows - 1):
+        for c in range(1, cols - 1):
+            d = dist[r, c]
+            if d < cell or d > max_half_width:
+                continue
+            ridge_x = d >= dist[r, c - 1] and d > dist[r, c + 1]
+            ridge_y = d >= dist[r - 1, c] and d > dist[r + 1, c]
+            if ridge_x or ridge_y:
+                sources.append(
+                    {"x": min_x + c * cell, "y": max_y - r * cell, "length": cell * STREET_TRAFFIC}
+                )
+    return sources