openwalkscore 0.1.0__py3-none-any.whl

openwalkscore/__init__.py

@@ -0,0 +1,82 @@
+"""openwalkscore: open, transparent, API-key-free walkability scores from OpenStreetMap.
+
+Quick start::
+
+    from openwalkscore import score_point
+
+    result = score_point(48.8530, 2.3499)          # downloads OSM data (cached)
+    print(result.score, result.rating)
+    print(result.explain())
+
+    # offline, from a local extract
+    result = score_point(48.8530, 2.3499, data="paris_extract.osm")
+
+The method is documented in :mod:`openwalkscore.scoring` and the README. This
+project is not affiliated with Walk Score(R) or Redfin, and its scores are not
+comparable to theirs.
+"""
+
+from ._version import __version__
+from .dem import DEM, load_dem
+from .htmlmap import render_html, write_html
+from .network import NetworkMetrics, WalkNetwork, dijkstra
+from .osm import POI, OSMData, Way, load_osm, parse_geojson, parse_osm_xml, parse_overpass_json
+from .overpass import DEFAULT_ENDPOINTS, OverpassClient, OverpassError, build_query
+from .profiles import (
+    CategoryConfig,
+    DecayConfig,
+    PenaltyConfig,
+    Profile,
+    get_profile,
+    list_profiles,
+)
+from .scoring import (
+    AmenityHit,
+    CategoryResult,
+    PenaltyResult,
+    WalkScorer,
+    WalkScoreResult,
+    compare,
+    decay,
+    rating_for,
+    score_grid,
+    score_point,
+)
+
+__all__ = [
+    "__version__",
+    "AmenityHit",
+    "CategoryConfig",
+    "CategoryResult",
+    "DEFAULT_ENDPOINTS",
+    "DEM",
+    "DecayConfig",
+    "NetworkMetrics",
+    "OSMData",
+    "OverpassClient",
+    "OverpassError",
+    "POI",
+    "PenaltyConfig",
+    "PenaltyResult",
+    "Profile",
+    "WalkNetwork",
+    "WalkScoreResult",
+    "WalkScorer",
+    "Way",
+    "build_query",
+    "compare",
+    "decay",
+    "dijkstra",
+    "get_profile",
+    "list_profiles",
+    "load_dem",
+    "load_osm",
+    "parse_geojson",
+    "parse_osm_xml",
+    "parse_overpass_json",
+    "rating_for",
+    "render_html",
+    "score_grid",
+    "score_point",
+    "write_html",
+]

openwalkscore/_version.py

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

openwalkscore/cli.py

