greenrule 0.1.0__py3-none-any.whl

greenrule/__init__.py

@@ -0,0 +1,106 @@
+"""greenrule: urban green space provision and exposure indicators.
+
+The 3-30-300 rule (Konijnendijk 2023) per home, the WHO Regional Office for Europe (2016)
+Urban Green Space Indicator (300 m linear distance, 0.5 ha core / 1 ha additional), green
+space per capita, NDVI buffer exposure and equity summaries (Gini, population shares).
+Network distances use a small built-in Dijkstra on GeoJSON lines with a Euclidean
+fallback. Pure NumPy; coordinates in projected metres.
+"""
+
+from ._common import M2_PER_HA, GreenError
+from ._version import __version__
+from .analysis import Assessment, assess
+from .equity import equity_summary, gini, lorenz_curve, share_meeting
+from .exposure import Exposure, ndvi_exposure
+from .geometry import Area, densify_boundary, sampled_overlap
+from .green import GreenDistance, GreenSpaces, euclidean_distance, network_distance
+from .io import (
+    PointLayer,
+    areas_from_geojson,
+    points_from_csv,
+    points_from_geojson,
+    points_to_geojson,
+    read_geojson,
+    read_points,
+    write_csv,
+    write_json,
+)
+from .network import Network
+from .provision import Provision, green_provision
+from .raster import Raster, ndvi
+from .rule333 import (
+    MAX_DISTANCE_M,
+    MIN_CANOPY,
+    MIN_TREES,
+    Rule333Result,
+    assign_zones,
+    canopy_share_buffers,
+    canopy_share_zones,
+    evaluate_3_30_300,
+    trees_within_radius,
+    visible_tree_counts,
+)
+from .who import (
+    WHO_ADDITIONAL_MIN_AREA_HA,
+    WHO_CORE_MIN_AREA_HA,
+    WHO_DISTANCE_M,
+    ProximityResult,
+    who_proximity,
+    who_proximity_both,
+)
+
+__all__ = [
+    "__version__",
+    "GreenError",
+    "M2_PER_HA",
+    # geometry and green spaces
+    "Area",
+    "GreenSpaces",
+    "GreenDistance",
+    "euclidean_distance",
+    "network_distance",
+    "densify_boundary",
+    "sampled_overlap",
+    "Network",
+    # 3-30-300
+    "MIN_TREES",
+    "MIN_CANOPY",
+    "MAX_DISTANCE_M",
+    "visible_tree_counts",
+    "trees_within_radius",
+    "canopy_share_zones",
+    "canopy_share_buffers",
+    "assign_zones",
+    "evaluate_3_30_300",
+    "Rule333Result",
+    # WHO
+    "WHO_DISTANCE_M",
+    "WHO_CORE_MIN_AREA_HA",
+    "WHO_ADDITIONAL_MIN_AREA_HA",
+    "who_proximity",
+    "who_proximity_both",
+    "ProximityResult",
+    # provision, exposure, equity
+    "green_provision",
+    "Provision",
+    "Raster",
+    "ndvi",
+    "ndvi_exposure",
+    "Exposure",
+    "gini",
+    "lorenz_curve",
+    "share_meeting",
+    "equity_summary",
+    # analysis and I/O
+    "assess",
+    "Assessment",
+    "read_geojson",
+    "read_points",
+    "PointLayer",
+    "points_from_geojson",
+    "points_from_csv",
+    "points_to_geojson",
+    "areas_from_geojson",
+    "write_csv",
+    "write_json",
+]

greenrule/__main__.py

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

greenrule/_common.py

