zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/shading.py

@@ -0,0 +1,443 @@
+"""Raster sun, shadow, sky-view and visibility engines on a height field.
+
+The plugin computes these on the GPU with depth maps of the 3D scene. Here the
+scene is a 2.5-D *surface*: a :class:`~zero2geospatial3d.grid.Grid` whose
+values are the terrain plus the height of anything standing on it (buildings,
+walls, tree crowns). :func:`zero2geospatial3d.scene.Scene.surface` builds one
+from a DEM and extruded footprints.
+
+Every receiver is lifted ``lift`` metres above its cell (0.3 m as in the
+viewer) so a flat surface does not shade itself. Rays are marched in steps of
+``step`` (default: half a cell) with bilinear sampling; anything outside the
+grid is treated as open sky.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Callable, Iterable, NamedTuple, Optional, Sequence
+
+import numpy as np
+
+from .grid import Grid
+from .solar import (
+    SunSample,
+    day_of_year,
+    sky_hemisphere,
+    sun_path,
+)
+
+__all__ = [
+    "shadow_mask",
+    "horizon_angles",
+    "sky_view_factor",
+    "sun_hours",
+    "shadow_study",
+    "ShadowFrame",
+    "viewshed",
+    "directional_irradiation",
+    "solar_irradiation",
+    "IrradiationResult",
+    "pv_yield",
+    "scene_dir_to_angles",
+]
+
+Progress = Optional[Callable[[float], None]]
+
+
+def _bilinear_open(values: np.ndarray, fc: np.ndarray, fr: np.ndarray) -> np.ndarray:
+    """Bilinear sample at fractional (col, row); ``-inf`` outside the grid."""
+    rows, cols = values.shape
+    inside = (fc >= 0) & (fc <= cols - 1) & (fr >= 0) & (fr <= rows - 1)
+    out = np.full(fc.shape, -np.inf)
+    if not inside.any():
+        return out
+    c = fc[inside]
+    r = fr[inside]
+    c0 = np.minimum(np.floor(c).astype(int), max(cols - 2, 0))
+    r0 = np.minimum(np.floor(r).astype(int), max(rows - 2, 0))
+    if cols < 2 or rows < 2:
+        out[inside] = values.flat[0]
+        return out
+    tx = c - c0
+    ty = r - r0
+    a = values[r0, c0] * (1 - tx) + values[r0, c0 + 1] * tx
+    b = values[r0 + 1, c0] * (1 - tx) + values[r0 + 1, c0 + 1] * tx
+    out[inside] = a * (1 - ty) + b * ty
+    return out
+
+
+def _surface_values(surface: Grid) -> np.ndarray:
+    z = surface.values
+    if np.isnan(z).any():
+        z = np.where(np.isnan(z), np.nanmin(z) if np.isfinite(z).any() else 0.0, z)
+    return z
+
+
+def _max_tan_along(
+    surface: Grid,
+    azimuth: float,
+    *,
+    lift: float,
+    step: Optional[float],
+    max_distance: Optional[float],
+    stop_tan: Optional[float] = None,
+) -> np.ndarray:
+    """Largest ``(z(p + d u) - z0) / d`` along azimuth ``u`` for every cell.
+
+    With ``stop_tan`` the march ends as soon as no cell could still exceed it
+    (used for single sun directions, where only "above or below" matters).
+    """
+    z = _surface_values(surface)
+    rows, cols = z.shape
+    cell = surface.cell
+    step = step or cell * 0.5
+    z0 = z + lift
+    zmax = float(z.max())
+    diag = math.hypot(rows, cols) * cell
+    limit = min(diag, max_distance) if max_distance else diag
+    dx = math.sin(azimuth) / cell  # columns per metre (east)
+    dy = -math.cos(azimuth) / cell  # rows per metre (row index grows southwards)
+    cc, rr = np.meshgrid(np.arange(cols, dtype=float), np.arange(rows, dtype=float))
+    best = np.full(z.shape, -np.inf)
+    d = step
+    while d <= limit + 1e-9:
+        zs = _bilinear_open(z, cc + dx * d, rr + dy * d)
+        if not np.isfinite(zs).any():
+            break  # every ray has left the grid
+        np.maximum(best, (zs - z0) / d, out=best)
+        # Nothing further away can beat the current best (or the threshold).
+        bound = (zmax - z0) / d
+        target = best if stop_tan is None else np.maximum(best, stop_tan)
+        if not (bound > target).any():
+            break
+        d += step
+    return best
+
+
+def shadow_mask(
+    surface: Grid,
+    elevation: float,
+    azimuth: float,
+    *,
+    lift: float = 0.3,
+    step: Optional[float] = None,
+    max_distance: Optional[float] = None,
+) -> np.ndarray:
+    """Boolean ``(rows, cols)`` array, ``True`` where the cell is in sunlight.
+
+    Args:
+        surface: terrain + objects height field.
+        elevation: sun elevation in radians (``<= 0`` means everything is dark).
+        azimuth: sun azimuth in radians, clockwise from north.
+    """
+    if elevation <= 0:
+        return np.zeros(surface.shape, dtype=bool)
+    tan_el = math.tan(elevation)
+    best = _max_tan_along(
+        surface, azimuth, lift=lift, step=step, max_distance=max_distance, stop_tan=tan_el
+    )
+    return best < tan_el
+
+
+def horizon_angles(
+    surface: Grid,
+    n_azimuths: int = 36,
+    *,
+    lift: float = 0.3,
+    step: Optional[float] = None,
+    max_distance: Optional[float] = None,
+    on_progress: Progress = None,
+) -> np.ndarray:
+    """Horizon elevation (radians, ``>= 0``) for ``n_azimuths`` sectors.
+
+    Returns an array of shape ``(n_azimuths, rows, cols)``; sector ``k`` looks
+    towards azimuth ``2*pi*k/n_azimuths`` (clockwise from north).
+    """
+    out = np.empty((n_azimuths,) + surface.shape)
+    for k in range(n_azimuths):
+        az = 2 * math.pi * k / n_azimuths
+        best = _max_tan_along(
+            surface, az, lift=lift, step=step, max_distance=max_distance, stop_tan=0.0
+        )
+        out[k] = np.arctan(np.maximum(best, 0.0))
+        if on_progress:
+            on_progress((k + 1) / n_azimuths)
+    return out
+
+
+def sky_view_factor(
+    surface: Grid,
+    n_azimuths: int = 36,
+    *,
+    lift: float = 0.3,
+    step: Optional[float] = None,
+    max_distance: Optional[float] = None,
+    horizons: Optional[np.ndarray] = None,
+    on_progress: Progress = None,
+) -> np.ndarray:
+    """Sky view factor of a horizontal receiver (1 = open sky, 0 = enclosed).
+
+    Uses the horizon-angle form ``SVF = 1 - mean_k sin^2(h_k)``, which equals the
+    cosine-weighted hemisphere integral the plugin samples on the GPU.
+    """
+    if horizons is None:
+        horizons = horizon_angles(
+            surface,
+            n_azimuths,
+            lift=lift,
+            step=step,
+            max_distance=max_distance,
+            on_progress=on_progress,
+        )
+    return 1.0 - np.mean(np.sin(horizons) ** 2, axis=0)
+
+
+def _sector_horizon(horizons: np.ndarray, azimuth: float) -> np.ndarray:
+    """Horizon at an arbitrary azimuth, linearly interpolated between sectors."""
+    n = horizons.shape[0]
+    f = (azimuth % (2 * math.pi)) / (2 * math.pi) * n
+    k0 = int(math.floor(f)) % n
+    k1 = (k0 + 1) % n
+    t = f - math.floor(f)
+    return horizons[k0] * (1 - t) + horizons[k1] * t
+
+
+def sun_hours(
+    surface: Grid,
+    lat: float,
+    lon: float,
+    utc_offset: float,
+    *,
+    month: int = 3,
+    day: int = 21,
+    year: Optional[int] = None,
+    start_hour: float = 0.0,
+    end_hour: float = 24.0,
+    step_minutes: float = 10.0,
+    min_elevation_deg: float = 0.5,
+    lift: float = 0.3,
+    step: Optional[float] = None,
+    on_progress: Progress = None,
+) -> np.ndarray:
+    """Hours of direct sun per cell on one day (BRE 209 uses 21 March, >= 2 h).
+
+    ``year=None`` uses a typical non-leap year, as the viewer does.
+    """
+    doy = day_of_year(year or 2001, month, day)
+    path = sun_path(
+        doy,
+        lat,
+        lon,
+        utc_offset,
+        start_hour=start_hour,
+        end_hour=end_hour,
+        step_minutes=step_minutes,
+        min_elevation_deg=min_elevation_deg,
+    )
+    total = np.zeros(surface.shape)
+    for i, s in enumerate(path):
+        lit = shadow_mask(surface, s.elevation, s.azimuth, lift=lift, step=step)
+        total += lit * s.weight
+        if on_progress:
+            on_progress((i + 1) / len(path))
+    return total
+
+
+class ShadowFrame(NamedTuple):
+    """One frame of a shadow study: clock hour, sun angles (rad) and lit mask."""
+
+    hour: float
+    elevation: float
+    azimuth: float
+    lit: np.ndarray
+
+
+def shadow_study(
+    surface: Grid,
+    lat: float,
+    lon: float,
+    utc_offset: float,
+    *,
+    month: int = 6,
+    day: int = 21,
+    year: Optional[int] = None,
+    start_hour: float = 6.0,
+    end_hour: float = 20.0,
+    step_minutes: float = 30.0,
+    lift: float = 0.3,
+) -> list[ShadowFrame]:
+    """Sun-or-shade masks at regular clock times through one day."""
+    doy = day_of_year(year or 2001, month, day)
+    frames: list[ShadowFrame] = []
+    from .solar import solar_position
+
+    h = start_hour
+    while h <= end_hour + 1e-9:
+        p = solar_position(doy, h, lat, lon, utc_offset)
+        lit = shadow_mask(surface, p.elevation, p.azimuth, lift=lift)
+        frames.append(ShadowFrame(h, p.elevation, p.azimuth, lit))
+        h += step_minutes / 60.0
+    return frames
+
+
+def viewshed(
+    surface: Grid,
+    observer_xy: tuple[float, float],
+    *,
+    observer_height: float = 1.6,
+    target_height: float = 0.3,
+    radius: Optional[float] = None,
+) -> np.ndarray:
+    """Cells visible from an observer standing on the surface.
+
+    Returns a float array: 1 visible, 0 hidden, NaN beyond ``radius``.
+    """
+    z = _surface_values(surface)
+    rows, cols = z.shape
+    oc = (observer_xy[0] - surface.min_x) / surface.cell
+    orr = (surface.max_y - observer_xy[1]) / surface.cell
+    oz = float(surface.sample(*observer_xy)) + observer_height
+    cc, rr = np.meshgrid(np.arange(cols, dtype=float), np.arange(rows, dtype=float))
+    dist_cells = np.hypot(cc - oc, rr - orr)
+    tz = z + target_height
+    target_slope = (tz - oz) / np.maximum(dist_cells, 1e-9)
+    blocking = np.full(z.shape, -np.inf)
+    n = int(math.ceil(dist_cells.max())) + 1
+    for k in range(1, n):
+        t = k / n
+        fc = oc + (cc - oc) * t
+        fr = orr + (rr - orr) * t
+        d = dist_cells * t
+        # Only samples at least half a cell before the target can block it.
+        valid = (dist_cells - d) > 0.5
+        zs = _bilinear_open(z, fc, fr)
+        slope = np.where(valid & (d > 0.5), (zs - oz) / np.maximum(d, 1e-9), -np.inf)
+        np.maximum(blocking, slope, out=blocking)
+    vis = (target_slope >= blocking).astype(float)
+    if radius is not None:
+        vis[dist_cells * surface.cell > radius] = np.nan
+    return vis
+
+
+def scene_dir_to_angles(direction: Sequence[float]) -> tuple[float, float]:
+    """(elevation, azimuth) in radians for a scene-axis vector (+x E, +y up, -z N)."""
+    x, y, zc = float(direction[0]), float(direction[1]), float(direction[2])
+    el = math.asin(max(-1.0, min(1.0, y / (math.sqrt(x * x + y * y + zc * zc) or 1.0))))
+    az = math.atan2(x, -zc) % (2 * math.pi)
+    return el, az
+
+
+def _normal(tilt_deg: float, azimuth_deg: float) -> np.ndarray:
+    """Panel normal in scene axes for a tilt and a facing azimuth."""
+    t = math.radians(tilt_deg)
+    a = math.radians(azimuth_deg)
+    return np.array([math.sin(a) * math.sin(t), math.cos(t), -math.cos(a) * math.sin(t)])
+
+
+def directional_irradiation(
+    surface: Grid,
+    directions: Iterable[SunSample] | Iterable[tuple[Sequence[float], float]],
+    *,
+    tilt_deg: float = 0.0,
+    azimuth_deg: float = 180.0,
+    horizons: Optional[np.ndarray] = None,
+    n_azimuths: int = 36,
+    lift: float = 0.3,
+) -> tuple[np.ndarray, float]:
+    """Sum of ``weight * cos(incidence)`` over visible directions.
+
+    ``directions`` holds ``(dir, weight)`` pairs in scene axes (as produced by
+    :func:`~zero2geospatial3d.solar.sun_path`, ``sky_hemisphere`` or the
+    weather module's ``annual_sun_bins``). Visibility is tested against the
+    horizon of each cell. Returns ``(values, unobstructed_potential)``.
+    """
+    if horizons is None:
+        horizons = horizon_angles(surface, n_azimuths, lift=lift)
+    n = _normal(tilt_deg, azimuth_deg)
+    acc = np.zeros(surface.shape)
+    potential = 0.0
+    for item in directions:
+        vec, weight = item[0], item[1]
+        cos_i = max(0.0, float(np.dot(n, np.asarray(vec, dtype=float))))
+        if cos_i <= 0 or weight <= 0:
+            continue
+        el, az = scene_dir_to_angles(vec)
+        if el <= 0:
+            continue
+        visible = el > _sector_horizon(horizons, az)
+        acc += visible * (weight * cos_i)
+        potential += weight * cos_i
+    return acc, potential
+
+
+class IrradiationResult(NamedTuple):
+    """Per-cell irradiation in kWh/m2 over the period, and the unshaded potential."""
+
+    total: np.ndarray
+    direct: np.ndarray
+    diffuse: np.ndarray
+    reflected: float
+    potential: float
+
+
+def solar_irradiation(
+    surface: Grid,
+    sun_bins: Iterable[tuple[Sequence[float], float]],
+    dhi_sum_wh: float,
+    ghi_sum_wh: float,
+    *,
+    tilt_deg: float = 0.0,
+    azimuth_deg: float = 180.0,
+    albedo: float = 0.2,
+    sky_directions: int = 144,
+    n_azimuths: int = 36,
+    lift: float = 0.3,
+) -> IrradiationResult:
+    """Direct + isotropic diffuse + ground-reflected irradiation (kWh/m2).
+
+    Mirrors the viewer's ``solarRadiation`` runner: ``sun_bins`` are
+    ``(direction, DNI Wh/m2)`` pairs (e.g. ``annual_sun_bins(...)["directions"]``),
+    diffuse light is ``DHI * sky-view`` on the tilted plane and the ground adds
+    ``albedo * GHI * (1 - cos tilt) / 2``.
+    """
+    horizons = horizon_angles(surface, n_azimuths, lift=lift)
+    bins = [(d, w / 1000.0) for d, w in sun_bins]
+    direct, direct_pot = directional_irradiation(
+        surface, bins, tilt_deg=tilt_deg, azimuth_deg=azimuth_deg, horizons=horizons
+    )
+    sky = [(s.dir, s.weight) for s in sky_hemisphere(sky_directions)]
+    diff_frac, diff_pot = directional_irradiation(
+        surface, sky, tilt_deg=tilt_deg, azimuth_deg=azimuth_deg, horizons=horizons
+    )
+    dhi = dhi_sum_wh / 1000.0
+    ghi = ghi_sum_wh / 1000.0
+    reflected = albedo * ghi * (1 - math.cos(math.radians(tilt_deg))) / 2
+    diffuse = dhi * diff_frac
+    total = direct + diffuse + reflected
+    return IrradiationResult(
+        total, direct, diffuse, reflected, direct_pot + dhi * diff_pot + reflected
+    )
+
+
+def pv_yield(
+    irradiation: np.ndarray,
+    potential: np.ndarray | float,
+    *,
+    efficiency: float = 0.2,
+    performance_ratio: float = 0.8,
+    coverage: float = 0.6,
+    min_share: float = 0.7,
+    mask: Optional[np.ndarray] = None,
+) -> np.ndarray:
+    """PV electricity (kWh/m2 of ground) per cell, as in the viewer.
+
+    ``yield = irradiation * efficiency * performance_ratio * coverage`` on cells
+    keeping at least ``min_share`` of their unshaded ``potential``; 0 elsewhere.
+    ``mask`` (e.g. roof cells) restricts the panels further.
+    """
+    irr = np.asarray(irradiation, dtype=float)
+    ok = irr >= min_share * np.asarray(potential, dtype=float)
+    if mask is not None:
+        ok &= np.asarray(mask, dtype=bool)
+    return np.where(ok, irr * efficiency * performance_ratio * coverage, 0.0)

zero2geospatial3d/solar.py

@@ -0,0 +1,207 @@
+"""Solar geometry: NOAA sun position, sunrise/sunset, sun paths and sky sampling.
+
+Port of the plugin's ``web/src/core/solar.js``. Angles are returned in radians;
+azimuth is measured clockwise from north. Direction vectors use the viewer's
+scene axes (+x east, +y up, -z north) so that results stay comparable with the
+plugin; :func:`sun_vector_enu` gives the east-north-up form used by the raster
+engines in :mod:`zero2geospatial3d.shading`.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import math
+from typing import NamedTuple, Optional
+
+__all__ = [
+    "SolarPosition",
+    "SunSample",
+    "SkySample",
+    "day_of_year",
+    "is_leap",
+    "solar_position",
+    "sun_vector",
+    "sun_vector_enu",
+    "sunrise_sunset",
+    "sun_path",
+    "sky_hemisphere",
+]
+
+DEG = math.pi / 180.0
+
+
+class SolarPosition(NamedTuple):
+    """Sun position; ``elevation``/``azimuth``/``declination`` in radians, ``eq_time`` in minutes."""
+
+    elevation: float
+    azimuth: float
+    declination: float
+    eq_time: float
+
+
+class SunSample(NamedTuple):
+    """One sun-path sample: scene-axis direction, duration weight (h), clock hour."""
+
+    dir: tuple[float, float, float]
+    weight: float
+    hour: float
+    elevation: float
+    azimuth: float
+
+
+class SkySample(NamedTuple):
+    """One sky direction (scene axes) with its solid-angle weight."""
+
+    dir: tuple[float, float, float]
+    weight: float
+
+
+def day_of_year(year: int, month: int, day: int) -> int:
+    """Day of year (1..366) for a calendar date."""
+    return _dt.date(year, month, day).timetuple().tm_yday
+
+
+def is_leap(year: int) -> bool:
+    """Gregorian leap-year test."""
+    return (year % 4 == 0 and year % 100 != 0) or year % 400 == 0
+
+
+def solar_position(
+    doy: float,
+    hour: float,
+    lat: float,
+    lon: float,
+    utc_offset: float,
+    days_in_year: int = 365,
+) -> SolarPosition:
+    """NOAA "General Solar Position Calculations".
+
+    Args:
+        doy: day of year (1-based).
+        hour: local clock time in hours (0..24, fractional).
+        lat: latitude, degrees north.
+        lon: longitude, degrees east.
+        utc_offset: time zone of the clock, hours east of UTC.
+        days_in_year: 365 or 366.
+    """
+    g = (2 * math.pi / days_in_year) * (doy - 1 + (hour - utc_offset - 12) / 24)
+    eq_time = 229.18 * (
+        0.000075
+        + 0.001868 * math.cos(g)
+        - 0.032077 * math.sin(g)
+        - 0.014615 * math.cos(2 * g)
+        - 0.040849 * math.sin(2 * g)
+    )
+    decl = (
+        0.006918
+        - 0.399912 * math.cos(g)
+        + 0.070257 * math.sin(g)
+        - 0.006758 * math.cos(2 * g)
+        + 0.000907 * math.sin(2 * g)
+        - 0.002697 * math.cos(3 * g)
+        + 0.00148 * math.sin(3 * g)
+    )
+    true_solar_minutes = hour * 60 + eq_time + 4 * lon - 60 * utc_offset
+    ha = (true_solar_minutes / 4 - 180) * DEG
+    phi = lat * DEG
+    sin_el = math.sin(phi) * math.sin(decl) + math.cos(phi) * math.cos(decl) * math.cos(ha)
+    elevation = math.asin(max(-1.0, min(1.0, sin_el)))
+    azimuth = math.atan2(
+        -math.sin(ha) * math.cos(decl),
+        math.cos(phi) * math.sin(decl) - math.sin(phi) * math.cos(decl) * math.cos(ha),
+    )
+    if azimuth < 0:
+        azimuth += 2 * math.pi
+    return SolarPosition(elevation, azimuth, decl, eq_time)
+
+
+def sun_vector(elevation: float, azimuth: float) -> tuple[float, float, float]:
+    """Unit vector towards the sun in scene axes (+x east, +y up, -z north)."""
+    c = math.cos(elevation)
+    return (math.sin(azimuth) * c, math.sin(elevation), -math.cos(azimuth) * c)
+
+
+def sun_vector_enu(elevation: float, azimuth: float) -> tuple[float, float, float]:
+    """Unit vector towards the sun as (east, north, up)."""
+    c = math.cos(elevation)
+    return (math.sin(azimuth) * c, math.cos(azimuth) * c, math.sin(elevation))
+
+
+def _bisect(above, lo: float, hi: float, start_above: bool) -> float:
+    for _ in range(30):
+        mid = (lo + hi) / 2
+        if above(mid) == start_above:
+            lo = mid
+        else:
+            hi = mid
+    return (lo + hi) / 2
+
+
+def sunrise_sunset(
+    doy: float, lat: float, lon: float, utc_offset: float
+) -> tuple[Optional[float], Optional[float]]:
+    """Clock hours ``(sunrise, sunset)``; ``None`` entries for polar day/night."""
+
+    def above(h: float) -> bool:
+        return solar_position(doy, h, lat, lon, utc_offset).elevation > 0
+
+    step = 0.25
+    rise: Optional[float] = None
+    sset: Optional[float] = None
+    h = 0.0
+    while h < 24:
+        a = above(h)
+        b = above(h + step)
+        if not a and b and rise is None:
+            rise = _bisect(above, h, h + step, False)
+        if a and not b:
+            sset = _bisect(above, h, h + step, True)
+        h += step
+    return rise, sset
+
+
+def sun_path(
+    doy: float,
+    lat: float,
+    lon: float,
+    utc_offset: float,
+    *,
+    start_hour: float = 0.0,
+    end_hour: float = 24.0,
+    step_minutes: float = 10.0,
+    min_elevation_deg: float = 0.5,
+) -> list[SunSample]:
+    """Sun directions through one day.
+
+    Samples every ``step_minutes`` between ``start_hour`` and ``end_hour`` while
+    the sun is above ``min_elevation_deg``. Each sample is weighted with its
+    duration in hours, so the weights of unobstructed samples sum to sun hours.
+    """
+    out: list[SunSample] = []
+    step = step_minutes / 60.0
+    h = start_hour + step / 2
+    while h < end_hour:
+        p = solar_position(doy, h, lat, lon, utc_offset)
+        if p.elevation >= min_elevation_deg * DEG:
+            out.append(
+                SunSample(sun_vector(p.elevation, p.azimuth), step, h, p.elevation, p.azimuth)
+            )
+        h += step
+    return out
+
+
+def sky_hemisphere(n: int = 192) -> list[SkySample]:
+    """Quasi-uniform directions over the upper hemisphere (Fibonacci lattice).
+
+    Each direction stands for the solid angle ``2*pi/n``. With the cosine factor
+    ``max(0, n.d)`` and weight ``2/n`` the sum is the sky view factor of a
+    surface with normal ``n``: 1 for an open roof, 0.5 for an open wall.
+    """
+    out: list[SkySample] = []
+    golden = math.pi * (3 - math.sqrt(5))
+    for i in range(n):
+        y = 1 - (i + 0.5) / n
+        r = math.sqrt(max(0.0, 1 - y * y))
+        a = i * golden
+        out.append(SkySample((math.cos(a) * r, y, math.sin(a) * r), 2.0 / n))
+    return out