spacematrix 0.1.0__py3-none-any.whl

spacematrix/__init__.py

@@ -0,0 +1,107 @@
+"""spacematrix: urban density indicators after Berghauser Pont & Haupt (2010).
+
+FSI, GSI, OSR, L, network density N and tare T at the lot, island, fabric and
+district levels; building-type classification; the Spacemate diagram; and
+comparisons with dwelling density and Turkish TAKS / KAKS.
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .analysis import SpacematrixResult, aggregate, analyze, measure
+from .classify import (
+    DEFAULT_THRESHOLDS,
+    THRESHOLDS_VERIFIED,
+    BuildingType,
+    TypeThresholds,
+    classify,
+)
+from .compare import (
+    EMSAL_EXEMPT_MAX_SHARE,
+    TAKS_KAKS_NOTE,
+    TaksKaksEquivalent,
+    coverage_percent,
+    dwelling_density,
+    dwellings_from_fsi,
+    fsi_from_dwelling_density,
+    fsi_from_kaks,
+    kaks_from_fsi,
+    population_density,
+    taks_kaks_equivalent,
+)
+from .geometry import Polygon, intersection_area, shape_area, split_line_length
+from .indicators import (
+    fsi,
+    fsi_from_gsi_l,
+    fsi_from_gsi_osr,
+    grid_network_density,
+    grid_tare,
+    gsi,
+    layers,
+    mesh_size,
+    network_density,
+    osr,
+    profile_width,
+    tare,
+    upscale,
+)
+from .io import read_buildings, read_network, read_zones, write_csv, write_geojson
+from .models import LEVELS, Building, Density, Network, Zone, floors_from_height
+
+__all__ = [
+    "__version__",
+    # models
+    "LEVELS",
+    "Building",
+    "Zone",
+    "Network",
+    "Density",
+    "Polygon",
+    "floors_from_height",
+    # indicators
+    "fsi",
+    "gsi",
+    "osr",
+    "layers",
+    "network_density",
+    "tare",
+    "mesh_size",
+    "grid_network_density",
+    "grid_tare",
+    "profile_width",
+    "upscale",
+    "fsi_from_gsi_l",
+    "fsi_from_gsi_osr",
+    # analysis
+    "measure",
+    "analyze",
+    "aggregate",
+    "SpacematrixResult",
+    # classification
+    "classify",
+    "TypeThresholds",
+    "BuildingType",
+    "DEFAULT_THRESHOLDS",
+    "THRESHOLDS_VERIFIED",
+    # comparison
+    "dwelling_density",
+    "coverage_percent",
+    "dwellings_from_fsi",
+    "fsi_from_dwelling_density",
+    "population_density",
+    "fsi_from_kaks",
+    "kaks_from_fsi",
+    "taks_kaks_equivalent",
+    "TaksKaksEquivalent",
+    "EMSAL_EXEMPT_MAX_SHARE",
+    "TAKS_KAKS_NOTE",
+    # geometry and io
+    "shape_area",
+    "intersection_area",
+    "split_line_length",
+    "read_buildings",
+    "read_zones",
+    "read_network",
+    "write_csv",
+    "write_geojson",
+]

spacematrix/__main__.py

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

spacematrix/_shapely.py

@@ -0,0 +1,35 @@
+"""Optional bridge to shapely (``pip install "spacematrix[shapely]"``)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .geometry import Polygon, Shape, as_polygons
+
+
+def to_shapely(shape: Shape) -> Any:
+    """Convert a :class:`Polygon` or multipolygon to a shapely geometry."""
+    try:
+        from shapely.geometry import MultiPolygon as SMultiPolygon
+        from shapely.geometry import Polygon as SPolygon
+    except ImportError as exc:  # pragma: no cover - exercised only without shapely
+        raise ImportError(
+            "the shapely backend needs shapely: pip install 'spacematrix[shapely]'"
+        ) from exc
+    polys = [SPolygon(p.exterior, [list(h) for h in p.holes]) for p in as_polygons(shape)]
+    return polys[0] if len(polys) == 1 else SMultiPolygon(polys)
+
+
+def from_shapely(geom: Any) -> tuple[Polygon, ...]:
+    """Convert a shapely Polygon or MultiPolygon to a tuple of :class:`Polygon`."""
+    kind = geom.geom_type
+    if kind == "Polygon":
+        parts = [geom]
+    elif kind == "MultiPolygon":
+        parts = list(geom.geoms)
+    else:
+        raise TypeError(f"expected a polygonal geometry, got {kind}")
+    return tuple(
+        Polygon.from_coords(list(p.exterior.coords), [list(r.coords) for r in p.interiors])
+        for p in parts
+    )

