parcelform 0.1.0__py3-none-any.whl

parcelform/__init__.py

@@ -0,0 +1,130 @@
+"""parcelform: parcel and lot geometry metrics from GeoJSON polygons in projected coordinates.
+
+Area, perimeter, convex hull, minimum-area rectangle (rotating calipers) and orientation;
+shape indices (Polsby-Popper, Schwartzberg, Reock, rectangularity, elongation, convexity,
+fractal dimension); frontage against street centrelines or blocks, lot depth and width,
+corner / through / interior classification; buildable envelopes by setback; lot-rule checks
+and simple subdivision feasibility. Pure NumPy.
+"""
+
+from ._common import Geometry, ParcelError, Polygon, to_geometry, to_polygon
+from ._version import __version__
+from .analysis import (
+    ParcelReport,
+    analyze,
+    analyze_parcel,
+    envelopes,
+    load_streets,
+    subdivide_collection,
+)
+from .envelope import Envelope, buildable_envelope, edge_roles, resolve_setbacks
+from .frontage import (
+    CORNER,
+    INTERIOR,
+    LANDLOCKED,
+    LOT_TYPES,
+    THROUGH,
+    Frontage,
+    FrontagePiece,
+    LotDimensions,
+    StreetSegments,
+    as_streets,
+    frontage,
+    lot_dimensions,
+)
+from .geometry import (
+    Circle,
+    Rectangle,
+    area,
+    centroid,
+    convex_hull,
+    min_area_rectangle,
+    min_enclosing_circle,
+    perimeter,
+    points_in_polygon,
+)
+from .io import read_geojson, read_rules, write_csv, write_geojson
+from .shape import (
+    ShapeIndices,
+    fractal_dimension,
+    orientation_difference,
+    polsby_popper,
+    schwartzberg,
+    schwartzberg_ratio,
+    shape_indices,
+)
+from .subdivision import (
+    LotRules,
+    RuleCheck,
+    SubdivisionResult,
+    check_lot,
+    evaluate_rules,
+    lot_count_bound,
+    split_parcel,
+    subdivision_feasibility,
+)
+
+__all__ = [
+    "__version__",
+    "ParcelError",
+    "Polygon",
+    "Geometry",
+    "to_geometry",
+    "to_polygon",
+    # geometry
+    "area",
+    "perimeter",
+    "centroid",
+    "convex_hull",
+    "min_area_rectangle",
+    "min_enclosing_circle",
+    "points_in_polygon",
+    "Rectangle",
+    "Circle",
+    # shape
+    "shape_indices",
+    "ShapeIndices",
+    "polsby_popper",
+    "schwartzberg",
+    "schwartzberg_ratio",
+    "fractal_dimension",
+    "orientation_difference",
+    # frontage
+    "frontage",
+    "Frontage",
+    "FrontagePiece",
+    "StreetSegments",
+    "as_streets",
+    "lot_dimensions",
+    "LotDimensions",
+    "CORNER",
+    "THROUGH",
+    "INTERIOR",
+    "LANDLOCKED",
+    "LOT_TYPES",
+    # envelope
+    "buildable_envelope",
+    "Envelope",
+    "edge_roles",
+    "resolve_setbacks",
+    # subdivision
+    "LotRules",
+    "RuleCheck",
+    "SubdivisionResult",
+    "check_lot",
+    "evaluate_rules",
+    "lot_count_bound",
+    "split_parcel",
+    "subdivision_feasibility",
+    # analysis and I/O
+    "analyze",
+    "analyze_parcel",
+    "envelopes",
+    "subdivide_collection",
+    "load_streets",
+    "ParcelReport",
+    "read_geojson",
+    "read_rules",
+    "write_geojson",
+    "write_csv",
+]

parcelform/__main__.py

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

parcelform/_common.py