@@ -0,0 +1,79 @@
+"""Shared errors, coercion helpers and JSON cleaning.
+
+Coordinates are planar (projected) in metres: distances, areas (m2) and hectares assume
+metre units. No reprojection is done.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+FloatArray = NDArray[np.float64]
+BoolArray = NDArray[np.bool_]
+
+#: Square metres per hectare.
+M2_PER_HA = 10_000.0
+
+
+class GreenError(ValueError):
+    """Raised for invalid inputs or inconsistent parameters."""
+
+
+def as_points(coords: Any, what: str = "points") -> FloatArray:
+    """Return ``coords`` as an ``(n, 2)`` float array (a single pair gives ``(1, 2)``)."""
+    try:
+        arr = np.asarray(coords, dtype=float)
+    except (TypeError, ValueError):
+        raise GreenError(f"{what}: coordinates are not numeric") from None
+    if arr.ndim == 1 and arr.size >= 2:
+        arr = arr.reshape(1, -1)
+    if arr.ndim != 2 or arr.shape[1] < 2:
+        raise GreenError(f"{what}: expected [x, y] pairs")
+    arr = np.ascontiguousarray(arr[:, :2])
+    if not np.all(np.isfinite(arr)):
+        raise GreenError(f"{what}: coordinates contain NaN or infinity")
+    return arr
+
+
+def as_weights(values: Any, n: int, what: str = "population") -> FloatArray:
+    """Non-negative weights of length ``n``; ``None`` gives ones."""
+    if values is None:
+        return np.ones(n)
+    w = np.asarray(values, dtype=float).ravel()
+    if len(w) != n:
+        raise GreenError(f"{what}: expected {n} values, got {len(w)}")
+    if not np.all(np.isfinite(w)) or np.any(w < 0):
+        raise GreenError(f"{what}: values must be finite and >= 0")
+    return w
+
+
+def check_positive(value: Any, name: str, allow_zero: bool = False) -> float:
+    try:
+        v = float(value)
+    except (TypeError, ValueError):
+        raise GreenError(f"{name} must be a number, got {value!r}") from None
+    if not np.isfinite(v) or v < 0 or (v == 0 and not allow_zero):
+        cond = ">= 0" if allow_zero else "> 0"
+        raise GreenError(f"{name} must be finite and {cond}, got {value!r}")
+    return v
+
+
+def clean(obj: Any) -> Any:
+    """Recursively convert numpy types 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)):
+        f = float(obj)
+        return f if np.isfinite(f) else None
+    return obj

greenrule/_version.py

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

greenrule/analysis.py

