geojson-diff 0.1.0__py3-none-any.whl

geojson_diff/geometry.py

@@ -0,0 +1,454 @@
+"""Pure-Python geometry helpers: distances, Hausdorff, area, length, hashing.
+
+All functions accept GeoJSON geometry dictionaries. Longitude/latitude data
+(RFC 7946) is measured on a sphere (haversine for distances, the spherical
+excess formula for areas); projected data is measured in CRS units.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from collections.abc import Iterator, Sequence
+from difflib import SequenceMatcher
+from typing import Any
+
+__all__ = [
+    "EARTH_RADIUS_M",
+    "Metric",
+    "bbox",
+    "bbox_union",
+    "centroid",
+    "geometry_area",
+    "geometry_hash",
+    "geometry_length",
+    "geometry_vertices",
+    "hausdorff_distance",
+    "haversine",
+    "is_geographic",
+    "iter_parts",
+    "same_structure",
+    "vertex_changes",
+]
+
+EARTH_RADIUS_M = 6371008.8
+"""Mean Earth radius used for haversine distances."""
+_AREA_RADIUS_M = 6378137.0  # WGS84 semi-major axis, as used by common GeoJSON area tools
+_M_PER_DEG = math.pi * EARTH_RADIUS_M / 180.0
+
+Position = Sequence[float]
+Geometry = dict[str, Any]
+BBox = tuple[float, float, float, float]
+
+
+# --------------------------------------------------------------------------- parts
+
+
+def iter_parts(geom: Geometry | None) -> Iterator[tuple[str, list[Position]]]:
+    """Yield ``(kind, positions)`` for every primitive part of ``geom``.
+
+    ``kind`` is ``"point"``, ``"line"`` or ``"ring"``.
+    """
+    if not geom:
+        return
+    kind = geom.get("type")
+    coords = geom.get("coordinates")
+    if kind == "Point":
+        if coords:
+            yield "point", [coords]
+    elif kind == "MultiPoint":
+        for point in coords or []:
+            yield "point", [point]
+    elif kind == "LineString":
+        yield "line", list(coords or [])
+    elif kind == "MultiLineString":
+        for line in coords or []:
+            yield "line", list(line)
+    elif kind == "Polygon":
+        for ring in coords or []:
+            yield "ring", list(ring)
+    elif kind == "MultiPolygon":
+        for polygon in coords or []:
+            for ring in polygon:
+                yield "ring", list(ring)
+    elif kind == "GeometryCollection":
+        for member in geom.get("geometries") or []:
+            yield from iter_parts(member)
+    else:
+        raise ValueError(f"unsupported geometry type {kind!r}")
+
+
+def geometry_vertices(geom: Geometry | None) -> list[Position]:
+    """All positions of ``geom`` (closing ring positions included)."""
+    out: list[Position] = []
+    for _, positions in iter_parts(geom):
+        out.extend(positions)
+    return out
+
+
+def _distinct(kind: str, positions: list[Position]) -> list[Position]:
+    if kind == "ring" and len(positions) > 1 and list(positions[0]) == list(positions[-1]):
+        return positions[:-1]
+    return positions
+
+
+def bbox(geom: Geometry | None) -> BBox | None:
+    """``(min_x, min_y, max_x, max_y)`` of ``geom`` or ``None`` when empty."""
+    xs: list[float] = []
+    ys: list[float] = []
+    for pos in geometry_vertices(geom):
+        xs.append(float(pos[0]))
+        ys.append(float(pos[1]))
+    if not xs:
+        return None
+    return (min(xs), min(ys), max(xs), max(ys))
+
+
+def bbox_union(boxes: Sequence[BBox | None]) -> BBox | None:
+    """Union of bounding boxes, ignoring ``None`` entries."""
+    real = [b for b in boxes if b is not None]
+    if not real:
+        return None
+    return (
+        min(b[0] for b in real),
+        min(b[1] for b in real),
+        max(b[2] for b in real),
+        max(b[3] for b in real),
+    )
+
+
+def is_geographic(*geoms: Geometry | None) -> bool:
+    """True when every coordinate looks like longitude/latitude."""
+    for geom in geoms:
+        for pos in geometry_vertices(geom):
+            if not (-180.0 <= pos[0] <= 180.0 and -90.0 <= pos[1] <= 90.0):
+                return False
+    return True
+
+
+def centroid(geom: Geometry | None) -> tuple[float, float] | None:
+    """Mean of the distinct vertices (a cheap, stable representative point)."""
+    sx = sy = 0.0
+    n = 0
+    for kind, positions in iter_parts(geom):
+        for pos in _distinct(kind, positions):
+            sx += pos[0]
+            sy += pos[1]
+            n += 1
+    if n == 0:
+        return None
+    return (sx / n, sy / n)
+
+
+# ----------------------------------------------------------------------- distances
+
+
+def haversine(a: Position, b: Position) -> float:
+    """Great-circle distance in metres between two lon/lat positions."""
+    lon1, lat1, lon2, lat2 = map(math.radians, (a[0], a[1], b[0], b[1]))
+    h = (
+        math.sin((lat2 - lat1) / 2.0) ** 2
+        + math.cos(lat1) * math.cos(lat2) * math.sin((lon2 - lon1) / 2.0) ** 2
+    )
+    return 2.0 * EARTH_RADIUS_M * math.asin(min(1.0, math.sqrt(h)))
+
+
+def _wrap(dlon: float) -> float:
+    while dlon > 180.0:
+        dlon -= 360.0
+    while dlon < -180.0:
+        dlon += 360.0
+    return dlon
+
+
+class Metric:
+    """Distance functions in metres (lon/lat data) or in coordinate units."""
+
+    def __init__(self, metres: bool) -> None:
+        self.metres = metres
+
+    def point(self, a: Position, b: Position) -> float:
+        if self.metres:
+            return haversine(a, b)
+        return math.hypot(b[0] - a[0], b[1] - a[1])
+
+    def segment(self, p: Position, a: Position, b: Position) -> float:
+        """Distance from ``p`` to the segment ``a``-``b``."""
+        if self.metres:
+            # Local equirectangular projection centred on p: accurate for the
+            # short segments that matter when comparing two versions of a feature.
+            k = math.cos(math.radians(p[1]))
+            ax, ay = _wrap(a[0] - p[0]) * k, a[1] - p[1]
+            bx, by = _wrap(b[0] - p[0]) * k, b[1] - p[1]
+            return _seg_origin(ax, ay, bx, by) * _M_PER_DEG
+        return _seg_origin(a[0] - p[0], a[1] - p[1], b[0] - p[0], b[1] - p[1])
+
+
+def _seg_origin(ax: float, ay: float, bx: float, by: float) -> float:
+    """Distance from the origin to the segment (ax, ay)-(bx, by)."""
+    dx, dy = bx - ax, by - ay
+    denom = dx * dx + dy * dy
+    if denom == 0.0:
+        return math.hypot(ax, ay)
+    t = -(ax * dx + ay * dy) / denom
+    t = 0.0 if t < 0.0 else min(t, 1.0)
+    return math.hypot(ax + t * dx, ay + t * dy)
+
+
+def _segments(geom: Geometry | None) -> list[tuple[Position, Position]]:
+    segs: list[tuple[Position, Position]] = []
+    for _, positions in iter_parts(geom):
+        if len(positions) == 1:
+            segs.append((positions[0], positions[0]))
+        for i in range(len(positions) - 1):
+            segs.append((positions[i], positions[i + 1]))
+    return segs
+
+
+def _directed(
+    points: list[Position],
+    segs: list[tuple[Position, Position]],
+    metric: Metric,
+    cmax: float,
+    limit: float | None,
+) -> float:
+    n, m = len(points), len(segs)
+    for i, p in enumerate(points):
+        cmin = math.inf
+        start = i * m // n
+        for k in range(m):
+            off = (k + 1) // 2 if k % 2 else -(k // 2)
+            a, b = segs[(start + off) % m]
+            d = metric.segment(p, a, b)
+            if d < cmin:
+                cmin = d
+                if cmin <= cmax:
+                    break  # early break: this point cannot raise the maximum
+        if cmin > cmax:
+            cmax = cmin
+            if limit is not None and cmax > limit:
+                return cmax
+    return cmax
+
+
+def hausdorff_distance(
+    a: Geometry | None,
+    b: Geometry | None,
+    metres: bool | None = None,
+    limit: float | None = None,
+) -> float:
+    """Symmetric Hausdorff distance between two geometries (pure Python).
+
+    Every vertex of one geometry is measured against the segments (and
+    points) of the other, in both directions. Uses the early-break algorithm
+    of Taha & Hanbury (2015), visiting candidate segments outward from the
+    aligned index, which makes it close to linear for two versions of the same
+    feature. When ``limit`` is given the search stops as soon as the distance
+    is known to exceed it (the returned value is then a lower bound above
+    ``limit``). ``metres=None`` measures in metres when both geometries are
+    longitude/latitude.
+    """
+    if metres is None:
+        metres = is_geographic(a, b)
+    metric = Metric(metres)
+    pa, pb = geometry_vertices(a), geometry_vertices(b)
+    if not pa and not pb:
+        return 0.0
+    if not pa or not pb:
+        return math.inf
+    cmax = _directed(pa, _segments(b), metric, 0.0, limit)
+    if limit is not None and cmax > limit:
+        return cmax
+    return _directed(pb, _segments(a), metric, cmax, limit)
+
+
+# --------------------------------------------------------------------- area/length
+
+
+def _ring_area_geodesic(ring: list[Position]) -> float:
+    n = len(ring)
+    if n < 3:
+        return 0.0
+    total = 0.0
+    for i in range(n):
+        if i == n - 2:
+            lo, mid, hi = n - 2, n - 1, 0
+        elif i == n - 1:
+            lo, mid, hi = n - 1, 0, 1
+        else:
+            lo, mid, hi = i, i + 1, i + 2
+        total += (math.radians(ring[hi][0]) - math.radians(ring[lo][0])) * math.sin(
+            math.radians(ring[mid][1])
+        )
+    return abs(total * _AREA_RADIUS_M * _AREA_RADIUS_M / 2.0)
+
+
+def _ring_area_planar(ring: list[Position]) -> float:
+    total = 0.0
+    n = len(ring)
+    for i in range(n):
+        x1, y1 = ring[i][0], ring[i][1]
+        x2, y2 = ring[(i + 1) % n][0], ring[(i + 1) % n][1]
+        total += x1 * y2 - x2 * y1
+    return abs(total) / 2.0
+
+
+def _polygon_area(rings: Sequence[list[Position]], metres: bool) -> float:
+    if not rings:
+        return 0.0
+    fn = _ring_area_geodesic if metres else _ring_area_planar
+    outer = fn(list(rings[0]))
+    holes = sum(fn(list(r)) for r in rings[1:])
+    return max(0.0, outer - holes)
+
+
+def geometry_area(geom: Geometry | None, metres: bool | None = None) -> float:
+    """Area in square metres (lon/lat data) or squared CRS units."""
+    if not geom:
+        return 0.0
+    if metres is None:
+        metres = is_geographic(geom)
+    kind = geom.get("type")
+    if kind == "Polygon":
+        return _polygon_area(geom.get("coordinates") or [], metres)
+    if kind == "MultiPolygon":
+        return sum(_polygon_area(p, metres) for p in geom.get("coordinates") or [])
+    if kind == "GeometryCollection":
+        return sum(geometry_area(g, metres) for g in geom.get("geometries") or [])
+    return 0.0
+
+
+def geometry_length(geom: Geometry | None, metres: bool | None = None) -> float:
+    """Length of lines (perimeter for polygons) in metres or CRS units."""
+    if not geom:
+        return 0.0
+    if metres is None:
+        metres = is_geographic(geom)
+    metric = Metric(metres)
+    total = 0.0
+    for kind, positions in iter_parts(geom):
+        if kind == "point":
+            continue
+        for i in range(len(positions) - 1):
+            total += metric.point(positions[i], positions[i + 1])
+    return total
+
+
+# ------------------------------------------------------------------------- hashing
+
+
+def _round(pos: Position, precision: int) -> list[float]:
+    return [round(float(c), precision) + 0.0 for c in pos]
+
+
+def _canonical_ring(ring: list[Position], precision: int) -> list[list[float]]:
+    pts = [_round(p, precision) for p in ring]
+    if len(pts) > 1 and pts[0] == pts[-1]:
+        pts = pts[:-1]
+    if not pts:
+        return []
+
+    def rotate(seq: list[list[float]]) -> list[list[float]]:
+        i = seq.index(min(seq))
+        return seq[i:] + seq[:i]
+
+    forward = rotate(pts)
+    backward = rotate(pts[::-1])
+    best = min(forward, backward)
+    return best + [best[0]]
+
+
+def _canonical(geom: Geometry | None, precision: int) -> Any:
+    if not geom:
+        return None
+    kind = geom.get("type")
+    coords = geom.get("coordinates")
+    if kind == "Point":
+        return [kind, _round(coords, precision) if coords else []]
+    if kind == "LineString":
+        return [kind, [_round(p, precision) for p in coords or []]]
+    if kind == "MultiPoint":
+        return [kind, sorted(_round(p, precision) for p in coords or [])]
+    if kind == "MultiLineString":
+        lines = [[_round(p, precision) for p in line] for line in coords or []]
+        return [kind, sorted(lines)]
+    if kind == "Polygon":
+        return [kind, [_canonical_ring(r, precision) for r in coords or []]]
+    if kind == "MultiPolygon":
+        polys = [[_canonical_ring(r, precision) for r in poly] for poly in coords or []]
+        return [kind, sorted(polys)]
+    if kind == "GeometryCollection":
+        members = [_canonical(g, precision) for g in geom.get("geometries") or []]
+        return [kind, sorted(members, key=lambda m: json.dumps(m))]
+    raise ValueError(f"unsupported geometry type {kind!r}")
+
+
+def geometry_hash(geom: Geometry | None, precision: int = 7) -> str:
+    """Stable SHA-1 of a geometry, insensitive to ring start/orientation and part order.
+
+    Coordinates are rounded to ``precision`` decimals (7 decimals is about
+    1 cm at the equator).
+    """
+    payload = json.dumps(_canonical(geom, precision), separators=(",", ":"))
+    return hashlib.sha1(payload.encode("utf-8")).hexdigest()
+
+
+# ------------------------------------------------------------------ vertex changes
+
+
+def same_structure(a: Geometry | None, b: Geometry | None) -> bool:
+    """True when both geometries have the same type, parts and vertex counts."""
+    if not a or not b or a.get("type") != b.get("type"):
+        return False
+    pa = [(k, len(p)) for k, p in iter_parts(a)]
+    pb = [(k, len(p)) for k, p in iter_parts(b)]
+    return pa == pb
+
+
+def _snap_key(pos: Position, grid: float) -> tuple[int, int]:
+    return (round(pos[0] / grid), round(pos[1] / grid))
+
+
+def vertex_changes(
+    a: Geometry | None,
+    b: Geometry | None,
+    tolerance: float,
+    metric: Metric,
+    grid: float,
+) -> dict[str, int]:
+    """Count vertices ``added``, ``removed`` and ``moved`` between two geometries.
+
+    Parts are compared in order. Equal-length parts are compared vertex by
+    vertex against ``tolerance`` (measured with ``metric``); otherwise the
+    vertex sequences, snapped to a ``grid`` in coordinate units, are aligned
+    with :class:`difflib.SequenceMatcher`.
+    """
+    parts_a = [_distinct(k, p) for k, p in iter_parts(a)]
+    parts_b = [_distinct(k, p) for k, p in iter_parts(b)]
+    added = removed = moved = 0
+    grid = grid if grid > 0 else 1e-9
+    for i in range(max(len(parts_a), len(parts_b))):
+        pa = parts_a[i] if i < len(parts_a) else []
+        pb = parts_b[i] if i < len(parts_b) else []
+        if len(pa) == len(pb):
+            moved += sum(1 for p, q in zip(pa, pb) if metric.point(p, q) > tolerance)
+            continue
+        sa = [_snap_key(p, grid) for p in pa]
+        sb = [_snap_key(p, grid) for p in pb]
+        for tag, i1, i2, j1, j2 in SequenceMatcher(None, sa, sb, autojunk=False).get_opcodes():
+            la, lb = i2 - i1, j2 - j1
+            if tag == "replace":
+                moved += min(la, lb)
+                added += max(0, lb - la)
+                removed += max(0, la - lb)
+            elif tag == "insert":
+                added += lb
+            elif tag == "delete":
+                removed += la
+    return {"added": added, "removed": removed, "moved": moved}
+
+
+def count_vertices(geom: Geometry | None) -> int:
+    """Number of distinct vertices (closing ring positions not counted)."""
+    return sum(len(_distinct(k, p)) for k, p in iter_parts(geom))

geojson_diff/git.py

@@ -0,0 +1,112 @@
+"""Git integration: textconv filter, external diff driver and revision access."""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import subprocess
+from typing import Any
+
+from .geometry import count_vertices, geometry_hash
+from .io import Source, iter_features
+
+__all__ = ["NULL_PATHS", "driver_sources", "read_revision", "textconv"]
+
+NULL_PATHS = ("/dev/null", "nul", "NUL")
+"""Placeholders git passes for the missing side of an added or deleted file."""
+
+_EMPTY: dict[str, Any] = {"type": "FeatureCollection", "features": []}
+
+
+def _round(obj: Any, precision: int) -> Any:
+    if isinstance(obj, (int, float)) and not isinstance(obj, bool):
+        return round(float(obj), precision) + 0.0  # 29 and 29.0 render alike
+    if isinstance(obj, list):
+        return [_round(o, precision) for o in obj]
+    if isinstance(obj, dict):
+        return {k: _round(v, precision) for k, v in obj.items()}
+    return obj
+
+
+def _sort_key(feature: dict[str, Any], index: int) -> tuple[int, str, int]:
+    fid = feature.get("id")
+    if fid is None:
+        return (1, "", index)
+    return (0, json.dumps(fid) if not isinstance(fid, str) else fid, index)
+
+
+def textconv(source: Source, precision: int = 7) -> str:
+    """A line-oriented, stable rendering of a GeoJSON file for ``git diff``.
+
+    Features are sorted by ``id`` (input order otherwise), one property per
+    line with sorted keys, so a plain line diff shows exactly which
+    attributes and geometries changed. Coordinates are rounded to
+    ``precision`` decimals.
+    """
+    features = list(iter_features(source))
+    order = sorted(range(len(features)), key=lambda i: _sort_key(features[i], i))
+    lines: list[str] = [f"# geojson-diff textconv: {len(features)} features"]
+    for i in order:
+        feature = features[i]
+        geom = feature.get("geometry")
+        fid = feature.get("id")
+        label = f"id={json.dumps(fid, ensure_ascii=False)}" if fid is not None else f"#{i}"
+        kind = geom.get("type") if geom else "null"
+        lines.append(f"feature {label} ({kind})")
+        props = feature.get("properties") or {}
+        for key in sorted(props):
+            value = json.dumps(props[key], ensure_ascii=False, sort_keys=True)
+            lines.append(f"  {json.dumps(key, ensure_ascii=False)}: {value}")
+        if geom:
+            digest = geometry_hash(geom, precision)[:12]
+            lines.append(f"  geometry: {kind}, {count_vertices(geom)} vertices, hash {digest}")
+            coords = geom.get("coordinates", geom.get("geometries"))
+            lines.append("  coordinates: " + json.dumps(_round(coords, precision)))
+    return "\n".join(lines) + "\n"
+
+
+def _side(path: str) -> Source:
+    if path in NULL_PATHS or not os.path.exists(path):
+        return dict(_EMPTY)
+    return path
+
+
+def driver_sources(args: list[str]) -> tuple[str, str, Source, Source]:
+    """Interpret the arguments git passes to a ``diff.<driver>.command``.
+
+    Git calls the command with ``path old-file old-hex old-mode new-file
+    new-hex new-mode`` (two more arguments for renames: the new path and a
+    similarity message). Returns the old and new display paths and the two
+    sources; ``/dev/null`` becomes an empty collection.
+    """
+    if len(args) not in (7, 9):
+        raise ValueError(
+            "--git expects the 7 (or 9) arguments git passes to an external diff command, "
+            f"got {len(args)}"
+        )
+    new_path = args[7] if len(args) == 9 else args[0]
+    return args[0], new_path, _side(args[1]), _side(args[4])
+
+
+def read_revision(rev: str, path: str, cwd: str | None = None, timeout: float = 60.0) -> Source:
+    """Contents of ``path`` at git revision ``rev`` (an empty collection if absent).
+
+    ``path`` is relative to the current directory, like other git commands.
+    """
+    spec = f"{rev}:./{path.replace(os.sep, '/')}" if not os.path.isabs(path) else f"{rev}:{path}"
+    proc = subprocess.run(
+        ["git", "show", spec],
+        cwd=cwd,
+        capture_output=True,
+        timeout=timeout,
+        check=False,
+    )
+    if proc.returncode != 0:
+        message = proc.stderr.decode("utf-8", "replace").strip()
+        if "exists on disk, but not in" in message or "does not exist in" in message:
+            return dict(_EMPTY)
+        raise ValueError(f"git show {spec} failed: {message or proc.returncode}")
+    stream = io.BytesIO(proc.stdout)
+    stream.name = f"{rev}:{path}"  # type: ignore[attr-defined]
+    return stream