@@ -0,0 +1,211 @@
+"""Shared types, validation and small ring helpers.
+
+All coordinates are planar (projected) and in one length unit, typically metres. Rings are
+``(n, 2)`` float arrays stored *open* (the closing vertex of GeoJSON is dropped).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, Sequence, Tuple
+
+import numpy as np
+from numpy.typing import NDArray
+
+FloatArray = NDArray[np.float64]
+
+#: Relative tolerance used for degenerate-geometry checks.
+EPS = 1e-12
+
+
+class ParcelError(ValueError):
+    """Raised for invalid geometry, inconsistent parameters or unsupported cases."""
+
+
+def as_ring(coords: Any, what: str = "ring") -> FloatArray:
+    """Return ``coords`` as an open ``(n, 2)`` float ring.
+
+    The closing vertex (if equal to the first) and consecutive duplicate vertices are
+    removed. Extra ordinates (z, m) are dropped. At least three distinct vertices and a
+    non-zero area are required.
+    """
+    try:
+        arr = np.asarray(coords, dtype=float)
+    except (TypeError, ValueError):
+        raise ParcelError(f"{what}: coordinates are not numeric") from None
+    if arr.ndim != 2 or arr.shape[1] < 2:
+        raise ParcelError(f"{what}: expected a sequence of [x, y] pairs")
+    arr = np.ascontiguousarray(arr[:, :2])
+    if not np.all(np.isfinite(arr)):
+        raise ParcelError(f"{what}: coordinates contain NaN or infinity")
+    if len(arr) > 1:
+        keep = np.ones(len(arr), dtype=bool)
+        keep[1:] = np.any(arr[1:] != arr[:-1], axis=1)
+        arr = arr[keep]
+    if len(arr) > 1 and np.array_equal(arr[0], arr[-1]):
+        arr = arr[:-1]
+    if len(arr) < 3:
+        raise ParcelError(f"{what}: needs at least three distinct vertices")
+    if abs(signed_area(arr)) <= EPS * max(1.0, float(np.ptp(arr, axis=0).max()) ** 2):
+        raise ParcelError(f"{what}: ring has zero area")
+    return arr
+
+
+def as_points(coords: Any, what: str = "points") -> FloatArray:
+    """Return ``coords`` as an ``(n, 2)`` float array (a single point gives ``(1, 2)``)."""
+    try:
+        arr = np.asarray(coords, dtype=float)
+    except (TypeError, ValueError):
+        raise ParcelError(f"{what}: coordinates are not numeric") from None
+    if arr.ndim == 1:
+        arr = arr.reshape(1, -1)
+    if arr.ndim != 2 or arr.shape[1] < 2 or len(arr) == 0:
+        raise ParcelError(f"{what}: expected [x, y] pairs")
+    arr = np.ascontiguousarray(arr[:, :2])
+    if not np.all(np.isfinite(arr)):
+        raise ParcelError(f"{what}: coordinates contain NaN or infinity")
+    return arr
+
+
+def signed_area(ring: FloatArray) -> float:
+    """Shoelace signed area: positive for counter-clockwise rings."""
+    x = ring[:, 0] - ring[0, 0]
+    y = ring[:, 1] - ring[0, 1]
+    return 0.5 * float(np.dot(x, np.roll(y, -1)) - np.dot(np.roll(x, -1), y))
+
+
+def ccw(ring: FloatArray) -> FloatArray:
+    """Return the ring in counter-clockwise order."""
+    return ring if signed_area(ring) > 0 else ring[::-1].copy()
+
+
+def ring_edges(ring: FloatArray) -> Tuple[FloatArray, FloatArray]:
+    """Start and end points of every edge of an open ring."""
+    return ring, np.roll(ring, -1, axis=0)
+
+
+def drop_collinear(ring: FloatArray, tol: float = 1e-9) -> FloatArray:
+    """Remove vertices whose neighbours make them collinear (within ``tol`` x edge scale)."""
+    pts = ring
+    changed = True
+    while changed and len(pts) > 3:
+        changed = False
+        prev = np.roll(pts, 1, axis=0)
+        nxt = np.roll(pts, -1, axis=0)
+        u = pts - prev
+        v = nxt - pts
+        cross = u[:, 0] * v[:, 1] - u[:, 1] * v[:, 0]
+        dot = np.einsum("ij,ij->i", u, v)
+        scale = np.linalg.norm(u, axis=1) * np.linalg.norm(v, axis=1)
+        flat = (np.abs(cross) <= tol * np.maximum(scale, EPS)) & (dot > 0)
+        if flat.any():
+            idx = int(np.argmax(flat))
+            pts = np.delete(pts, idx, axis=0)
+            changed = True
+    return pts
+
+
+@dataclass
+class Polygon:
+    """A polygon with one exterior ring and optional holes (open rings, any orientation)."""
+
+    exterior: FloatArray
+    holes: List[FloatArray] = field(default_factory=list)
+
+    @classmethod
+    def from_coords(cls, coords: Sequence[Any]) -> Polygon:
+        """Build from GeoJSON ``Polygon`` coordinates ``[exterior, hole, ...]``."""
+        if len(coords) == 0:
+            raise ParcelError("polygon has no rings")
+        ext = ccw(as_ring(coords[0], "exterior ring"))
+        holes = [ccw(as_ring(h, "hole"))[::-1].copy() for h in coords[1:]]
+        return cls(ext, holes)
+
+    def rings(self) -> List[FloatArray]:
+        return [self.exterior, *self.holes]
+
+    def to_coords(self) -> List[List[List[float]]]:
+        """GeoJSON coordinates with closed rings (exterior CCW, holes CW)."""
+        out = []
+        for r in self.rings():
+            closed = np.vstack([r, r[:1]])
+            out.append(closed.tolist())
+        return out
+
+
+@dataclass
+class Geometry:
+    """A polygonal geometry made of one or more :class:`Polygon` parts."""
+
+    parts: List[Polygon]
+
+    @property
+    def is_multi(self) -> bool:
+        return len(self.parts) > 1
+
+    def single(self, what: str = "operation") -> Polygon:
+        """Return the only part or raise for multi-part geometries."""
+        if len(self.parts) != 1:
+            raise ParcelError(f"{what} needs a single polygon, got {len(self.parts)} parts")
+        return self.parts[0]
+
+    def all_vertices(self) -> FloatArray:
+        return np.vstack([p.exterior for p in self.parts])
+
+
+def to_geometry(obj: Any) -> Geometry:
+    """Coerce a GeoJSON geometry dict, :class:`Polygon`, :class:`Geometry` or ring."""
+    if isinstance(obj, Geometry):
+        return obj
+    if isinstance(obj, Polygon):
+        return Geometry([obj])
+    if isinstance(obj, dict):
+        if obj.get("type") == "Feature":
+            return to_geometry(obj.get("geometry"))
+        gtype = obj.get("type")
+        coords = obj.get("coordinates")
+        if gtype == "Polygon":
+            return Geometry([Polygon.from_coords(coords or [])])
+        if gtype == "MultiPolygon":
+            parts = [Polygon.from_coords(c) for c in (coords or [])]
+            if not parts:
+                raise ParcelError("empty MultiPolygon")
+            return Geometry(parts)
+        raise ParcelError(f"expected a Polygon or MultiPolygon, got {gtype!r}")
+    # bare ring of coordinates
+    return Geometry([Polygon(ccw(as_ring(obj)))])
+
+
+def to_polygon(obj: Any, what: str = "operation") -> Polygon:
+    """Coerce to a single :class:`Polygon`."""
+    return to_geometry(obj).single(what)
+
+
+def check_positive(value: float, name: str, allow_zero: bool = False) -> float:
+    v = float(value)
+    if not np.isfinite(v) or v < 0 or (v == 0 and not allow_zero):
+        cond = ">= 0" if allow_zero else "> 0"
+        raise ParcelError(f"{name} must be finite and {cond}, got {value!r}")
+    return v
+
+
+def finite_or_none(x: float) -> Any:
+    """JSON-safe float: NaN/inf become ``None``."""
+    return float(x) if np.isfinite(x) else None
+
+
+def clean(obj: Any) -> Any:
+    """Recursively convert numpy scalars/arrays and non-finite floats to JSON-safe values."""
+    if isinstance(obj, dict):
+        return {str(k): clean(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [clean(v) for v in obj]
+    if isinstance(obj, np.ndarray):
+        return clean(obj.tolist())
+    if isinstance(obj, (np.bool_,)):
+        return bool(obj)
+    if isinstance(obj, (np.integer,)):
+        return int(obj)
+    if isinstance(obj, (float, np.floating)):
+        return finite_or_none(float(obj))
+    return obj

parcelform/_version.py

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

parcelform/analysis.py

@@ -0,0 +1,217 @@
+"""One-call parcel analysis and batch processing of FeatureCollections."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional
+
+from ._common import Geometry, ParcelError, clean, to_geometry
+from .envelope import Envelope, Setbacks, buildable_envelope
+from .frontage import Frontage, LotDimensions, StreetSegments, as_streets, frontage, lot_dimensions
+from .geometry import centroid
+from .io import check_projected, feature, feature_collection, read_geojson
+from .shape import ShapeIndices, shape_indices
+from .subdivision import (
+    LotRules,
+    RuleCheck,
+    SubdivisionResult,
+    evaluate_rules,
+    subdivision_feasibility,
+)
+
+
+def load_streets(streets: Any) -> Optional[StreetSegments]:
+    """Streets from a GeoJSON path, a FeatureCollection/geometry dict or a list of lines."""
+    if streets is None:
+        return None
+    if isinstance(streets, (str, Path)):
+        return as_streets(read_geojson(streets))
+    return as_streets(streets)
+
+
+@dataclass
+class ParcelReport:
+    """Everything measured for one parcel."""
+
+    shape: ShapeIndices
+    centroid: tuple
+    frontage: Optional[Frontage] = None
+    dimensions: Optional[LotDimensions] = None
+    envelope: Optional[Envelope] = None
+    rules: Optional[RuleCheck] = None
+    subdivision: Optional[SubdivisionResult] = None
+    error: Optional[str] = None
+
+    def properties(self) -> Dict[str, Any]:
+        """Flat, JSON-safe properties for a GeoJSON Feature or a CSV row."""
+        p: Dict[str, Any] = {}
+        s = self.shape.to_dict()
+        p.update({k: s[k] for k in s})
+        p["centroid_x"], p["centroid_y"] = self.centroid
+        if self.frontage is not None:
+            p["frontage"] = self.frontage.total
+            p["lot_type"] = self.frontage.lot_type
+            p["is_corner"] = self.frontage.is_corner
+            p["is_through"] = self.frontage.is_through
+            p["n_streets"] = self.frontage.n_streets
+            p["street_ids"] = [str(k) for k in self.frontage.by_street]
+        if self.dimensions is not None:
+            d = self.dimensions.to_dict()
+            p.update({f"lot_{k}": v for k, v in d.items()})
+        if self.envelope is not None:
+            p["envelope_area"] = self.envelope.area
+            p["envelope_share"] = self.envelope.share
+            p["envelope_method"] = self.envelope.method
+        if self.rules is not None:
+            p["rules_passed"] = self.rules.passed
+            p["rules_failures"] = "; ".join(self.rules.failures)
+        if self.subdivision is not None:
+            p["max_lots"] = self.subdivision.n_lots
+            p["subdividable"] = self.subdivision.feasible
+        if self.error:
+            p["error"] = self.error
+        return dict(clean(p))
+
+
+def analyze_parcel(
+    parcel: Any,
+    streets: Any = None,
+    tolerance: Optional[float] = None,
+    setbacks: Optional[Setbacks] = None,
+    rules: Optional[LotRules] = None,
+    subdivide: bool = False,
+    by: str = "frontage",
+    **frontage_kw: Any,
+) -> ParcelReport:
+    """Shape indices plus, when inputs allow, frontage, lot dimensions, envelope, rule
+    check and subdivision feasibility for one parcel."""
+    g: Geometry = to_geometry(parcel)
+    report = ParcelReport(shape=shape_indices(g), centroid=centroid(g))
+    if g.is_multi:
+        return report
+    poly = g.parts[0]
+    segs: Optional[StreetSegments] = None
+    if streets is not None:
+        if tolerance is None:
+            raise ParcelError("tolerance is required with streets")
+        segs = as_streets(streets)
+        report.frontage = frontage(poly, segs, tolerance, **frontage_kw)
+    report.dimensions = lot_dimensions(poly, report.frontage)
+    if setbacks is not None:
+        report.envelope = buildable_envelope(poly, setbacks, report.frontage)
+    if rules is not None:
+        report.rules = evaluate_rules(
+            rules,
+            report.shape.area,
+            report.dimensions.depth,
+            report.dimensions.width,
+            None if report.frontage is None else report.frontage.total,
+        )
+        if subdivide:
+            if segs is None or tolerance is None:
+                raise ParcelError("subdivision needs streets and tolerance")
+            report.subdivision = subdivision_feasibility(
+                poly, rules, segs, tolerance, by=by, **frontage_kw
+            )
+    return report
+
+
+def analyze(
+    parcels: Any,
+    streets: Any = None,
+    tolerance: Optional[float] = None,
+    setbacks: Optional[Setbacks] = None,
+    rules: Optional[LotRules] = None,
+    subdivide: bool = False,
+    by: str = "frontage",
+    keep_properties: bool = True,
+    allow_geographic: bool = False,
+    on_error: str = "raise",
+    **frontage_kw: Any,
+) -> Dict[str, Any]:
+    """Analyse every parcel of a FeatureCollection; returns a new FeatureCollection.
+
+    The original geometry is kept; measured values are added to (or replace) the
+    properties. With ``on_error="record"`` a failing parcel gets an ``error`` property
+    instead of stopping the run.
+    """
+    if on_error not in ("raise", "record"):
+        raise ParcelError("on_error must be 'raise' or 'record'")
+    fc = read_geojson(parcels)
+    if not allow_geographic:
+        check_projected(fc)
+    segs = load_streets(streets)
+    out: List[Dict[str, Any]] = []
+    for f in fc["features"]:
+        props = dict(f.get("properties") or {}) if keep_properties else {}
+        try:
+            rep = analyze_parcel(
+                f.get("geometry"), segs, tolerance, setbacks, rules, subdivide, by, **frontage_kw
+            )
+            props.update(rep.properties())
+        except ParcelError as exc:
+            if on_error == "raise":
+                raise
+            props["error"] = str(exc)
+        out.append(feature(f.get("geometry"), props, f.get("id")))
+    return feature_collection(out)
+
+
+def envelopes(
+    parcels: Any,
+    setbacks: Setbacks,
+    streets: Any = None,
+    tolerance: Optional[float] = None,
+    **frontage_kw: Any,
+) -> Dict[str, Any]:
+    """FeatureCollection of buildable envelopes (empty envelopes get a null geometry)."""
+    fc = read_geojson(parcels)
+    segs = load_streets(streets)
+    if isinstance(setbacks, Mapping) and segs is None:
+        raise ParcelError("role-based setbacks need streets and tolerance")
+    out = []
+    for i, f in enumerate(fc["features"]):
+        g = to_geometry(f.get("geometry"))
+        poly = g.single("envelopes")
+        front = None
+        if segs is not None:
+            if tolerance is None:
+                raise ParcelError("tolerance is required with streets")
+            front = frontage(poly, segs, tolerance, **frontage_kw)
+        env = buildable_envelope(poly, setbacks, front)
+        props = {"parcel": f.get("id", i), **env.to_dict()}
+        out.append(feature(env.to_geojson(), dict(clean(props)), f.get("id")))
+    return feature_collection(out)
+
+
+def subdivide_collection(
+    parcels: Any,
+    rules: LotRules,
+    streets: Any,
+    tolerance: float,
+    by: str = "frontage",
+    max_lots: Optional[int] = None,
+    **frontage_kw: Any,
+) -> Dict[str, Any]:
+    """Run :func:`subdivision_feasibility` on every parcel; returns a FeatureCollection of
+    the resulting lots (a conforming parcel that cannot be split is returned whole; a
+    non-conforming parcel is returned with ``n_lots = 0``)."""
+    fc = read_geojson(parcels)
+    segs = load_streets(streets)
+    out = []
+    for i, f in enumerate(fc["features"]):
+        pid = f.get("id", i)
+        poly = to_geometry(f.get("geometry")).single("subdivision")
+        res = subdivision_feasibility(
+            poly, rules, segs, tolerance, by=by, max_lots=max_lots, **frontage_kw
+        )
+        if res.n_lots == 0:
+            props = {"parcel": pid, "lot": 0, "n_lots": 0, **res.parent.to_dict()}
+            out.append(feature(f.get("geometry"), dict(clean(props))))
+            continue
+        for k, (lot, chk) in enumerate(zip(res.lots, res.checks), start=1):
+            props = {"parcel": pid, "lot": k, "n_lots": res.n_lots, **chk.to_dict()}
+            geom = {"type": "Polygon", "coordinates": lot.to_coords()}
+            out.append(feature(geom, dict(clean(props))))
+    return feature_collection(out)