zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/epw.py

@@ -0,0 +1,162 @@
+"""EnergyPlus weather (EPW) files: header check, nearest-station lookup and
+download from climate.onebuilding.org (TMYx files).
+
+The bundled station index ``data/epw_stations.json.gz`` lists about 17,000
+TMYx stations (names, coordinates, time zones, elevations and download paths)
+from the location indexes published by Climate.OneBuilding.Org. Weather files
+themselves are not bundled; :func:`download_station` fetches one on request.
+Parse a downloaded file with :func:`zero2geospatial3d.weather.parse_epw`.
+"""
+
+from __future__ import annotations
+
+import gzip
+import io
+import json
+import math
+import os
+import urllib.request
+import zipfile
+from functools import lru_cache
+from typing import Any, Optional
+
+__all__ = [
+    "EpwError",
+    "INDEX_PATH",
+    "read_header",
+    "haversine_km",
+    "load_index",
+    "nearest_stations",
+    "extract_epw",
+    "download_station",
+]
+
+INDEX_PATH = os.path.join(os.path.dirname(__file__), "data", "epw_stations.json.gz")
+MAX_ZIP_BYTES = 40 * 1024 * 1024
+ALLOWED_PREFIX = "https://climate.onebuilding.org/"
+DEFAULT_TIMEOUT_S = 120.0
+
+
+class EpwError(RuntimeError):
+    """Raised for unreadable, malformed or oversized weather files."""
+
+
+def read_header(path: str) -> dict[str, Any]:
+    """Parse the LOCATION line of an EPW file: city, country, lat, lon, tz, elevation."""
+    try:
+        with open(path, encoding="latin-1") as handle:
+            first = handle.readline()
+    except OSError as exc:
+        raise EpwError(f"Cannot read {path}: {exc}") from exc
+    return parse_location_line(first)
+
+
+def parse_location_line(first: str) -> dict[str, Any]:
+    """Parse an EPW ``LOCATION,...`` record."""
+    parts = [p.strip() for p in first.split(",")]
+    if len(parts) < 10 or parts[0].upper() != "LOCATION":
+        raise EpwError("Not an EPW file (the first line is not a LOCATION record).")
+    try:
+        return {
+            "city": parts[1],
+            "region": parts[2],
+            "country": parts[3],
+            "source": parts[4],
+            "wmo": parts[5],
+            "lat": float(parts[6]),
+            "lon": float(parts[7]),
+            "utc": float(parts[8]),
+            "elevation": float(parts[9]),
+        }
+    except ValueError as exc:
+        raise EpwError(f"Malformed EPW LOCATION line: {exc}") from exc
+
+
+def haversine_km(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Great-circle distance in kilometres."""
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dp, dl = p2 - p1, math.radians(lon2 - lon1)
+    a = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
+    return 6371.0088 * 2 * math.asin(min(1.0, math.sqrt(a)))
+
+
+@lru_cache(maxsize=2)
+def _load_cached(path: str) -> dict[str, Any]:
+    with gzip.open(path, "rt", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def load_index(path: str = INDEX_PATH) -> dict[str, Any]:
+    """The station index: ``{"base": url, "columns": [...], "rows": [[lat, lon, name, path, utc, elev], ...]}``."""
+    if not os.path.isfile(path):
+        raise EpwError(f"The weather-station index is missing: {path}")
+    return _load_cached(path)
+
+
+def nearest_stations(
+    lat: float, lon: float, count: int = 5, index: Optional[dict[str, Any]] = None
+) -> list[dict[str, Any]]:
+    """The ``count`` nearest stations as dicts sorted by distance."""
+    index = index or load_index()
+    base = index.get("base", "")
+    scored = []
+    for lat_s, lon_s, station, path, utc, elev in index["rows"]:
+        scored.append(
+            (haversine_km(lat, lon, lat_s, lon_s), lat_s, lon_s, station, path, utc, elev)
+        )
+    scored.sort(key=lambda row: row[0])
+    return [
+        {
+            "distance_km": round(d, 1),
+            "lat": la,
+            "lon": lo,
+            "station": st,
+            "url": base + p,
+            "utc": utc,
+            "elevation": el,
+        }
+        for d, la, lo, st, p, utc, el in scored[:count]
+    ]
+
+
+def extract_epw(zip_bytes: bytes, target_path: str) -> str:
+    """Write the single .epw member of a OneBuilding zip to ``target_path``."""
+    if len(zip_bytes) > MAX_ZIP_BYTES:
+        raise EpwError("The weather archive is unexpectedly large.")
+    try:
+        archive = zipfile.ZipFile(io.BytesIO(zip_bytes))
+    except zipfile.BadZipFile as exc:
+        raise EpwError("The download is not a zip archive.") from exc
+    members = [m for m in archive.infolist() if m.filename.lower().endswith(".epw")]
+    if not members:
+        raise EpwError("The archive contains no .epw file.")
+    member = members[0]
+    if member.file_size > MAX_ZIP_BYTES:
+        raise EpwError("The weather file is unexpectedly large.")
+    data = archive.read(member)
+    os.makedirs(os.path.dirname(target_path) or ".", exist_ok=True)
+    with open(target_path, "wb") as handle:
+        handle.write(data)
+    read_header(target_path)
+    return target_path
+
+
+def download_station(url: str, target_path: str, timeout: float = DEFAULT_TIMEOUT_S) -> str:
+    """Download a OneBuilding TMYx zip and extract its EPW to ``target_path``.
+
+    Only ``https://climate.onebuilding.org/`` URLs are accepted (as returned by
+    :func:`nearest_stations`).
+    """
+    if not url.startswith(ALLOWED_PREFIX):
+        raise EpwError("Only climate.onebuilding.org downloads are allowed.")
+    from . import __version__
+
+    request = urllib.request.Request(
+        url, headers={"User-Agent": f"zero2geospatial3d-sdk/{__version__}"}
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as reply:  # noqa: S310
+            content = reply.read(MAX_ZIP_BYTES + 1)
+    except OSError as exc:
+        raise EpwError(f"Download failed: {exc}") from exc
+    return extract_epw(content, target_path)

zero2geospatial3d/geo.py

@@ -0,0 +1,138 @@
+"""Pure-Python geometry helpers shared by the exporter and the tests.
+
+Scene convention: coordinates are metres in a projected CRS, made local by
+subtracting ``origin`` (the centre of the scene extent). The viewer maps local
+(x, y) to Three.js as (x, height, -y), so +x is east and +y is north.
+"""
+
+from __future__ import annotations
+
+import math
+
+MAX_GRID_CELLS = 1024  # longest side of an exported raster grid
+MAX_SCENE_SIDE_M = 250000.0  # sanity limit only: local float32 coordinates stay sub-centimetre
+LARGE_SCENE_SIDE_M = 20000.0  # above this the export warns about coarse cells
+
+
+def utm_epsg_for(lon: float, lat: float) -> int:
+    """EPSG code of the WGS84 / UTM zone containing (lon, lat)."""
+    zone = int(math.floor((lon + 180.0) / 6.0) + 1)
+    zone = max(1, min(60, zone))
+    return (32600 if lat >= 0 else 32700) + zone
+
+
+def grid_shape(
+    width: float, height: float, cell: float | None, max_cells: int = MAX_GRID_CELLS
+) -> tuple[int, int, float]:
+    """(cols, rows, cell) for an extent, with the cell grown if needed so that
+    neither side exceeds ``max_cells``. ``cell=None`` means automatic."""
+    if width <= 0 or height <= 0:
+        raise ValueError("extent must have a positive width and height")
+    longest = max(width, height)
+    auto = longest / max_cells
+    cell = auto if not cell or cell <= 0 else max(float(cell), auto)
+    cols = max(2, int(math.ceil(width / cell)))
+    rows = max(2, int(math.ceil(height / cell)))
+    return cols, rows, cell
+
+
+def round_coord(value: float, digits: int = 2) -> float:
+    return round(float(value), digits)
+
+
+def ring_area(ring) -> float:
+    """Signed shoelace area of a closed or open ring of (x, y)."""
+    n = len(ring)
+    if n < 3:
+        return 0.0
+    total = 0.0
+    for i in range(n):
+        x1, y1 = ring[i][0], ring[i][1]
+        x2, y2 = ring[(i + 1) % n][0], ring[(i + 1) % n][1]
+        total += x1 * y2 - x2 * y1
+    return total / 2.0
+
+
+def utc_offset_guess(lon: float) -> float:
+    """Nautical time-zone guess from longitude. Only a starting value: civil
+    time zones differ (Turkey is UTC+3 at about 30 degrees east), so the
+    viewer lets the user change it and an EPW file overrides it."""
+    return float(round(lon / 15.0))
+
+
+def choose_utc_offset(
+    lon: float, machine_offset: float | None, station_offset: float | None = None
+) -> float:
+    """Clock time zone for the sun: the standard offset of the nearest
+    weather station when one is close (the civil zone where it differs from
+    the longitude, as in Turkey), else the computer's standard offset when it
+    is within 1.5 h of the longitude's nautical zone (people analyse places
+    in their own country), else the nautical zone."""
+    if station_offset is not None:
+        return float(station_offset)
+    nautical = utc_offset_guess(lon)
+    if machine_offset is not None and abs(machine_offset - lon / 15.0) <= 1.5:
+        return float(machine_offset)
+    return nautical
+
+
+def safe_name(text: str, fallback: str = "layer") -> str:
+    out = []
+    for ch in str(text or ""):
+        if ch.isalnum() or ch in "-_":
+            out.append(ch)
+        elif ch in " .":
+            out.append("_")
+    name = "".join(out).strip("_")
+    return name[:60] or fallback
+
+
+def field_name(text: str, used: set, limit: int = 30) -> str:
+    """A GeoPackage-safe, unique, lower-case field name."""
+    base = "".join(ch if ch.isalnum() else "_" for ch in str(text or "").lower()).strip("_")
+    base = (base or "value")[:limit]
+    if base[0].isdigit():
+        base = ("v_" + base)[:limit]
+    name = base
+    k = 2
+    while name in used:
+        suffix = f"_{k}"
+        name = base[: limit - len(suffix)] + suffix
+        k += 1
+    used.add(name)
+    return name
+
+
+EARTH_RADIUS_M = 6378137.0
+
+
+def lonlat_to_local(
+    lon: float, lat: float, origin_lon: float, origin_lat: float
+) -> tuple[float, float]:
+    """Local metres (x east, y north) of a WGS84 point around an origin.
+
+    Equirectangular approximation, accurate to a few centimetres per kilometre
+    for scenes up to a few kilometres across (the plugin's typical extent). For
+    larger areas project with pyproj (``pip install zero2geospatial3d-sdk[geo]``).
+    """
+    k = math.cos(math.radians(origin_lat))
+    x = math.radians(lon - origin_lon) * EARTH_RADIUS_M * k
+    y = math.radians(lat - origin_lat) * EARTH_RADIUS_M
+    return x, y
+
+
+def local_to_lonlat(
+    x: float, y: float, origin_lon: float, origin_lat: float
+) -> tuple[float, float]:
+    """Inverse of :func:`lonlat_to_local`."""
+    k = math.cos(math.radians(origin_lat))
+    lon = origin_lon + math.degrees(x / (EARTH_RADIUS_M * k))
+    lat = origin_lat + math.degrees(y / EARTH_RADIUS_M)
+    return lon, lat
+
+
+def bbox_around(lon: float, lat: float, half_size_m: float) -> tuple[float, float, float, float]:
+    """(south, west, north, east) of a square of ``2 * half_size_m`` around a point."""
+    w, s = local_to_lonlat(-half_size_m, -half_size_m, lon, lat)
+    e, n = local_to_lonlat(half_size_m, half_size_m, lon, lat)
+    return s, w, n, e

zero2geospatial3d/grid.py

@@ -0,0 +1,119 @@
+"""Regular raster grid shared by every analysis module.
+
+A :class:`Grid` holds a 2-D ``values`` array of shape ``(rows, cols)`` stored
+row-major from the north-west cell. ``(min_x, max_y)`` is the *centre* of that
+cell in local metres (x east, y north), exactly as in the plugin's web viewer.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+import numpy as np
+
+__all__ = ["Grid", "make_grid"]
+
+
+@dataclass
+class Grid:
+    """A north-up raster in local metres.
+
+    Attributes:
+        values: ``(rows, cols)`` float array, row 0 is the northern edge.
+        cell: cell size in metres.
+        min_x: x of the centre of the north-west cell.
+        max_y: y of the centre of the north-west cell.
+    """
+
+    values: np.ndarray
+    cell: float = 1.0
+    min_x: float = 0.0
+    max_y: float = 0.0
+    nodata: Optional[float] = field(default=None)
+
+    def __post_init__(self) -> None:
+        arr = np.asarray(self.values, dtype=float)
+        if arr.ndim != 2:
+            raise ValueError("Grid values must be a 2-D (rows, cols) array")
+        if self.cell <= 0:
+            raise ValueError("cell size must be positive")
+        self.values = arr
+
+    @property
+    def rows(self) -> int:
+        return int(self.values.shape[0])
+
+    @property
+    def cols(self) -> int:
+        return int(self.values.shape[1])
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        return (self.rows, self.cols)
+
+    @property
+    def min_y(self) -> float:
+        return self.max_y - (self.rows - 1) * self.cell
+
+    @property
+    def max_x(self) -> float:
+        return self.min_x + (self.cols - 1) * self.cell
+
+    def cell_centre(self, c: int, r: int) -> tuple[float, float]:
+        """Local ``(x, y)`` of the centre of column ``c``, row ``r``."""
+        return (self.min_x + c * self.cell, self.max_y - r * self.cell)
+
+    def coords(self) -> tuple[np.ndarray, np.ndarray]:
+        """Arrays ``(x, y)`` of shape ``(rows, cols)`` with every cell centre."""
+        xs = self.min_x + np.arange(self.cols) * self.cell
+        ys = self.max_y - np.arange(self.rows) * self.cell
+        return np.meshgrid(xs, ys)
+
+    def index_of(self, x: float, y: float) -> tuple[int, int]:
+        """Nearest ``(col, row)`` for local ``(x, y)``, clamped to the grid."""
+        c = int(round((x - self.min_x) / self.cell))
+        r = int(round((self.max_y - y) / self.cell))
+        return (min(max(c, 0), self.cols - 1), min(max(r, 0), self.rows - 1))
+
+    def sample(self, x: float, y: float) -> float:
+        """Bilinear value at local ``(x, y)``; clamped at the edges."""
+        return float(self.sample_many(np.array([x]), np.array([y]))[0])
+
+    def sample_many(self, x: np.ndarray, y: np.ndarray) -> np.ndarray:
+        """Vectorised bilinear sampling (clamped at the edges)."""
+        x = np.asarray(x, dtype=float)
+        y = np.asarray(y, dtype=float)
+        v = self.values
+        if self.cols < 2 or self.rows < 2:
+            return np.full(x.shape, float(v.flat[0]) if v.size else 0.0)
+        fc = np.clip((x - self.min_x) / self.cell, 0, self.cols - 1)
+        fr = np.clip((self.max_y - y) / self.cell, 0, self.rows - 1)
+        c0 = np.minimum(self.cols - 2, np.floor(fc)).astype(int)
+        r0 = np.minimum(self.rows - 2, np.floor(fr)).astype(int)
+        tx = fc - c0
+        ty = fr - r0
+        a = v[r0, c0] * (1 - tx) + v[r0, c0 + 1] * tx
+        b = v[r0 + 1, c0] * (1 - tx) + v[r0 + 1, c0 + 1] * tx
+        return a * (1 - ty) + b * ty
+
+    def copy(self, values: Optional[np.ndarray] = None) -> Grid:
+        """A grid with the same georeference and new (or copied) values."""
+        vals = self.values.copy() if values is None else np.asarray(values, dtype=float)
+        return Grid(vals, self.cell, self.min_x, self.max_y, self.nodata)
+
+
+def make_grid(
+    cols: int,
+    rows: int,
+    cell: float,
+    min_x: float = 0.0,
+    max_y: float = 0.0,
+    values: Optional[np.ndarray] = None,
+) -> Grid:
+    """Build a :class:`Grid`; ``values`` may be flat (row-major) or 2-D."""
+    if values is None:
+        arr = np.zeros((rows, cols))
+    else:
+        arr = np.asarray(values, dtype=float).reshape(rows, cols)
+    return Grid(arr, cell, min_x, max_y)