skyview 0.1.0__py3-none-any.whl

skyview/__init__.py

@@ -0,0 +1,99 @@
+"""skyview: sky view factor, openness and street-canyon metrics.
+
+Quick start::
+
+    import numpy as np
+    from skyview import sky_view_factor, canyon_svf, Building, BuildingSet
+
+    dsm = np.zeros((50, 50))
+    dsm[:, 20] = dsm[:, 30] = 10.0           # two walls, 10 m high
+    svf = sky_view_factor(dsm, pixel_size=1.0, n_directions=32, max_radius=60)
+
+    canyon_svf(1.0)                           # Oke: cos(atan(2)) = 0.447
+
+    bs = BuildingSet([Building.box(0, 0, 10, 100, 20), Building.box(30, 0, 40, 100, 20)])
+    bs.sky_view_factor([20.0], [50.0], n_directions=72, weighting="cosine")
+
+For hours of direct sun and building shadows see the companion package
+``urbanshadow``.
+"""
+
+from ._version import __version__
+from .analytic import (
+    canyon_floor_mean_svf,
+    canyon_horizon_angle,
+    canyon_svf,
+    canyon_wall_mean_svf,
+)
+from .canyon import (
+    CanyonStation,
+    StreetCanyon,
+    lines_from_geojson,
+    orientation_entropy,
+    orientation_histogram,
+    orientation_order,
+    segment_bearings,
+    street_canyon,
+    street_canyons,
+)
+from .io import (
+    RasterData,
+    canyons_to_geojson,
+    points_to_geojson,
+    read_geojson,
+    read_raster,
+    write_geojson,
+    write_raster,
+)
+from .raster import (
+    elevation_angle_extremes,
+    horizon_angles,
+    openness,
+    ray_offsets,
+    sky_view_factor,
+    svf_from_horizon,
+)
+from .vector import (
+    Building,
+    BuildingSet,
+    buildings_from_geojson,
+    point_grid,
+    points_in_buildings,
+    rasterize_buildings,
+)
+
+__all__ = [
+    "Building",
+    "BuildingSet",
+    "CanyonStation",
+    "RasterData",
+    "StreetCanyon",
+    "__version__",
+    "buildings_from_geojson",
+    "canyon_floor_mean_svf",
+    "canyon_horizon_angle",
+    "canyon_svf",
+    "canyon_wall_mean_svf",
+    "canyons_to_geojson",
+    "elevation_angle_extremes",
+    "horizon_angles",
+    "lines_from_geojson",
+    "openness",
+    "orientation_entropy",
+    "orientation_histogram",
+    "orientation_order",
+    "point_grid",
+    "points_in_buildings",
+    "points_to_geojson",
+    "rasterize_buildings",
+    "ray_offsets",
+    "read_geojson",
+    "read_raster",
+    "segment_bearings",
+    "sky_view_factor",
+    "street_canyon",
+    "street_canyons",
+    "svf_from_horizon",
+    "write_geojson",
+    "write_raster",
+]

skyview/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m skyview``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

skyview/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

skyview/analytic.py