@@ -0,0 +1,176 @@
+"""One-call assessment of homes: 3-30-300, WHO proximity, NDVI exposure and equity."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+import numpy as np
+
+from ._common import GreenError, as_points, as_weights
+from .equity import equity_summary
+from .exposure import Exposure, ndvi_exposure
+from .geometry import Area
+from .green import GreenDistance, GreenSpaces, euclidean_distance, network_distance
+from .network import Network
+from .raster import Raster
+from .rule333 import (
+    CanopySource,
+    Rule333Result,
+    assign_zones,
+    canopy_share_buffers,
+    canopy_share_zones,
+    evaluate_3_30_300,
+    trees_within_radius,
+    visible_tree_counts,
+)
+from .who import WHO_CORE_MIN_AREA_HA, ProximityResult, who_proximity
+
+
+@dataclass
+class Assessment:
+    """Per-home rows and summaries from :func:`assess`."""
+
+    rule: Optional[Rule333Result] = None
+    who: Optional[ProximityResult] = None
+    exposure: Optional[Exposure] = None
+    equity: Optional[Dict[str, Any]] = None
+    n_homes: int = 0
+    notes: List[str] = field(default_factory=list)
+
+    def to_rows(self) -> List[Dict[str, Any]]:
+        rows: List[Dict[str, Any]] = [{} for _ in range(self.n_homes)]
+        if self.rule is not None:
+            for r, x in zip(rows, self.rule.to_rows()):
+                r.update(x)
+        if self.who is not None:
+            for r, m, d in zip(rows, self.who.meets, self.who.distance.distance):
+                r["who_distance"] = float(d)
+                r["who_proximity"] = bool(m)
+        if self.exposure is not None:
+            for r, x in zip(rows, self.exposure.to_rows()):
+                r.update(x)
+        return rows
+
+    def summary(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"homes": self.n_homes, "notes": list(self.notes)}
+        if self.rule is not None:
+            out["rule_3_30_300"] = self.rule.summary()
+        if self.who is not None:
+            out["who_2016"] = self.who.summary()
+        if self.exposure is not None:
+            m = self.exposure.mean
+            out["ndvi"] = {
+                "radius_m": self.exposure.radius,
+                "mean_of_means": float(np.nanmean(m)) if np.isfinite(m).any() else None,
+                "threshold": self.exposure.threshold,
+            }
+        if self.equity is not None:
+            out["equity"] = self.equity
+        return out
+
+
+def assess(
+    homes: Any,
+    greens: GreenSpaces,
+    population: Any = None,
+    *,
+    tree_counts: Optional[Sequence[float]] = None,
+    visible_pairs: Optional[Iterable[Tuple[int, Any]]] = None,
+    tree_points: Any = None,
+    tree_radius: Optional[float] = None,
+    canopy: Optional[CanopySource] = None,
+    canopy_radius: Optional[float] = None,
+    neighbourhoods: Optional[Sequence[Area]] = None,
+    canopy_mode: str = "binary",
+    canopy_resolution: Optional[float] = None,
+    min_green_area_ha: Optional[float] = None,
+    network: Optional[Network] = None,
+    max_snap: float = 100.0,
+    entrance_spacing: float = 25.0,
+    who_min_area_ha: Optional[float] = WHO_CORE_MIN_AREA_HA,
+    ndvi: Optional[Raster] = None,
+    ndvi_radius: Optional[float] = None,
+    ndvi_threshold: Optional[float] = None,
+    zones: Optional[Sequence[Any]] = None,
+) -> Assessment:
+    """Assess every home.
+
+    The 3-30-300 rule is evaluated when tree and canopy inputs are given (see
+    :mod:`greenrule.rule333` for the options); the WHO Europe (2016) indicator unless
+    ``who_min_area_ha`` is None; NDVI exposure when ``ndvi`` and ``ndvi_radius`` are given;
+    equity summaries over the computed criteria when ``zones`` (one label per home) are
+    given. ``network`` switches the 300 m criterion to network distance (Euclidean
+    fallback for homes without a connection); the WHO indicator always uses linear
+    distance, as defined.
+    """
+    pts = as_points(homes, "homes")
+    n = len(pts)
+    w = as_weights(population, n)
+    res = Assessment(n_homes=n)
+
+    trees = None
+    trees_method = "visibility"
+    if tree_counts is not None or visible_pairs is not None:
+        trees = visible_tree_counts(n, counts=tree_counts, pairs=visible_pairs)
+    elif tree_points is not None:
+        if tree_radius is None:
+            raise GreenError("tree_points need tree_radius")
+        trees = trees_within_radius(pts, tree_points, tree_radius)
+        trees_method = f"proxy: trees within {tree_radius:g} m"
+        res.notes.append("tree counts are a proximity proxy, not visibility")
+
+    canopy_share = None
+    if canopy is not None:
+        if neighbourhoods is not None:
+            zl = list(neighbourhoods)
+            shares = canopy_share_zones(zl, canopy, mode=canopy_mode, resolution=canopy_resolution)
+            idx = assign_zones(pts, zl)
+            canopy_share = np.where(idx >= 0, shares[np.maximum(idx, 0)], np.nan)
+            if (idx < 0).any():
+                res.notes.append(f"{int((idx < 0).sum())} homes outside every neighbourhood")
+        elif canopy_radius is not None:
+            if not isinstance(canopy, Raster):
+                raise GreenError("buffer neighbourhoods need a canopy Raster")
+            canopy_share = canopy_share_buffers(pts, canopy, canopy_radius, canopy_mode)
+        else:
+            raise GreenError("canopy needs neighbourhoods or canopy_radius")
+
+    if trees is not None and canopy_share is not None:
+        qualifying = greens.filter(min_green_area_ha)
+        dist: GreenDistance
+        if network is not None:
+            dist = network_distance(pts, qualifying, network, max_snap, entrance_spacing)
+        elif len(qualifying):
+            dist = euclidean_distance(pts, qualifying)
+        else:
+            dist = GreenDistance(np.full(n, np.inf), [None] * n, ["euclidean"] * n)
+        res.rule = evaluate_3_30_300(trees, canopy_share, dist, w, trees_method=trees_method)
+    elif trees is not None or canopy_share is not None:
+        raise GreenError("the 3-30-300 rule needs both tree and canopy inputs")
+
+    if who_min_area_ha is not None:
+        res.who = who_proximity(pts, greens, who_min_area_ha, population=w)
+
+    if ndvi is not None:
+        if ndvi_radius is None:
+            raise GreenError("ndvi needs ndvi_radius")
+        res.exposure = ndvi_exposure(pts, ndvi, ndvi_radius, threshold=ndvi_threshold)
+
+    if zones is not None:
+        crit: Dict[str, Any] = {}
+        if res.rule is not None:
+            crit.update(
+                {
+                    "3_trees": res.rule.meets_3,
+                    "30_canopy": res.rule.meets_30,
+                    "300_distance": res.rule.meets_300,
+                    "3_30_300": res.rule.meets_all,
+                }
+            )
+        if res.who is not None:
+            crit["who_2016"] = res.who.meets
+        if crit:
+            value = res.exposure.mean if res.exposure is not None else None
+            res.equity = equity_summary(crit, w, list(zones), value=value)
+    return res

greenrule/cli.py

@@ -0,0 +1,318 @@
+"""Command-line interface: ``greenrule who | rule | exposure | provision | equity``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+import numpy as np
+
+from ._common import GreenError
+from ._version import __version__
+from .equity import equity_summary, gini
+from .green import GreenSpaces
+from .io import (
+    PointLayer,
+    areas_from_geojson,
+    points_to_geojson,
+    read_geojson,
+    read_points,
+    read_table,
+    write_csv,
+    write_json,
+)
+from .network import Network
+from .provision import green_provision
+from .raster import Raster
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+
+
+def _transform(text: Optional[str]) -> Tuple[float, float, float, float]:
+    if not text:
+        raise GreenError("--transform x0,y0_top,dx,dy is required with a .npy raster")
+    try:
+        vals = [float(v) for v in text.split(",")]
+    except ValueError:
+        raise GreenError(f"bad --transform {text!r}") from None
+    if len(vals) != 4:
+        raise GreenError("--transform needs four numbers: x0,y0_top,dx,dy")
+    return vals[0], vals[1], vals[2], vals[3]
+
+
+def _homes(args: argparse.Namespace) -> Tuple[PointLayer, Optional[np.ndarray]]:
+    layer = read_points(args.homes)
+    pop = layer.column(args.population_field) if args.population_field else None
+    return layer, pop
+
+
+def _greens(path: str, id_field: Optional[str]) -> GreenSpaces:
+    return GreenSpaces.from_geojson(read_geojson(path), id_field=id_field)
+
+
+def _finish(
+    args: argparse.Namespace, layer: PointLayer, rows: List[Dict[str, Any]], summary: Any
+) -> None:
+    if args.output:
+        write_json(points_to_geojson(layer, rows), args.output)
+    if args.csv:
+        write_csv(
+            [{"id": i, **p, **r} for i, p, r in zip(layer.ids, layer.properties, rows)], args.csv
+        )
+    text = write_json(summary, args.summary)
+    if not args.summary:
+        sys.stdout.write(text + "\n")
+
+
+def _cmd_who(args: argparse.Namespace) -> int:
+    from .who import who_proximity, who_proximity_both
+
+    layer, pop = _homes(args)
+    greens = _greens(args.greens, args.green_id)
+    if args.both:
+        both = who_proximity_both(layer.xy, greens, args.distance, pop)
+        rows: List[Dict[str, Any]] = [{} for _ in range(len(layer))]
+        for key, res in both.items():
+            for r, d, m in zip(rows, res.distance.distance, res.meets):
+                r[f"distance_{key}"] = float(d)
+                r[f"meets_{key}"] = bool(m)
+        _finish(args, layer, rows, {k: v.summary() for k, v in both.items()})
+        return EXIT_OK
+    res = who_proximity(layer.xy, greens, args.min_area_ha, args.distance, pop)
+    _finish(args, layer, res.to_rows(), res.summary())
+    return EXIT_OK
+
+
+def _cmd_rule(args: argparse.Namespace) -> int:
+    from .analysis import assess
+
+    layer, pop = _homes(args)
+    greens = _greens(args.greens, args.green_id)
+    kw: Dict[str, Any] = {}
+    if args.trees_field:
+        kw["tree_counts"] = layer.column(args.trees_field)
+    elif args.trees:
+        if args.tree_radius is None:
+            raise GreenError("--trees needs --tree-radius (proximity proxy)")
+        kw["tree_points"] = read_points(args.trees).xy
+        kw["tree_radius"] = args.tree_radius
+    else:
+        raise GreenError("give --trees-field (visible-tree counts) or --trees + --tree-radius")
+    if args.canopy_field:
+        if not args.neighbourhoods:
+            raise GreenError("--canopy-field needs --neighbourhoods")
+        zones = areas_from_geojson(args.neighbourhoods, args.neighbourhood_id)
+        kw["neighbourhoods"] = zones
+        kw["canopy"] = {z.fid: float(z.properties[args.canopy_field]) for z in zones}
+    elif args.canopy_polygons:
+        if not args.neighbourhoods:
+            raise GreenError("--canopy-polygons needs --neighbourhoods")
+        kw["neighbourhoods"] = areas_from_geojson(args.neighbourhoods, args.neighbourhood_id)
+        kw["canopy"] = areas_from_geojson(args.canopy_polygons)
+        kw["canopy_resolution"] = args.resolution
+    elif args.canopy:
+        kw["canopy"] = Raster.from_npy(args.canopy, _transform(args.transform), args.nodata)
+        kw["canopy_mode"] = args.canopy_mode
+        if args.neighbourhoods:
+            kw["neighbourhoods"] = areas_from_geojson(args.neighbourhoods, args.neighbourhood_id)
+        else:
+            kw["canopy_radius"] = args.canopy_radius
+    else:
+        raise GreenError("give --canopy RASTER.npy, --canopy-polygons or --canopy-field")
+    if args.network:
+        kw["network"] = Network([read_geojson(args.network)], node_tolerance=args.node_tolerance)
+        kw["max_snap"] = args.max_snap
+        kw["entrance_spacing"] = args.entrance_spacing
+    zones_labels = layer.labels(args.zone_field) if args.zone_field else None
+    res = assess(
+        layer.xy,
+        greens,
+        pop,
+        min_green_area_ha=args.min_area_ha,
+        who_min_area_ha=None,
+        zones=zones_labels,
+        **kw,
+    )
+    _finish(args, layer, res.to_rows(), res.summary())
+    return EXIT_OK
+
+
+def _cmd_exposure(args: argparse.Namespace) -> int:
+    from .exposure import ndvi_exposure
+
+    layer, _ = _homes(args)
+    ras = Raster.from_npy(args.ndvi, _transform(args.transform), args.nodata)
+    res = ndvi_exposure(layer.xy, ras, args.radius, threshold=args.threshold)
+    m = res.mean[np.isfinite(res.mean)]
+    summary = {
+        "radius_m": args.radius,
+        "homes": len(layer),
+        "ndvi_mean_of_means": float(m.mean()) if len(m) else None,
+        "homes_without_data": int((~np.isfinite(res.mean)).sum()),
+    }
+    _finish(args, layer, res.to_rows(), summary)
+    return EXIT_OK
+
+
+def _cmd_provision(args: argparse.Namespace) -> int:
+    zones = areas_from_geojson(args.zones, args.zone_id)
+    pop = []
+    for z in zones:
+        v = z.properties.get(args.population_field)
+        if v is None:
+            raise GreenError(f"zone {z.fid!r} has no {args.population_field!r}")
+        pop.append(float(v))
+    greens = _greens(args.greens, args.green_id)
+    prov = green_provision(zones, greens, pop, method=args.method, resolution=args.resolution)
+    rows = prov.to_rows()
+    if args.csv:
+        write_csv(rows, args.csv)
+    pc = prov.per_capita
+    ok = np.isfinite(pc)
+    summary: Dict[str, Any] = {"total": prov.total(), "zones": rows, "method": args.method}
+    if ok.sum() > 0 and pc[ok].sum() > 0:
+        summary["gini_m2_per_capita"] = gini(pc[ok], prov.population[ok])
+    text = write_json(summary, args.output)
+    if not args.output:
+        sys.stdout.write(text + "\n")
+    return EXIT_OK
+
+
+def _truthy(v: str) -> bool:
+    s = str(v).strip().lower()
+    if s in ("1", "true", "yes", "y", "t"):
+        return True
+    if s in ("0", "false", "no", "n", "f", ""):
+        return False
+    raise GreenError(f"not a boolean: {v!r}")
+
+
+def _cmd_equity(args: argparse.Namespace) -> int:
+    rows = read_table(args.table)
+    if not rows:
+        raise GreenError("empty table")
+    names = [c.strip() for c in (args.criteria or "").split(",") if c.strip()]
+    for col in [*names, args.population, args.zone, args.value]:
+        if col and col not in rows[0]:
+            raise GreenError(f"column {col!r} not found")
+    pop = [float(r[args.population]) for r in rows] if args.population else None
+    zones = [r[args.zone] for r in rows] if args.zone else None
+    if names:
+        crit = {c: [_truthy(r[c]) for r in rows] for c in names}
+        value = [float(r[args.value]) for r in rows] if args.value else None
+        result = equity_summary(crit, pop, zones, value=value)
+    elif args.value:
+        result = {"value_gini": gini([float(r[args.value]) for r in rows], pop)}
+    else:
+        raise GreenError("give --criteria and/or --value")
+    if args.csv and "zones" in result:
+        write_csv(result["zones"], args.csv)
+    text = write_json(result, args.output)
+    if not args.output:
+        sys.stdout.write(text + "\n")
+    return EXIT_OK
+
+
+def _io_opts(p: argparse.ArgumentParser) -> None:
+    p.add_argument("-o", "--output", help="per-home GeoJSON output")
+    p.add_argument("--csv", help="per-home CSV output")
+    p.add_argument("--summary", help="write the summary JSON here (default: stdout)")
+
+
+def _homes_opts(p: argparse.ArgumentParser) -> None:
+    p.add_argument("homes", help="homes: GeoJSON points/buildings or CSV with x,y")
+    p.add_argument("--population-field", help="residents per home (attribute/column)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="greenrule",
+        description="Urban green space provision and exposure indicators (projected metres).",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("who", help="WHO Europe (2016) 300 m green space indicator")
+    _homes_opts(p)
+    p.add_argument("greens", help="green space polygons (GeoJSON)")
+    p.add_argument("--green-id", help="green space id attribute")
+    p.add_argument("--min-area-ha", type=float, default=0.5, help="0.5 (core, default) or 1")
+    p.add_argument("--both", action="store_true", help="report the 0.5 ha and 1 ha variants")
+    p.add_argument("--distance", type=float, default=300.0, help="linear distance (m)")
+    _io_opts(p)
+    p.set_defaults(func=_cmd_who)
+
+    p = sub.add_parser("rule", help="3-30-300 rule per home")
+    _homes_opts(p)
+    p.add_argument("greens")
+    p.add_argument("--green-id")
+    p.add_argument("--trees-field", help="visible-tree count attribute of the homes")
+    p.add_argument("--trees", help="tree points (proximity proxy, needs --tree-radius)")
+    p.add_argument("--tree-radius", type=float)
+    p.add_argument("--canopy", help="canopy raster (.npy)")
+    p.add_argument("--transform", help="x0,y0_top,dx,dy of the .npy raster")
+    p.add_argument("--nodata", type=float)
+    p.add_argument("--canopy-mode", choices=("binary", "fraction"), default="binary")
+    p.add_argument("--canopy-radius", type=float, help="buffer neighbourhood radius (m)")
+    p.add_argument("--neighbourhoods", help="neighbourhood polygons (GeoJSON)")
+    p.add_argument("--neighbourhood-id")
+    p.add_argument("--canopy-field", help="canopy share attribute of the neighbourhoods")
+    p.add_argument("--canopy-polygons", help="canopy polygons (GeoJSON)")
+    p.add_argument("--resolution", type=float, help="sampling resolution for polygons (m)")
+    p.add_argument("--min-area-ha", type=float, help="minimum green space size (none by default)")
+    p.add_argument("--network", help="street centrelines (GeoJSON) for network distance")
+    p.add_argument("--node-tolerance", type=float, default=0.01)
+    p.add_argument("--max-snap", type=float, default=100.0)
+    p.add_argument("--entrance-spacing", type=float, default=25.0)
+    p.add_argument("--zone-field", help="zone label attribute for equity summaries")
+    _io_opts(p)
+    p.set_defaults(func=_cmd_rule)
+
+    p = sub.add_parser("exposure", help="NDVI statistics in circular buffers")
+    _homes_opts(p)
+    p.add_argument("--ndvi", required=True, help="NDVI raster (.npy)")
+    p.add_argument("--transform", required=True, help="x0,y0_top,dx,dy")
+    p.add_argument("--nodata", type=float)
+    p.add_argument("--radius", type=float, required=True, help="buffer radius (m)")
+    p.add_argument("--threshold", type=float, help="NDVI >= threshold counts as green")
+    _io_opts(p)
+    p.set_defaults(func=_cmd_exposure)
+
+    p = sub.add_parser("provision", help="green area and m2 per resident by zone")
+    p.add_argument("zones", help="zone polygons with a population attribute (GeoJSON)")
+    p.add_argument("greens")
+    p.add_argument("--population-field", required=True)
+    p.add_argument("--zone-id")
+    p.add_argument("--green-id")
+    p.add_argument("--method", choices=("centroid", "sample"), default="centroid")
+    p.add_argument("--resolution", type=float)
+    p.add_argument("-o", "--output", help="summary JSON (default: stdout)")
+    p.add_argument("--csv", help="per-zone CSV")
+    p.set_defaults(func=_cmd_provision)
+
+    p = sub.add_parser("equity", help="Gini and shares meeting criteria from a CSV table")
+    p.add_argument("table", help="CSV with one row per home or area")
+    p.add_argument("--criteria", help="comma-separated boolean columns")
+    p.add_argument("--value", help="continuous column for a Gini coefficient")
+    p.add_argument("--population", help="weight column")
+    p.add_argument("--zone", help="zone label column")
+    p.add_argument("-o", "--output")
+    p.add_argument("--csv", help="per-zone CSV")
+    p.set_defaults(func=_cmd_equity)
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except (GreenError, OSError, KeyError, ValueError) as exc:
+        print(f"greenrule: error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())