@@ -0,0 +1,258 @@
+"""Command-line interface: ``openwalkscore score | grid | explain | compare | profiles``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Sequence
+
+from ._version import __version__
+from .overpass import DEFAULT_ENDPOINTS, OverpassClient, OverpassError
+from .profiles import list_profiles, resolve_profile
+from .scoring import RATINGS, WalkScoreResult, compare, score_grid, score_point
+
+METHOD_SUMMARY = """\
+openwalkscore method (all numbers come from the profile shown below):
+  1. Distances to amenities are measured along the OpenStreetMap walking network
+     (pure-Python Dijkstra, points snapped to the nearest street edge). Without a
+     network, straight-line distance x detour_factor is used.
+  2. Each amenity earns credit 1 up to decay.full_m, falling smoothly to 0 at
+     decay.zero_m.
+  3. Per category the best max_count amenities are kept; the k-th is weighted by
+     ratio^(k-1) (normalised), so extra amenities add less and less.
+  4. Access score = 100 x sum(weight x category subscore) / sum(weight).
+  5. Penalties for low intersection density, long blocks and (with a DEM) steep
+     grades scale the access score down; combined penalty <= max_total_penalty.
+Not affiliated with Walk Score(R) or Redfin; scores are not comparable to theirs.
+"""
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--profile",
+        default="default",
+        help="built-in profile name (%(default)s), or a .toml profile file",
+    )
+    p.add_argument(
+        "--input",
+        "-i",
+        dest="input",
+        help="offline OSM input (.osm, .geojson or Overpass .json) instead of downloading",
+    )
+    p.add_argument("--dem", help="ESRI ASCII grid (.asc, WGS 84) for the slope penalty")
+    p.add_argument(
+        "--engine", choices=("python", "networkx"), default="python", help="shortest-path engine"
+    )
+    p.add_argument("--timeout", type=float, default=60.0, help="Overpass timeout in seconds")
+    p.add_argument(
+        "--endpoint",
+        action="append",
+        help="Overpass interpreter URL (repeat for fail-over; default: public mirrors)",
+    )
+    p.add_argument("--no-cache", action="store_true", help="bypass the on-disk Overpass cache")
+    p.add_argument("--cache-dir", help="Overpass cache folder")
+
+
+def _add_point(p: argparse.ArgumentParser, required: bool = True) -> None:
+    p.add_argument("--lat", type=float, required=required, help="latitude (WGS 84)")
+    p.add_argument("--lon", type=float, required=required, help="longitude (WGS 84)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="openwalkscore",
+        description="Open, transparent walkability scores (0-100) from OpenStreetMap.",
+        epilog="Not affiliated with Walk Score(R)/Redfin. Map data (c) OpenStreetMap contributors.",
+    )
+    parser.add_argument("--version", action="version", version=f"openwalkscore {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("score", help="score one point")
+    _add_point(s)
+    _add_common(s)
+    s.add_argument("--name", default="", help="label for the point")
+    s.add_argument("--json", action="store_true", help="print the full result as JSON")
+    s.add_argument("--html", help="also write an HTML map to this file")
+
+    g = sub.add_parser("grid", help="score a grid of cells, write GeoJSON")
+    g.add_argument(
+        "--bbox",
+        required=True,
+        help="west,south,east,north in degrees (e.g. 2.33,48.85,2.36,48.87)",
+    )
+    g.add_argument("--cell", type=float, default=250.0, help="cell size in metres (%(default)s)")
+    g.add_argument("--max-cells", type=int, default=10_000, help="safety limit on cell count")
+    g.add_argument("-o", "--output", required=True, help="output GeoJSON path")
+    g.add_argument("--html", help="also write an HTML map to this file")
+    _add_common(g)
+
+    e = sub.add_parser("explain", help="explain a point's score, or the method and profile")
+    _add_point(e, required=False)
+    _add_common(e)
+
+    c = sub.add_parser("compare", help="score and rank several points")
+    c.add_argument(
+        "--point",
+        action="append",
+        required=True,
+        help="'lat,lon' or 'name,lat,lon' (repeat)",
+    )
+    _add_common(c)
+    c.add_argument("--json", action="store_true", help="print results as JSON")
+    c.add_argument("--html", help="also write an HTML map to this file")
+
+    sub.add_parser("profiles", help="list built-in profiles")
+    return parser
+
+
+def _client(args: argparse.Namespace) -> OverpassClient:
+    cache: Any = False if args.no_cache else (args.cache_dir or None)
+    return OverpassClient(
+        endpoints=args.endpoint or DEFAULT_ENDPOINTS, timeout_s=args.timeout, cache_dir=cache
+    )
+
+
+def _kwargs(args: argparse.Namespace) -> dict[str, Any]:
+    return {
+        "data": args.input,
+        "dem": args.dem,
+        "engine": args.engine,
+        "client": _client(args),
+        "use_cache": not args.no_cache,
+    }
+
+
+def _summary(r: WalkScoreResult) -> str:
+    head = f"{r.name + ': ' if r.name else ''}{r.score}/100 ({r.rating})"
+    lines = [
+        head,
+        f"  location      {r.lat:.6f}, {r.lon:.6f}",
+        f"  profile       {r.profile}   distances: {r.distance_mode}",
+        f"  access score  {r.access_score:.1f}   penalties: -{r.total_penalty * 100:.1f} %",
+        "  subscores:",
+    ]
+    for c in r.categories:
+        near = c.nearest
+        where = f"{near.name} @ {near.distance_m:.0f} m" if near else "-"
+        lines.append(f"    {c.label:<22} {c.subscore * 100:5.1f} %   {where}")
+    return "\n".join(lines)
+
+
+def _parse_point(text: str) -> tuple[str, float, float]:
+    parts = [p.strip() for p in text.split(",")]
+    if len(parts) == 2:
+        return ("", float(parts[0]), float(parts[1]))
+    if len(parts) == 3:
+        return (parts[0], float(parts[1]), float(parts[2]))
+    raise ValueError(f"--point {text!r}: use 'lat,lon' or 'name,lat,lon'")
+
+
+def _cmd_score(args: argparse.Namespace) -> int:
+    r = score_point(args.lat, args.lon, args.profile, name=args.name, **_kwargs(args))
+    print(json.dumps(r.to_dict(), indent=2, ensure_ascii=False) if args.json else _summary(r))
+    if args.html:
+        from .htmlmap import write_html
+
+        write_html(r, args.html, title=f"openwalkscore {r.score}/100")
+        print(f"map written to {args.html}", file=sys.stderr)
+    return 0
+
+
+def _cmd_grid(args: argparse.Namespace) -> int:
+    parts = [p.strip() for p in args.bbox.split(",")]
+    if len(parts) != 4:
+        raise ValueError("--bbox needs four comma-separated numbers: west,south,east,north")
+    bbox = (float(parts[0]), float(parts[1]), float(parts[2]), float(parts[3]))
+    fc = score_grid(bbox, args.cell, args.profile, max_cells=args.max_cells, **_kwargs(args))
+    Path(args.output).write_text(json.dumps(fc, ensure_ascii=False), encoding="utf-8")
+    props = fc["properties"]
+    print(f"{props['cells']} cells, mean score {props['mean_score']} -> {args.output}")
+    if args.html:
+        from .htmlmap import write_html
+
+        write_html(fc, args.html, title="openwalkscore grid")
+        print(f"map written to {args.html}", file=sys.stderr)
+    return 0
+
+
+def _cmd_explain(args: argparse.Namespace) -> int:
+    if (args.lat is None) != (args.lon is None):
+        raise ValueError("give both --lat and --lon, or neither")
+    if args.lat is None:
+        prof = resolve_profile(args.profile)
+        print(METHOD_SUMMARY)
+        print("Rating bands: " + ", ".join(f"{name} >= {lo}" for lo, name in RATINGS))
+        print(f"\nProfile '{prof.name}':")
+        print(json.dumps(prof.to_dict(), indent=2))
+        return 0
+    r = score_point(args.lat, args.lon, args.profile, **_kwargs(args))
+    print(r.explain())
+    near = r.nearest_amenities(limit=15)
+    if near:
+        print("\nNearest counted amenities:")
+        for h in near:
+            print(
+                f"  {h.distance_m:7.0f} m  {h.category:<18} {h.name}  "
+                f"(credit {h.credit:.2f}, {h.distance_mode}, {h.osm_ref})"
+            )
+    return 0
+
+
+def _cmd_compare(args: argparse.Namespace) -> int:
+    pts = [_parse_point(p) for p in args.point]
+    named = [(n or f"#{i + 1}", la, lo) for i, (n, la, lo) in enumerate(pts)]
+    results = compare(named, args.profile, **_kwargs(args))
+    if args.json:
+        print(json.dumps([r.to_dict() for r in results], indent=2, ensure_ascii=False))
+    else:
+        ranked = sorted(results, key=lambda r: -r.score)
+        print(f"{'rank':<5}{'name':<24}{'score':>6}  rating")
+        for i, r in enumerate(ranked, 1):
+            print(f"{i:<5}{r.name[:23]:<24}{r.score:>6}  {r.rating}")
+    if args.html:
+        from .htmlmap import write_html
+
+        write_html(results, args.html, title="openwalkscore comparison")
+        print(f"map written to {args.html}", file=sys.stderr)
+    return 0
+
+
+def _cmd_profiles(args: argparse.Namespace) -> int:
+    for name in list_profiles():
+        print(f"{name:<10} {resolve_profile(name).description}")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point; returns a process exit code."""
+    # OSM names are in every script; never crash on a narrow console encoding.
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(errors="backslashreplace")
+            except (ValueError, OSError):  # pragma: no cover - exotic streams
+                pass
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handlers = {
+        "score": _cmd_score,
+        "grid": _cmd_grid,
+        "explain": _cmd_explain,
+        "compare": _cmd_compare,
+        "profiles": _cmd_profiles,
+    }
+    try:
+        return handlers[args.command](args)
+    except OverpassError as exc:
+        print(f"openwalkscore: download failed: {exc}", file=sys.stderr)
+        return 3
+    except (ValueError, FileNotFoundError, OSError) as exc:
+        print(f"openwalkscore: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

openwalkscore/dem.py

@@ -0,0 +1,120 @@
+"""Optional elevation input for the slope penalty.
+
+The scorer only needs a callable ``elevation(lat, lon) -> metres | None``. This
+module offers two ready-made sources without heavy dependencies:
+
+* :meth:`DEM.from_ascii_grid` reads an ESRI ASCII grid (``.asc``) in geographic
+  coordinates (WGS 84 degrees), the format GDAL writes with
+  ``gdal_translate -of AAIGrid``.
+* :meth:`DEM.from_function` wraps any callable (for example a rasterio sampler).
+"""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+from typing import Callable, Optional
+
+__all__ = ["DEM", "load_dem"]
+
+
+class DEM:
+    """Elevation source. Call it as ``dem(lat, lon)``; returns metres or ``None``."""
+
+    def __init__(self, fn: Callable[[float, float], Optional[float]], name: str = "dem") -> None:
+        self._fn = fn
+        self.name = name
+
+    def __call__(self, lat: float, lon: float) -> float | None:
+        z = self._fn(lat, lon)
+        if z is None:
+            return None
+        z = float(z)
+        return z if math.isfinite(z) else None
+
+    @classmethod
+    def from_function(cls, fn: Callable[[float, float], Optional[float]]) -> DEM:
+        return cls(fn, name=getattr(fn, "__name__", "function"))
+
+    @classmethod
+    def from_ascii_grid(cls, path: str | Path) -> DEM:
+        """Load an ESRI ASCII grid whose cell coordinates are WGS 84 degrees.
+
+        Values are bilinearly interpolated between cell centres; points outside
+        the grid or touching ``NODATA`` cells return ``None``.
+        """
+        header: dict[str, float] = {}
+        rows: list[list[float]] = []
+        with open(path, encoding="utf-8") as fh:
+            for line in fh:
+                parts = line.split()
+                if not parts:
+                    continue
+                key = parts[0].lower()
+                if not rows and key in (
+                    "ncols",
+                    "nrows",
+                    "xllcorner",
+                    "yllcorner",
+                    "xllcenter",
+                    "yllcenter",
+                    "cellsize",
+                    "nodata_value",
+                ):
+                    header[key] = float(parts[1])
+                    continue
+                rows.append([float(p) for p in parts])
+        for req in ("ncols", "nrows", "cellsize"):
+            if req not in header:
+                raise ValueError(f"{path}: ASCII grid header lacks {req!r}")
+        ncols, nrows, cs = int(header["ncols"]), int(header["nrows"]), header["cellsize"]
+        values = [v for row in rows for v in row]
+        if len(values) != ncols * nrows:
+            raise ValueError(f"{path}: expected {ncols * nrows} values, found {len(values)}")
+        grid = [values[r * ncols : (r + 1) * ncols] for r in range(nrows)]
+        if "xllcenter" in header:
+            x0 = header["xllcenter"]
+            y0 = header["yllcenter"]
+        else:
+            x0 = header.get("xllcorner", 0.0) + cs / 2
+            y0 = header.get("yllcorner", 0.0) + cs / 2
+        nodata = header.get("nodata_value")
+        # Row 0 is the northern edge; cell-centre latitude of row r:
+        y_top = y0 + (nrows - 1) * cs
+
+        def sample(lat: float, lon: float) -> float | None:
+            fx = (lon - x0) / cs
+            fy = (y_top - lat) / cs
+            eps = 1e-6  # forgive floating-point round-off at the grid edge
+            if fx < -eps or fy < -eps or fx > ncols - 1 + eps or fy > nrows - 1 + eps:
+                return None
+            fx = min(max(fx, 0.0), ncols - 1.0)
+            fy = min(max(fy, 0.0), nrows - 1.0)
+            c0 = min(int(fx), max(ncols - 2, 0))
+            r0 = min(int(fy), max(nrows - 2, 0))
+            c1, r1 = min(c0 + 1, ncols - 1), min(r0 + 1, nrows - 1)
+            tx, ty = fx - c0, fy - r0
+            corners = (grid[r0][c0], grid[r0][c1], grid[r1][c0], grid[r1][c1])
+            if nodata is not None and any(v == nodata for v in corners):
+                return None
+            top = corners[0] * (1 - tx) + corners[1] * tx
+            bottom = corners[2] * (1 - tx) + corners[3] * tx
+            return top * (1 - ty) + bottom * ty
+
+        return cls(sample, name=str(path))
+
+
+def load_dem(
+    source: str | Path | DEM | Callable[[float, float], Optional[float]] | None,
+) -> DEM | None:
+    """Turn a path, callable or :class:`DEM` into a :class:`DEM` (``None`` passes through)."""
+    if source is None or isinstance(source, DEM):
+        return source
+    if callable(source):
+        return DEM.from_function(source)
+    path = Path(source)
+    if path.suffix.lower() != ".asc":
+        raise ValueError(
+            "only ESRI ASCII grids (.asc) are read directly; pass a callable otherwise"
+        )
+    return DEM.from_ascii_grid(path)

openwalkscore/geo.py

@@ -0,0 +1,106 @@
+"""Small geodesy helpers: great-circle distance, local projection and bounding boxes.
+
+Everything here is pure Python. Distances are in metres, coordinates in WGS 84
+degrees. The local projection is an equirectangular approximation that is accurate
+to well under 1 % over the few kilometres a walkability analysis covers.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Tuple
+
+EARTH_RADIUS_M = 6_371_008.8
+"""Mean Earth radius (IUGG) in metres."""
+
+BBox = Tuple[float, float, float, float]
+"""Bounding box as ``(west, south, east, north)`` in degrees (GeoJSON order)."""
+
+
+def haversine_m(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Great-circle distance between two WGS 84 points, in metres."""
+    p1 = math.radians(lat1)
+    p2 = math.radians(lat2)
+    dp = p2 - p1
+    dl = math.radians(lon2 - lon1)
+    a = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
+    return 2 * EARTH_RADIUS_M * math.asin(min(1.0, math.sqrt(a)))
+
+
+class LocalProjection:
+    """Equirectangular projection centred on a reference point.
+
+    ``forward`` maps ``(lat, lon)`` to ``(x, y)`` metres east/north of the origin and
+    ``inverse`` maps back. Good enough for city-scale geometry (snapping, buffers).
+    """
+
+    def __init__(self, lat0: float, lon0: float) -> None:
+        self.lat0 = lat0
+        self.lon0 = lon0
+        self._kx = math.radians(1.0) * EARTH_RADIUS_M * math.cos(math.radians(lat0))
+        self._ky = math.radians(1.0) * EARTH_RADIUS_M
+
+    def forward(self, lat: float, lon: float) -> tuple[float, float]:
+        return ((lon - self.lon0) * self._kx, (lat - self.lat0) * self._ky)
+
+    def inverse(self, x: float, y: float) -> tuple[float, float]:
+        return (self.lat0 + y / self._ky, self.lon0 + x / self._kx)
+
+
+def bbox_around(lat: float, lon: float, radius_m: float) -> BBox:
+    """Bounding box ``(west, south, east, north)`` that contains a circle of ``radius_m``."""
+    if radius_m < 0:
+        raise ValueError("radius_m must be non-negative")
+    dlat = math.degrees(radius_m / EARTH_RADIUS_M)
+    coslat = max(math.cos(math.radians(lat)), 1e-6)
+    dlon = math.degrees(radius_m / (EARTH_RADIUS_M * coslat))
+    return (lon - dlon, max(lat - dlat, -90.0), lon + dlon, min(lat + dlat, 90.0))
+
+
+def expand_bbox(bbox: BBox, margin_m: float) -> BBox:
+    """Grow a bounding box by ``margin_m`` metres on every side."""
+    west, south, east, north = validate_bbox(bbox)
+    dlat = math.degrees(margin_m / EARTH_RADIUS_M)
+    # The widest latitude of the box needs the largest longitude margin.
+    worst_lat = max(abs(south), abs(north))
+    coslat = max(math.cos(math.radians(worst_lat)), 1e-6)
+    dlon = math.degrees(margin_m / (EARTH_RADIUS_M * coslat))
+    return (
+        max(west - dlon, -180.0),
+        max(south - dlat, -90.0),
+        min(east + dlon, 180.0),
+        min(north + dlat, 90.0),
+    )
+
+
+def validate_bbox(bbox: BBox) -> BBox:
+    """Check that ``bbox`` is a sane ``(west, south, east, north)`` tuple and return it."""
+    if len(bbox) != 4:
+        raise ValueError("bbox must have four values: west, south, east, north")
+    west, south, east, north = (float(v) for v in bbox)
+    if not (-180.0 <= west <= 180.0 and -180.0 <= east <= 180.0):
+        raise ValueError("bbox longitudes must be within [-180, 180]")
+    if not (-90.0 <= south <= 90.0 and -90.0 <= north <= 90.0):
+        raise ValueError("bbox latitudes must be within [-90, 90]")
+    if west >= east or south >= north:
+        raise ValueError("bbox must satisfy west < east and south < north (west,south,east,north)")
+    return (west, south, east, north)
+
+
+def bbox_diagonal_m(bbox: BBox) -> float:
+    """Length of the bounding-box diagonal in metres."""
+    west, south, east, north = bbox
+    return haversine_m(south, west, north, east)
+
+
+def validate_latlon(lat: float, lon: float) -> tuple[float, float]:
+    """Return ``(lat, lon)`` as floats or raise ``ValueError`` when out of range."""
+    lat_f = float(lat)
+    lon_f = float(lon)
+    if not (math.isfinite(lat_f) and math.isfinite(lon_f)):
+        raise ValueError("latitude and longitude must be finite numbers")
+    if not -90.0 <= lat_f <= 90.0:
+        raise ValueError(f"latitude {lat_f} is outside [-90, 90]")
+    if not -180.0 <= lon_f <= 180.0:
+        raise ValueError(f"longitude {lon_f} is outside [-180, 180]")
+    return lat_f, lon_f