spacematrix/_version.py

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

spacematrix/analysis.py

@@ -0,0 +1,255 @@
+"""Measure Spacematrix indicators for lots, islands, fabrics and districts.
+
+Levels (Berghauser Pont and Haupt, 2010, ch. "Density and scale"):
+
+* **lot** (*l*): a plot; tare does not apply.
+* **island** (*i*): an urban block bounded by the building/property lines along
+  the streets; island tare ``T_i`` is the island area not covered by lots
+  (internal paths, communal gardens, ...).
+* **fabric** (*f*): islands plus the streets that serve them, bounded by the
+  street centrelines; fabric tare ``T_f`` is mostly street space, and network
+  density ``N_f`` counts the streets inside the fabric fully and the bounding
+  (edge) streets half.
+* **district** (*d*): fabrics plus large non-built areas (parks, water, rail,
+  large infrastructure); district tare ``T_d``.
+
+Building floor area and footprint are allocated to a zone either by
+**overlap** (default: the share of the footprint inside the zone, so a building
+straddling two lots is split between them) or by **centroid** (the whole
+building goes to the zone containing its footprint centroid).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+from . import indicators as ind
+from .classify import DEFAULT_THRESHOLDS, TypeThresholds, classify
+from .geometry import bbox, intersection_area, point_in_shape, split_line_length
+from .models import LEVELS, Building, Density, Network, Zone
+
+__all__ = ["measure", "analyze", "aggregate", "SpacematrixResult"]
+
+_Box = Tuple[float, float, float, float]
+
+
+def _overlaps(a: _Box, b: _Box) -> bool:
+    return a[0] < b[2] and b[0] < a[2] and a[1] < b[3] and b[1] < a[3]
+
+
+def _line_box(line: Sequence[Tuple[float, float]]) -> _Box:
+    xs = [p[0] for p in line]
+    ys = [p[1] for p in line]
+    return min(xs), min(ys), max(xs), max(ys)
+
+
+def measure(
+    zone: Zone,
+    buildings: Iterable[Building],
+    *,
+    level: str = "island",
+    allocation: str = "overlap",
+    network: Optional[Network] = None,
+    lower_level: Optional[Iterable[Zone]] = None,
+    backend: str = "python",
+    edge_tolerance: float = 0.01,
+    thresholds: Optional[TypeThresholds] = DEFAULT_THRESHOLDS,
+) -> Density:
+    """Compute the indicators of one zone.
+
+    Args:
+        zone: The plan area ``A``.
+        buildings: Candidate buildings (those that do not touch the zone are ignored).
+        level: One of ``"lot"``, ``"island"``, ``"fabric"``, ``"district"``.
+        allocation: ``"overlap"`` or ``"centroid"`` (see module docstring).
+        network: Street centrelines; network density ``N`` is computed when given.
+        lower_level: Zones of the next lower level (lots for an island, islands for a
+            fabric, fabrics for a district). Tare is computed from the part of their
+            area that falls inside ``zone``.
+        backend: ``"python"`` or ``"shapely"`` for polygon overlaps.
+        edge_tolerance: Distance (m) within which a street centreline counts as running
+            along the zone boundary (an edge street, weighted 1/2 in ``N``).
+        thresholds: Type thresholds for :func:`spacematrix.classify`, or ``None`` to skip
+            classification. Types are assigned at lot and island level and, when the
+            fabric tare is known, at fabric level from the net (island-equivalent)
+            values ``FSI / (1 - T)`` and ``GSI / (1 - T)``.
+    """
+    if level not in LEVELS:
+        raise ValueError(f"level must be one of {LEVELS}")
+    if allocation not in ("overlap", "centroid"):
+        raise ValueError("allocation must be 'overlap' or 'centroid'")
+    area = zone.area
+    zbox = bbox(zone.geometry)
+    floor = built = 0.0
+    dwellings: Optional[float] = None
+    count = 0
+    for b in buildings:
+        if not _overlaps(bbox(b.geometry), zbox):
+            continue
+        footprint = b.footprint
+        if footprint <= 0:
+            continue
+        if allocation == "centroid":
+            share = 1.0 if point_in_shape(b.centroid, zone.geometry) else 0.0
+        else:
+            share = min(1.0, intersection_area(b.geometry, zone.geometry, backend) / footprint)
+        if share <= 1e-12:
+            continue
+        count += 1
+        built += footprint * share
+        floor += b.gross_floor_area * share
+        if b.dwellings is not None:
+            dwellings = (dwellings or 0.0) + b.dwellings * share
+    f = ind.fsi(floor, area)
+    g = ind.gsi(built, area)
+    rec = Density(
+        level=level,
+        id=zone.id,
+        area=area,
+        floor_area=floor,
+        built_area=built,
+        fsi=f,
+        gsi=g,
+        osr=ind.osr(f, g),
+        l=ind.layers(f, g),
+        dwellings=dwellings,
+        building_count=count,
+    )
+    if lower_level is not None:
+        covered = sum(
+            intersection_area(z.geometry, zone.geometry, backend)
+            for z in lower_level
+            if _overlaps(bbox(z.geometry), zbox)
+        )
+        rec.lower_level_area = covered
+        rec.tare = ind.tare(area, covered)
+    if network is not None:
+        li = le = 0.0
+        for line in network.lines:
+            if len(line) < 2 or not _overlaps(_line_box(line), _grow(zbox, edge_tolerance)):
+                continue
+            a, e = split_line_length(line, zone.geometry, edge_tolerance)
+            li += a
+            le += e
+        rec.network_interior = li
+        rec.network_edge = le
+        rec.n = ind.network_density(li, le, area)
+    if thresholds is not None:
+        if level in ("lot", "island"):
+            rec.type = classify(f, g, thresholds).label
+        elif rec.tare is not None and rec.tare < 1:
+            k = 1.0 - rec.tare
+            rec.type = classify(f / k, g / k, thresholds).label
+    return rec
+
+
+def _grow(box: _Box, d: float) -> _Box:
+    return box[0] - d, box[1] - d, box[2] + d, box[3] + d
+
+
+@dataclass
+class SpacematrixResult:
+    """Per-level results of :func:`analyze`."""
+
+    lots: List[Density] = field(default_factory=list)
+    islands: List[Density] = field(default_factory=list)
+    fabrics: List[Density] = field(default_factory=list)
+    districts: List[Density] = field(default_factory=list)
+
+    def level(self, name: str) -> List[Density]:
+        """Records of one level (``"lot"``, ``"island"``, ``"fabric"``, ``"district"``)."""
+        if name not in LEVELS:
+            raise ValueError(f"level must be one of {LEVELS}")
+        return {
+            "lot": self.lots,
+            "island": self.islands,
+            "fabric": self.fabrics,
+            "district": self.districts,
+        }[name]
+
+    def records(self) -> List[Density]:
+        """All records, lots first."""
+        return [*self.lots, *self.islands, *self.fabrics, *self.districts]
+
+    def rows(self) -> List[Dict[str, Any]]:
+        """All records as flat dictionaries."""
+        return [r.as_dict() for r in self.records()]
+
+
+def analyze(
+    buildings: Sequence[Building],
+    *,
+    lots: Optional[Sequence[Zone]] = None,
+    islands: Optional[Sequence[Zone]] = None,
+    fabrics: Optional[Sequence[Zone]] = None,
+    districts: Optional[Sequence[Zone]] = None,
+    network: Optional[Network] = None,
+    allocation: str = "overlap",
+    backend: str = "python",
+    edge_tolerance: float = 0.01,
+    thresholds: Optional[TypeThresholds] = DEFAULT_THRESHOLDS,
+) -> SpacematrixResult:
+    """Measure every supplied level; tare uses the next lower level that was supplied
+    (lots for islands, islands for fabrics, fabrics for districts).
+
+    Network density is computed for fabrics and districts when ``network`` is given.
+    See :func:`measure` for the other arguments.
+    """
+    kw: Dict[str, Any] = {
+        "allocation": allocation,
+        "backend": backend,
+        "edge_tolerance": edge_tolerance,
+        "thresholds": thresholds,
+    }
+    res = SpacematrixResult()
+    for z in lots or ():
+        res.lots.append(measure(z, buildings, level="lot", **kw))
+    for z in islands or ():
+        res.islands.append(measure(z, buildings, level="island", lower_level=lots, **kw))
+    for z in fabrics or ():
+        res.fabrics.append(
+            measure(z, buildings, level="fabric", lower_level=islands, network=network, **kw)
+        )
+    for z in districts or ():
+        res.districts.append(
+            measure(z, buildings, level="district", lower_level=fabrics, network=network, **kw)
+        )
+    return res
+
+
+def aggregate(records: Sequence[Density], level: str = "island", id: Any = "aggregate") -> Density:
+    """Combine several samples of the same level into one (area-weighted).
+
+    FSI and GSI of the union are ``ΣF / ΣA`` and ``ΣB / ΣA`` (not the mean of the
+    ratios). Tare is ``1 - Σ A_y / Σ A_x`` when all records carry it; N is the
+    area-weighted mean, which is exact when the samples share no edge streets.
+    """
+    if not records:
+        raise ValueError("nothing to aggregate")
+    area = sum(r.area for r in records)
+    floor = sum(r.floor_area for r in records)
+    built = sum(r.built_area for r in records)
+    f = ind.fsi(floor, area)
+    g = ind.gsi(built, area)
+    out = Density(
+        level=level,
+        id=id,
+        area=area,
+        floor_area=floor,
+        built_area=built,
+        fsi=f,
+        gsi=g,
+        osr=ind.osr(f, g),
+        l=ind.layers(f, g),
+        building_count=sum(r.building_count for r in records),
+    )
+    if all(r.lower_level_area is not None for r in records):
+        lower = sum(r.lower_level_area or 0.0 for r in records)
+        out.lower_level_area = lower
+        out.tare = ind.tare(area, lower)
+    if all(r.n is not None for r in records):
+        out.n = sum((r.n or 0.0) * r.area for r in records) / area
+    if any(r.dwellings is not None for r in records):
+        out.dwellings = sum(r.dwellings or 0.0 for r in records)
+    return out

spacematrix/classify.py

@@ -0,0 +1,129 @@
+"""Classification of samples into Spacematrix building types.
+
+Berghauser Pont and Haupt (2010) show that samples of the same building type
+cluster in the Spacemate diagram (GSI on the x axis, FSI on the y axis) and
+name nine types by height (low-rise, mid-rise, high-rise) and form (point,
+strip, block). In the Spacemate, height classes are bands between iso-L lines
+(rays ``FSI = L · GSI``) and form classes are, in a first approximation, bands
+of coverage (GSI): detached "point" buildings cover little ground, perimeter
+"block" buildings cover a lot, row/slab "strip" types sit in between.
+
+.. warning::
+   The numeric boundaries in :data:`DEFAULT_THRESHOLDS` are **approximations**
+   chosen for this package. They were **not verified** against the tables or
+   figures of the book, which delineates the type clusters graphically from
+   Dutch reference samples rather than as fixed cut-offs. Calibrate them to your
+   own reference samples (or a cluster analysis on FSI, GSI and N, see
+   Berghauser Pont and Olsson, 2017, "Typology based on three density variables
+   central to Spacematrix using cluster analysis", 24th ISUF conference,
+   Valencia) and pass your own :class:`TypeThresholds`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+__all__ = [
+    "TypeThresholds",
+    "BuildingType",
+    "DEFAULT_THRESHOLDS",
+    "THRESHOLDS_VERIFIED",
+    "classify",
+]
+
+#: The default thresholds have not been checked against the primary source.
+THRESHOLDS_VERIFIED = False
+
+
+@dataclass(frozen=True)
+class TypeThresholds:
+    """Boundaries used by :func:`classify` (all user-overridable).
+
+    Attributes:
+        low_rise_max_l: Samples with ``L`` up to this value are low-rise
+            (default 3.5: one to three storeys on average). APPROXIMATION.
+        mid_rise_max_l: Samples with ``L`` up to this value (and above the previous
+            one) are mid-rise (default 7.5: four to seven storeys). APPROXIMATION.
+        point_max_gsi: ``GSI`` below this value is a point (detached) type
+            (default 0.20). APPROXIMATION.
+        strip_max_gsi: ``GSI`` below this value (and at least ``point_max_gsi``) is a
+            strip (row / slab) type; at or above it, a block type (default 0.35).
+            APPROXIMATION.
+        min_gsi: Samples with less coverage than this are reported as
+            ``"unbuilt"`` (default 0.0 only rejects empty samples).
+    """
+
+    low_rise_max_l: float = 3.5
+    mid_rise_max_l: float = 7.5
+    point_max_gsi: float = 0.20
+    strip_max_gsi: float = 0.35
+    min_gsi: float = 0.0
+
+    def __post_init__(self) -> None:
+        if not 0 < self.low_rise_max_l < self.mid_rise_max_l:
+            raise ValueError("need 0 < low_rise_max_l < mid_rise_max_l")
+        if not 0 < self.point_max_gsi < self.strip_max_gsi <= 1:
+            raise ValueError("need 0 < point_max_gsi < strip_max_gsi <= 1")
+
+
+DEFAULT_THRESHOLDS = TypeThresholds()
+
+
+@dataclass(frozen=True)
+class BuildingType:
+    """Result of :func:`classify`."""
+
+    height: str  # "low-rise" | "mid-rise" | "high-rise" | "unbuilt"
+    form: str  # "point" | "strip" | "block" | "unbuilt"
+    l: Optional[float]  # noqa: E741
+
+    @property
+    def label(self) -> str:
+        """For example ``"mid-rise block"``; ``"unbuilt"`` for empty samples."""
+        if self.height == "unbuilt":
+            return "unbuilt"
+        return f"{self.height} {self.form}"
+
+    @property
+    def code(self) -> str:
+        """Short code such as ``"MB"`` (mid-rise block); ``"-"`` if unbuilt."""
+        if self.height == "unbuilt":
+            return "-"
+        return self.height[0].upper() + self.form[0].upper()
+
+
+HEIGHT_CLASSES: Tuple[str, ...] = ("low-rise", "mid-rise", "high-rise")
+FORM_CLASSES: Tuple[str, ...] = ("point", "strip", "block")
+
+
+def classify(
+    fsi: float, gsi: float, thresholds: TypeThresholds = DEFAULT_THRESHOLDS
+) -> BuildingType:
+    """Classify a sample from its FSI and GSI.
+
+    Use values measured at the **island** (or lot) level: tare at the fabric and
+    district levels lowers GSI and FSI by the same factor, which leaves L
+    unchanged but shifts GSI across the form boundaries.
+
+    Args:
+        fsi: Floor space index of the sample.
+        gsi: Ground space index of the sample.
+        thresholds: Boundaries; see the warning in this module's docstring.
+    """
+    if gsi <= thresholds.min_gsi or gsi <= 0 or fsi <= 0:
+        return BuildingType("unbuilt", "unbuilt", None)
+    l_value = fsi / gsi
+    if l_value <= thresholds.low_rise_max_l:
+        height = "low-rise"
+    elif l_value <= thresholds.mid_rise_max_l:
+        height = "mid-rise"
+    else:
+        height = "high-rise"
+    if gsi < thresholds.point_max_gsi:
+        form = "point"
+    elif gsi < thresholds.strip_max_gsi:
+        form = "strip"
+    else:
+        form = "block"
+    return BuildingType(height, form, l_value)