@@ -0,0 +1,153 @@
+"""Closed-form sky view factors for the infinite symmetric street canyon.
+
+These formulas are the classic validation cases for numerical SVF codes. The
+canyon has two parallel walls of height ``H`` separated by a street of width
+``W`` and is infinitely long. The aspect ratio is ``H/W``.
+
+Two weightings of the sky hemisphere are used in the literature:
+
+* **cosine-weighted** (the radiative view factor, used by Oke and by
+  Johnson & Watson): each sky element counts with the cosine of its zenith
+  angle, as for a horizontal radiation receiver. For a horizon elevation
+  ``gamma(phi)`` the factor is the azimuthal mean of ``cos^2 gamma``.
+* **isotropic** (the solid-angle fraction of the hemisphere, as in the
+  relief-visualisation SVF of Zakšek et al., 2011): every element of the
+  visible sky counts equally. The factor is the azimuthal mean of
+  ``1 - sin gamma``.
+
+Sources
+-------
+* Oke, T. R. (1981). Canyon geometry and the nocturnal urban heat island.
+  *Journal of Climatology* 1, 237-254. Centre-of-floor SVF
+  ``psi = cos(arctan(2H/W))``.
+* Oke, T. R. (1987). *Boundary Layer Climates*, 2nd ed., Routledge.
+* Johnson, G. T. and Watson, I. D. (1984). The determination of view-factors
+  in urban canyons. *Journal of Climate and Applied Meteorology* 23, 329-335.
+  Floor- and wall-averaged factors (equivalent to Hottel's crossed-strings
+  rule for a 2D enclosure).
+* Zakšek, K., Oštir, K. and Kokalj, Ž. (2011). Sky-view factor as a relief
+  visualization technique. *Remote Sensing* 3(2), 398-415.
+  https://doi.org/10.3390/rs3020398
+
+All functions in this module are derived in closed form (see each
+docstring); the test suite also checks them against direct numerical
+integration of the horizon profile.
+"""
+
+from __future__ import annotations
+
+import math
+
+__all__ = [
+    "WEIGHTINGS",
+    "canyon_floor_mean_svf",
+    "canyon_horizon_angle",
+    "canyon_svf",
+    "canyon_wall_mean_svf",
+    "check_weighting",
+]
+
+WEIGHTINGS = ("isotropic", "cosine")
+
+
+def check_weighting(weighting: str) -> str:
+    """Validate and normalise a weighting name (``"isotropic"`` or ``"cosine"``)."""
+    w = str(weighting).strip().lower()
+    if w not in WEIGHTINGS:
+        raise ValueError(f"weighting must be one of {WEIGHTINGS}, got {weighting!r}")
+    return w
+
+
+def _check_hw(hw: float) -> float:
+    hw = float(hw)
+    if not math.isfinite(hw) or hw < 0:
+        raise ValueError(f"H/W must be a finite number >= 0, got {hw!r}")
+    return hw
+
+
+def canyon_horizon_angle(hw: float, azimuth_from_axis_deg: float, position: float = 0.5) -> float:
+    """Horizon elevation angle (degrees) seen from a point on the canyon floor.
+
+    Parameters
+    ----------
+    hw:
+        Aspect ratio ``H/W``.
+    azimuth_from_axis_deg:
+        Viewing azimuth measured from the canyon axis (0 = along the street).
+    position:
+        Cross-street position of the observer as a fraction of ``W`` measured
+        from the left wall (0.5 = centre line). Directions with
+        ``0 < azimuth < 180`` look towards the right wall.
+
+    For a direction that makes angle ``phi`` with the axis, the wall at
+    horizontal distance ``d`` across the street is met after ``d / |sin phi|``
+    metres, so ``tan gamma = H |sin phi| / d``.
+    """
+    hw = _check_hw(hw)
+    p = float(position)
+    if not 0.0 < p < 1.0:
+        raise ValueError("position must lie strictly between 0 and 1")
+    s = math.sin(math.radians(azimuth_from_axis_deg))
+    if abs(s) < 1e-15:
+        return 0.0
+    d = (1.0 - p) if s > 0 else p  # in units of W
+    return math.degrees(math.atan(hw * abs(s) / d))
+
+
+def canyon_svf(hw: float, weighting: str = "cosine", position: float = 0.5) -> float:
+    """SVF of a point on the floor of an infinite symmetric canyon.
+
+    Parameters
+    ----------
+    hw:
+        Aspect ratio ``H/W`` (0 gives open ground, SVF = 1).
+    weighting:
+        ``"cosine"`` (radiative view factor, Oke 1981) or ``"isotropic"``
+        (solid-angle fraction, Zakšek et al. 2011).
+    position:
+        Cross-street position as a fraction of ``W`` from one wall
+        (0.5 = centre line, Oke's case).
+
+    Formulas (``a = position * W`` and ``b = W - a`` are the distances to
+    the two walls):
+
+    * cosine: ``(sin alpha_a + sin alpha_b) / 2`` with
+      ``sin alpha_a = a / sqrt(a^2 + H^2)``. At the centre line this is
+      Oke's ``cos(arctan(2H/W))``.
+    * isotropic: ``1 - (arctan(H/a) + arctan(H/b)) / pi``. At the centre line
+      this is ``1 - (2/pi) arctan(2H/W)``. It follows from averaging
+      ``sin gamma`` over azimuth: ``(1/pi) * int_0^pi k s / sqrt(1 + k^2 s^2)
+      dphi = (2/pi) arctan(k)`` with ``s = sin phi``.
+    """
+    hw = _check_hw(hw)
+    w = check_weighting(weighting)
+    p = float(position)
+    if not 0.0 < p < 1.0:
+        raise ValueError("position must lie strictly between 0 and 1")
+    a, b = p, 1.0 - p  # distances to the walls in units of W
+    if w == "cosine":
+        return 0.5 * (a / math.hypot(a, hw) + b / math.hypot(b, hw))
+    return 1.0 - (math.atan2(hw, a) + math.atan2(hw, b)) / math.pi
+
+
+def canyon_floor_mean_svf(hw: float) -> float:
+    """Cosine-weighted SVF averaged over the whole canyon floor.
+
+    ``psi_floor = sqrt(1 + (H/W)^2) - H/W`` (Johnson & Watson, 1984; this is
+    Hottel's crossed-strings rule for the floor seeing the canyon opening).
+    """
+    hw = _check_hw(hw)
+    return math.sqrt(1.0 + hw * hw) - hw
+
+
+def canyon_wall_mean_svf(hw: float) -> float:
+    """Cosine-weighted SVF averaged over one canyon wall.
+
+    ``psi_wall = (1 + W/H - sqrt(1 + (W/H)^2)) / 2`` (Johnson & Watson, 1984;
+    crossed strings). Tends to 0.5 for an isolated wall (``H/W -> 0``).
+    """
+    hw = _check_hw(hw)
+    if hw == 0.0:
+        return 0.5
+    wh = 1.0 / hw
+    return 0.5 * (1.0 + wh - math.sqrt(1.0 + wh * wh))

