zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/weather.py

@@ -0,0 +1,373 @@
+"""Weather: EnergyPlus EPW parsing, monthly summaries, wind rose, annual
+sun-direction bins for radiation, and a clear-sky year when no EPW exists.
+
+Ported from the 02Geo3D QGIS plugin (``web/src/core/weather.js``).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional, Sequence, Union
+
+import numpy as np
+
+from .solar import solar_position, sun_vector
+
+__all__ = [
+    "MONTH_NAMES",
+    "Weather",
+    "annual_sun_bins",
+    "clear_sky_year",
+    "conditions_at",
+    "hour_index",
+    "monthly_summary",
+    "parse_epw",
+    "read_epw",
+    "typical_doy",
+    "wind_rose",
+]
+
+MONTH_DAYS = (31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
+MONTH_START = tuple(int(x) for x in np.concatenate(([0], np.cumsum(MONTH_DAYS)[:-1])))
+MONTH_NAMES = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
+HOURS = 8760
+
+_NUMERIC_ROW = re.compile(r"^\s*-?\d")
+
+
+@dataclass
+class Weather:
+    """Hourly weather for a 365-day typical year (8760 records).
+
+    Arrays are indexed by hour of the year (0 = 1 January, hour ending 01:00).
+    Fields that a source does not provide (e.g. air temperature for a
+    :func:`clear_sky_year`) are ``None``.
+    """
+
+    location: dict[str, Any]
+    month: np.ndarray
+    day: np.ndarray
+    hour: np.ndarray
+    ghi: np.ndarray
+    dni: np.ndarray
+    dhi: np.ndarray
+    dry_bulb: Optional[np.ndarray] = None
+    dew_point: Optional[np.ndarray] = None
+    rh: Optional[np.ndarray] = None
+    pressure: Optional[np.ndarray] = None
+    ir: Optional[np.ndarray] = None
+    wind_dir: Optional[np.ndarray] = None
+    wind_speed: Optional[np.ndarray] = None
+    sky_cover: Optional[np.ndarray] = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def hours(self) -> int:
+        return int(self.month.shape[0])
+
+
+def typical_doy(month: int, day: int) -> int:
+    """Day of year in a 365-day typical year."""
+    return MONTH_START[int(month) - 1] + int(day)
+
+
+def _num(text: str, missing: float, fallback: float) -> float:
+    try:
+        v = float(text)
+    except (TypeError, ValueError):
+        return fallback
+    return v if math.isfinite(v) and v < missing else fallback
+
+
+def parse_epw(text: str) -> Weather:
+    """Parse EnergyPlus EPW text into a :class:`Weather`.
+
+    Missing values use the EPW sentinels and fall back to neutral defaults.
+    Leap-year files carry 29 February: it is dropped so the year has 8760 hours.
+
+    Raises:
+        ValueError: if the text has no LOCATION line or fewer than 8760 records.
+    """
+    lines = re.split(r"\r?\n", text)
+    loc = [s.strip() for s in lines[0].split(",")] if lines else []
+    if not loc or loc[0].upper() != "LOCATION" or len(loc) < 10:
+        raise ValueError("Not an EPW file (no LOCATION line).")
+    location: dict[str, Any] = {
+        "city": loc[1],
+        "region": loc[2],
+        "country": loc[3],
+        "source": loc[4],
+        "wmo": loc[5],
+        "lat": _num(loc[6], math.inf, math.nan),
+        "lon": _num(loc[7], math.inf, math.nan),
+        "utc_offset": _num(loc[8], math.inf, math.nan),
+        "elevation": _num(loc[9], math.inf, math.nan),
+    }
+    rows = [ln.split(",") for ln in lines[8:] if ln and _NUMERIC_ROW.match(ln)]
+    if len(rows) < HOURS:
+        raise ValueError(f"EPW has {len(rows)} hourly records; {HOURS} are required.")
+
+    n = HOURS
+    month = np.zeros(n, dtype=np.uint8)
+    day = np.zeros(n, dtype=np.uint8)
+    hour = np.zeros(n, dtype=np.uint8)
+    cols = {
+        k: np.zeros(n)
+        for k in (
+            "dry_bulb",
+            "dew_point",
+            "rh",
+            "pressure",
+            "ir",
+            "ghi",
+            "dni",
+            "dhi",
+            "wind_dir",
+            "wind_speed",
+            "sky_cover",
+        )
+    }
+    spec = (
+        ("dry_bulb", 6, 99.9, 20.0, False),
+        ("dew_point", 7, 99.9, 10.0, False),
+        ("rh", 8, 999, 50.0, False),
+        ("pressure", 9, 999999, 101325.0, False),
+        ("ir", 12, 9999, math.nan, False),
+        ("ghi", 13, 9999, 0.0, True),
+        ("dni", 14, 9999, 0.0, True),
+        ("dhi", 15, 9999, 0.0, True),
+        ("wind_dir", 20, 999, 0.0, False),
+        ("wind_speed", 21, 999, 0.0, True),
+        ("sky_cover", 22, 99, 5.0, False),
+    )
+    k = 0
+    for r in rows:
+        if k >= n:
+            break
+        if len(r) < 23:
+            r = r + [""] * (23 - len(r))
+        m = int(_num(r[1], math.inf, 0))
+        d = int(_num(r[2], math.inf, 0))
+        if m == 2 and d == 29:
+            continue
+        month[k] = m
+        day[k] = d
+        hour[k] = int(_num(r[3], math.inf, 0))
+        for name, idx, missing, fallback, nonneg in spec:
+            v = _num(r[idx], missing, fallback)
+            cols[name][k] = max(0.0, v) if nonneg else v
+        k += 1
+    if k < n:
+        raise ValueError(f"EPW ended before {HOURS} hours.")
+    return Weather(location=location, month=month, day=day, hour=hour, **cols)  # type: ignore[arg-type]
+
+
+def read_epw(path: Union[str, Path]) -> Weather:
+    """Read and parse an EPW file from disk (UTF-8, Latin-1 fallback)."""
+    raw = Path(path).read_bytes()
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        text = raw.decode("latin-1")
+    return parse_epw(text)
+
+
+def hour_index(month: int, day: int, hour_ending: int) -> int:
+    """Index of the EPW record for a month, day and clock hour (1..24 = hour ending)."""
+    return (typical_doy(month, day) - 1) * 24 + (int(hour_ending) - 1)
+
+
+def monthly_summary(w: Weather) -> list[dict[str, Any]]:
+    """Monthly mean/min/max temperature, mean RH and wind, and GHI sum (kWh/m2)."""
+    out: list[dict[str, Any]] = []
+    for m, name in enumerate(MONTH_NAMES, start=1):
+        sel = w.month == m
+        cnt = int(sel.sum())
+        rec: dict[str, Any] = {
+            "name": name,
+            "t_mean": 0.0,
+            "t_min": math.inf,
+            "t_max": -math.inf,
+            "rh": 0.0,
+            "ghi_kwh": float(w.ghi[sel].sum() / 1000),
+            "wind": 0.0,
+            "n": cnt,
+        }
+        if cnt:
+            if w.dry_bulb is not None:
+                t = w.dry_bulb[sel]
+                rec.update(t_mean=float(t.mean()), t_min=float(t.min()), t_max=float(t.max()))
+            if w.rh is not None:
+                rec["rh"] = float(w.rh[sel].mean())
+            if w.wind_speed is not None:
+                rec["wind"] = float(w.wind_speed[sel].mean())
+        out.append(rec)
+    return out
+
+
+def _filter(w: Weather, months: Optional[Sequence[int]], hours: Optional[Sequence[int]]) -> Any:
+    sel = np.ones(w.hours, dtype=bool)
+    if months:
+        sel &= np.isin(w.month, list(months))
+    if hours:
+        sel &= np.isin(w.hour, list(hours))
+    return sel
+
+
+def wind_rose(
+    w: Weather,
+    sectors: int = 16,
+    classes: Sequence[float] = (0.5, 2, 4, 6, 8, 11),
+    months: Optional[Sequence[int]] = None,
+    hours: Optional[Sequence[int]] = None,
+) -> dict[str, Any]:
+    """Wind rose: frequency (fraction of hours) per direction sector and speed class.
+
+    Calm hours (speed below ``classes[0]``) are counted separately. Returns a
+    dict with ``freq`` (sectors x classes), ``sector_freq``, ``calm``,
+    ``mean_speed``, ``prevailing_direction`` (degrees) and ``prevailing_speed``.
+    """
+    if w.wind_speed is None or w.wind_dir is None:
+        raise ValueError("weather has no wind data")
+    cls = np.asarray(classes, dtype=float)
+    sel = _filter(w, months, hours)
+    v = w.wind_speed[sel].astype(float)
+    dirs = w.wind_dir[sel].astype(float)
+    total = int(v.size)
+    calm_mask = v < cls[0]
+    sector = np.floor(np.mod(dirs, 360) / (360 / sectors) + 0.5).astype(int) % sectors
+    # Speed class: first j>=1 with v < classes[j] gives j-1, else the last class.
+    c = np.searchsorted(cls, v, side="right") - 1
+    c = np.clip(c, 0, len(cls) - 1)
+    table = np.zeros((sectors, len(cls)))
+    ok = ~calm_mask
+    np.add.at(table, (sector[ok], c[ok]), 1)
+    freq = table / total if total else table
+    sector_freq = freq.sum(axis=1)
+    prevailing = int(np.argmax(sector_freq)) if sectors else 0
+    p = ok & (sector == prevailing)
+    return {
+        "sectors": sectors,
+        "classes": list(cls),
+        "freq": freq,
+        "sector_freq": sector_freq,
+        "calm": float(calm_mask.sum() / total) if total else 0.0,
+        "mean_speed": float(v.mean()) if total else 0.0,
+        "prevailing_direction": prevailing * (360 / sectors),
+        "prevailing_speed": float(v[p].mean()) if p.any() else 0.0,
+    }
+
+
+# ASHRAE clear-sky model constants per month (A in W/m2, B, C; ASHRAE
+# Handbook of Fundamentals, 1985): DNI = A exp(-B / sin(altitude)), DHI = C DNI.
+ASHRAE_CLEAR = (
+    (1230, 0.142, 0.058),
+    (1215, 0.144, 0.060),
+    (1186, 0.156, 0.071),
+    (1136, 0.180, 0.097),
+    (1104, 0.196, 0.121),
+    (1088, 0.205, 0.134),
+    (1085, 0.207, 0.136),
+    (1107, 0.201, 0.122),
+    (1151, 0.177, 0.092),
+    (1192, 0.160, 0.073),
+    (1221, 0.149, 0.063),
+    (1233, 0.142, 0.057),
+)
+
+
+def clear_sky_year(lat: float, lon: float, utc_offset: float) -> Weather:
+    """Hourly clear-sky DNI/DHI/GHI (Wh/m2 per hour): an upper bound with no clouds."""
+    n = HOURS
+    month = np.zeros(n, dtype=np.uint8)
+    day = np.zeros(n, dtype=np.uint8)
+    hour = np.zeros(n, dtype=np.uint8)
+    ghi = np.zeros(n)
+    dni = np.zeros(n)
+    dhi = np.zeros(n)
+    k = 0
+    for m in range(1, 13):
+        a, b, c = ASHRAE_CLEAR[m - 1]
+        for d in range(1, MONTH_DAYS[m - 1] + 1):
+            doy = typical_doy(m, d)
+            for h in range(1, 25):
+                month[k], day[k], hour[k] = m, d, h
+                p = solar_position(doy, h - 0.5, lat, lon, utc_offset)
+                if p.elevation > 0.0175:
+                    s = math.sin(p.elevation)
+                    beam = a * math.exp(-b / s)
+                    dni[k] = beam
+                    dhi[k] = c * beam
+                    ghi[k] = beam * s + c * beam
+                k += 1
+    loc = {"lat": lat, "lon": lon, "utc_offset": utc_offset, "city": "Clear sky", "clear_sky": True}
+    return Weather(location=loc, month=month, day=day, hour=hour, ghi=ghi, dni=dni, dhi=dhi)
+
+
+def annual_sun_bins(
+    w: Weather,
+    lat: float,
+    lon: float,
+    utc_offset: float,
+    months: Optional[Sequence[int]] = None,
+    alt_step_deg: float = 5,
+    az_step_deg: float = 7.5,
+) -> dict[str, Any]:
+    """Bin the year's direct-beam hours into sky patches.
+
+    Each patch becomes one direction (the DNI-weighted mean sun vector of its
+    hours, scene axes +x east, +y up, -z north) with the patch's DNI sum in
+    Wh/m2 as weight. Also returns DHI, GHI and DNI sums.
+
+    Returns:
+        ``{"directions": [{"dir": (x, y, z), "weight": wh}], "dhi_sum", "ghi_sum", "dni_sum"}``
+    """
+    sel = _filter(w, months, None)
+    bins: dict[int, list[float]] = {}
+    dhi_sum = float(w.dhi[sel].sum())
+    ghi_sum = float(w.ghi[sel].sum())
+    dni_sum = 0.0
+    alt_step = math.radians(alt_step_deg)
+    az_step = math.radians(az_step_deg)
+    for i in np.nonzero(sel & (w.dni > 0))[0]:
+        dni = float(w.dni[i])
+        p = solar_position(
+            typical_doy(int(w.month[i]), int(w.day[i])), int(w.hour[i]) - 0.5, lat, lon, utc_offset
+        )
+        if p.elevation <= 0.0087:  # below 0.5 degrees
+            continue
+        dni_sum += dni
+        key = int(math.floor(p.elevation / alt_step)) * 1000 + int(math.floor(p.azimuth / az_step))
+        v = sun_vector(p.elevation, p.azimuth)
+        b = bins.setdefault(key, [0.0, 0.0, 0.0, 0.0])
+        b[0] += v[0] * dni
+        b[1] += v[1] * dni
+        b[2] += v[2] * dni
+        b[3] += dni
+    directions = []
+    for x, y, z, wt in bins.values():
+        length = math.sqrt(x * x + y * y + z * z) or 1.0
+        directions.append({"dir": (x / length, y / length, z / length), "weight": wt})
+    return {"directions": directions, "dhi_sum": dhi_sum, "ghi_sum": ghi_sum, "dni_sum": dni_sum}
+
+
+def _at(arr: Optional[np.ndarray], i: int) -> Optional[float]:
+    return None if arr is None else float(arr[i])
+
+
+def conditions_at(w: Weather, month: int, day: int, hour_ending: int) -> dict[str, Optional[float]]:
+    """Hourly conditions for comfort analysis (``None`` for fields the source lacks)."""
+    i = hour_index(month, day, hour_ending)
+    return {
+        "air_temp": _at(w.dry_bulb, i),
+        "rh": _at(w.rh, i),
+        "wind_speed": _at(w.wind_speed, i),
+        "wind_dir": _at(w.wind_dir, i),
+        "ghi": float(w.ghi[i]),
+        "dni": float(w.dni[i]),
+        "dhi": float(w.dhi[i]),
+        "ir": _at(w.ir, i),
+    }

zero2geospatial3d/web/index.html

@@ -0,0 +1,50 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>02 Geo3D Analyzer</title>
+  <link rel="icon" href="data:,">
+  <link rel="stylesheet" href="./src/style.css">
+  <script type="importmap">
+    {
+      "imports": {
+        "three": "./vendor/three/three.module.js",
+        "three/addons/": "./vendor/three/addons/"
+      }
+    }
+  </script>
+</head>
+<body>
+  <div id="app">
+    <header id="topbar">
+      <div class="brand"><span class="logo">02</span><span>Geo3D Analyzer</span></div>
+      <div id="scene-title" class="scene-title"></div>
+      <div id="sun-clock" class="sun-clock"></div>
+      <div id="fps" class="fps"></div>
+      <a href="https://geophilo.com/zero2geospatial3d/" target="_blank" rel="noopener" class="topbar-manual" title="Open the 02 Geo3D Analyzer Reference Manual">Manual ↗</a>
+    </header>
+    <aside id="sidebar">
+      <nav id="tabs"></nav>
+      <div id="panels"></div>
+    </aside>
+    <main id="view">
+      <div id="tool-hint" class="tool-hint" hidden></div>
+      <div id="legend" class="legend" hidden></div>
+      <div id="inspector" class="inspector" hidden></div>
+      <div id="empty" class="empty" hidden>
+        <h2>No scene to show</h2>
+        <p>Open the viewer from QGIS: <b>02 Geo3D Analyzer</b> panel → <b>Open in 3D</b>.</p>
+        <p class="detail"></p>
+      </div>
+      <div id="toast" class="toast"></div>
+    </main>
+    <footer id="statusbar">
+      <span id="status-text">Starting …</span>
+      <span id="status-progress" class="progress" hidden><span></span></span>
+      <span class="hint">Drag to orbit · right-drag to pan · wheel to zoom · click a building to inspect</span>
+    </footer>
+  </div>
+  <script type="module" src="./src/main.js"></script>
+</body>
+</html>