skyview/canyon.py

@@ -0,0 +1,281 @@
+"""Street-canyon geometry from building footprints and street centrelines.
+
+For each street centreline, stations are placed every ``spacing`` metres.
+At each station two rays are cast perpendicular to the street, one to each
+side, and the first building edge they cross (within ``max_distance``)
+gives the distance to the building line and the height of that building.
+Where both sides are enclosed the station has a canyon width
+``W = d_left + d_right``, a mean height ``H = (h_left + h_right) / 2`` and an
+aspect ratio ``H/W`` (Oke, 1988, *Energy and Buildings* 11, 103-113, uses
+``H/W`` as the primary canyon descriptor).
+
+Street orientation statistics follow Boeing, G. (2019). Urban spatial order:
+street network orientation, configuration, and entropy. *Applied Network
+Science* 4, 67. https://doi.org/10.1007/s41109-019-0189-1 : bearings are
+binned into 36 bins of 10 degrees centred on 0, 10, ..., 350, each segment
+counting both in its bearing and the reverse bearing, the Shannon entropy
+``H_o = -sum P_i ln P_i`` is computed and the orientation order is
+``phi = 1 - ((H_o - H_g) / (H_max - H_g))^2`` with ``H_max = ln 36`` and
+``H_g = ln 4`` (a perfect four-way grid).
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Union
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from .analytic import canyon_svf
+from .vector import Building, BuildingSet
+
+__all__ = [
+    "CanyonStation",
+    "StreetCanyon",
+    "lines_from_geojson",
+    "orientation_entropy",
+    "orientation_histogram",
+    "orientation_order",
+    "segment_bearings",
+    "street_canyon",
+    "street_canyons",
+]
+
+Line = List[Tuple[float, float]]
+
+
+@dataclass
+class CanyonStation:
+    """Measurements at one station along a street."""
+
+    x: float
+    y: float
+    left_distance: Optional[float]
+    right_distance: Optional[float]
+    left_height: Optional[float]
+    right_height: Optional[float]
+
+    @property
+    def enclosed(self) -> bool:
+        return self.left_distance is not None and self.right_distance is not None
+
+    @property
+    def width(self) -> Optional[float]:
+        if self.left_distance is None or self.right_distance is None:
+            return None
+        return self.left_distance + self.right_distance
+
+    @property
+    def height(self) -> Optional[float]:
+        if self.left_height is None or self.right_height is None:
+            return None
+        return 0.5 * (self.left_height + self.right_height)
+
+    @property
+    def hw(self) -> Optional[float]:
+        w = self.width
+        h = self.height
+        if w is None or h is None or w <= 0:
+            return None
+        return h / w
+
+
+@dataclass
+class StreetCanyon:
+    """Summary of the canyon along one street centreline.
+
+    ``hw_mean`` is the mean of station ``H/W`` values over enclosed stations;
+    ``svf_oke`` is Oke's centre-line cosine SVF for that mean aspect ratio
+    (an idealised estimate that assumes an infinite symmetric canyon).
+    """
+
+    length: float
+    bearing: float
+    n_stations: int
+    enclosure: float
+    width_mean: Optional[float]
+    height_mean: Optional[float]
+    hw_mean: Optional[float]
+    hw_median: Optional[float]
+    svf_oke: Optional[float]
+    stations: List[CanyonStation]
+
+    def summary(self) -> Dict[str, Any]:
+        """Plain dict of the summary values (no station list)."""
+        d = asdict(self)
+        d.pop("stations")
+        return d
+
+
+def _clean_line(coords: Iterable[Sequence[float]]) -> Line:
+    pts: Line = []
+    for c in coords:
+        p = (float(c[0]), float(c[1]))
+        if not pts or p != pts[-1]:
+            pts.append(p)
+    if len(pts) < 2:
+        raise ValueError("a line needs at least 2 distinct vertices")
+    return pts
+
+
+def lines_from_geojson(data: Dict[str, Any]) -> List[Tuple[Line, Dict[str, Any]]]:
+    """Read LineString / MultiLineString features as ``(coords, properties)`` pairs."""
+    if data.get("type") == "Feature":
+        features = [data]
+    elif data.get("type") == "FeatureCollection":
+        features = list(data.get("features") or [])
+    else:
+        raise ValueError("expected a GeoJSON Feature or FeatureCollection")
+    out: List[Tuple[Line, Dict[str, Any]]] = []
+    for feat in features:
+        geom = feat.get("geometry") or {}
+        props = dict(feat.get("properties") or {})
+        if geom.get("type") == "LineString":
+            out.append((_clean_line(geom["coordinates"]), props))
+        elif geom.get("type") == "MultiLineString":
+            for part in geom["coordinates"]:
+                out.append((_clean_line(part), props))
+    return out
+
+
+def segment_bearings(line: Sequence[Sequence[float]]) -> Tuple[np.ndarray, np.ndarray]:
+    """Bearing (degrees clockwise from north, 0..360) and length of each segment."""
+    a = np.asarray(line, dtype=np.float64)
+    d = np.diff(a[:, :2], axis=0)
+    lengths = np.hypot(d[:, 0], d[:, 1])
+    bearings = np.degrees(np.arctan2(d[:, 0], d[:, 1])) % 360.0
+    keep = lengths > 0
+    return bearings[keep], lengths[keep]
+
+
+def _axis_bearing(line: Line) -> float:
+    """Length-weighted mean axial bearing (0..180) using doubled angles."""
+    b, ln = segment_bearings(line)
+    th = np.radians(2.0 * b)
+    c = float((ln * np.cos(th)).sum())
+    s = float((ln * np.sin(th)).sum())
+    return (math.degrees(math.atan2(s, c)) / 2.0) % 180.0
+
+
+def street_canyon(
+    line: Sequence[Sequence[float]],
+    buildings: Union[BuildingSet, Iterable[Building]],
+    spacing: float = 10.0,
+    max_distance: float = 50.0,
+) -> StreetCanyon:
+    """Measure the street canyon along one centreline.
+
+    Parameters
+    ----------
+    line:
+        Centreline vertices ``[(x, y), ...]`` in metres.
+    buildings:
+        Footprints with heights.
+    spacing:
+        Station spacing in metres; the first station is at ``spacing / 2``.
+    max_distance:
+        Search distance to each side in metres; beyond it a side counts as
+        open.
+    """
+    bs = buildings if isinstance(buildings, BuildingSet) else BuildingSet(buildings)
+    if spacing <= 0 or max_distance <= 0:
+        raise ValueError("spacing and max_distance must be positive")
+    pts = np.asarray(_clean_line(line), dtype=np.float64)
+    seg = np.diff(pts, axis=0)
+    seg_len = np.hypot(seg[:, 0], seg[:, 1])
+    total = float(seg_len.sum())
+    cum = np.concatenate([[0.0], np.cumsum(seg_len)])
+    n = max(1, int(math.floor(total / spacing)))
+    pos = (np.arange(n) + 0.5) * (total / n)
+    stations: List[CanyonStation] = []
+    for p in pos:
+        k = int(min(np.searchsorted(cum, p, side="right") - 1, len(seg_len) - 1))
+        f = (p - cum[k]) / seg_len[k]
+        x = float(pts[k, 0] + f * seg[k, 0])
+        y = float(pts[k, 1] + f * seg[k, 1])
+        tx, ty = seg[k] / seg_len[k]
+        # left normal = rotate tangent by +90 degrees
+        ux = np.array([-ty, ty])
+        uy = np.array([tx, -tx])
+        vals: List[Tuple[Optional[float], Optional[float]]] = []
+        if bs.ax.size:
+            t, valid = bs.ray_hits(x, y, ux, uy, max_distance)
+            for side in range(2):
+                v = valid[side]
+                if v.any():
+                    j = int(np.argmin(np.where(v, t[side], np.inf)))
+                    vals.append((float(t[side, j]), float(bs.edge_height[j])))
+                else:
+                    vals.append((None, None))
+        else:
+            vals = [(None, None), (None, None)]
+        stations.append(CanyonStation(x, y, vals[0][0], vals[1][0], vals[0][1], vals[1][1]))
+    enclosed = [s for s in stations if s.enclosed]
+    widths = [s.width for s in enclosed if s.width is not None]
+    heights = [s.height for s in enclosed if s.height is not None]
+    hws = [s.hw for s in enclosed if s.hw is not None]
+    hw_mean = float(np.mean(hws)) if hws else None
+    return StreetCanyon(
+        length=total,
+        bearing=_axis_bearing(_clean_line(line)),
+        n_stations=len(stations),
+        enclosure=len(enclosed) / len(stations),
+        width_mean=float(np.mean(widths)) if widths else None,
+        height_mean=float(np.mean(heights)) if heights else None,
+        hw_mean=hw_mean,
+        hw_median=float(np.median(hws)) if hws else None,
+        svf_oke=canyon_svf(hw_mean, "cosine") if hw_mean is not None else None,
+        stations=stations,
+    )
+
+
+def street_canyons(
+    lines: Iterable[Sequence[Sequence[float]]],
+    buildings: Union[BuildingSet, Iterable[Building]],
+    spacing: float = 10.0,
+    max_distance: float = 50.0,
+) -> List[StreetCanyon]:
+    """:func:`street_canyon` for many centrelines sharing one building set."""
+    bs = buildings if isinstance(buildings, BuildingSet) else BuildingSet(buildings)
+    return [street_canyon(ln, bs, spacing, max_distance) for ln in lines]
+
+
+def orientation_histogram(
+    lines: Iterable[Sequence[Sequence[float]]], n_bins: int = 36, weight_by_length: bool = True
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Bidirectional bearing histogram of street segments (Boeing, 2019).
+
+    Returns ``(bin_centres_deg, counts)``. Bins are centred on
+    ``0, 360/n_bins, ...``; each segment counts in its bearing and in the
+    reverse bearing, weighted by length unless ``weight_by_length=False``.
+    """
+    if n_bins < 1:
+        raise ValueError("n_bins must be >= 1")
+    width = 360.0 / n_bins
+    counts = np.zeros(n_bins)
+    for line in lines:
+        b, ln = segment_bearings(line)
+        w = ln if weight_by_length else np.ones_like(ln)
+        for bb in (b, (b + 180.0) % 360.0):
+            idx = np.floor(((bb + width / 2.0) % 360.0) / width).astype(np.int64) % n_bins
+            np.add.at(counts, idx, w)
+    return np.arange(n_bins) * width, counts
+
+
+def orientation_entropy(counts: ArrayLike) -> float:
+    """Shannon entropy ``-sum P ln P`` (nats) of a bearing histogram."""
+    c = np.asarray(counts, dtype=np.float64)
+    tot = c.sum()
+    if tot <= 0:
+        raise ValueError("histogram is empty")
+    p = c[c > 0] / tot
+    return float(-(p * np.log(p)).sum())
+
+
+def orientation_order(entropy: float, n_bins: int = 36) -> float:
+    """Boeing's (2019) orientation order ``phi`` (1 = perfect grid, ~0 = disorder)."""
+    h_max = math.log(n_bins)
+    h_g = math.log(4)
+    return 1.0 - ((entropy - h_g) / (h_max - h_g)) ** 2