geofencing 0.1.0__py3-none-any.whl

geofencing/__init__.py

@@ -0,0 +1,72 @@
+"""geofencing: fast, dependency-free geofence checks and enter/exit/dwell events.
+
+Quick start::
+
+    from geofencing import CircleFence, FenceIndex, GeofenceEngine
+
+    idx = FenceIndex([CircleFence("depot", 29.02, 41.01, radius_m=150)])
+    idx.containing_ids(29.021, 41.0105)          # ['depot']
+
+    engine = GeofenceEngine(idx, min_inside_s=10, buffer_m=15, dwell_s=300)
+    for event in engine.process_many(positions):
+        print(event.to_dict())
+"""
+
+from ._geodesy import geodesic_distance_m, haversine_m, normalize_lon
+from .engine import EngineConfig, GeofenceEngine
+from .events import Event, EventType, Position
+from .fences import (
+    BOUNDARY,
+    INSIDE,
+    OUTSIDE,
+    BBoxFence,
+    CircleFence,
+    CorridorFence,
+    Fence,
+    PolygonFence,
+)
+from .index import FenceIndex
+from .io import (
+    fence_from_feature,
+    fences_from_geojson,
+    fences_to_geojson,
+    load_fences,
+    read_positions,
+    save_fences,
+    write_events,
+)
+from .rtree import STRTree
+from .schedule import Schedule, ScheduleRule
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BOUNDARY",
+    "INSIDE",
+    "OUTSIDE",
+    "BBoxFence",
+    "CircleFence",
+    "CorridorFence",
+    "EngineConfig",
+    "Event",
+    "EventType",
+    "Fence",
+    "FenceIndex",
+    "GeofenceEngine",
+    "PolygonFence",
+    "Position",
+    "STRTree",
+    "Schedule",
+    "ScheduleRule",
+    "__version__",
+    "fence_from_feature",
+    "fences_from_geojson",
+    "fences_to_geojson",
+    "geodesic_distance_m",
+    "haversine_m",
+    "load_fences",
+    "normalize_lon",
+    "read_positions",
+    "save_fences",
+    "write_events",
+]

geofencing/__main__.py

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

geofencing/_geodesy.py

@@ -0,0 +1,172 @@
+"""Geodesy helpers: distances, destinations and longitude arithmetic.
+
+Everything here is pure Python (``math`` only). Coordinates are always
+``(lon, lat)`` in decimal degrees on WGS84.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Optional, Tuple
+
+#: Mean Earth radius (IUGG), metres.
+EARTH_RADIUS_M = 6371008.8
+#: WGS84 semi-major axis, metres.
+WGS84_A = 6378137.0
+#: WGS84 flattening.
+WGS84_F = 1.0 / 298.257223563
+#: Metres per degree of latitude on the mean sphere.
+M_PER_DEG = EARTH_RADIUS_M * math.pi / 180.0
+
+#: Bound on ``|ellipsoidal / spherical - 1|`` for any pair of points. The local
+#: radii of curvature of WGS84 lie within -0.56 % / +0.46 % of the mean radius, so
+#: 1 % is a safe band outside which the fast spherical answer is already decisive.
+SPHERE_ELLIPSOID_BAND = 0.01
+
+_DEG = math.pi / 180.0
+
+
+def normalize_lon(lon: float) -> float:
+    """Wrap a longitude into ``[-180, 180)``."""
+    if -180.0 <= lon < 180.0:
+        return lon
+    return ((lon + 180.0) % 360.0) - 180.0
+
+
+def wrap_delta(d: float) -> float:
+    """Wrap a longitude difference into ``[-180, 180]``."""
+    if -180.0 <= d <= 180.0:
+        return d
+    d = ((d + 180.0) % 360.0) - 180.0
+    return d
+
+
+def metres_per_degree_lon(lat: float) -> float:
+    """Metres per degree of longitude at ``lat`` (never exactly zero)."""
+    return max(math.cos(lat * _DEG) * M_PER_DEG, 1e-6)
+
+
+def haversine_m(lon1: float, lat1: float, lon2: float, lat2: float) -> float:
+    """Great-circle distance on the mean sphere, metres."""
+    p1 = lat1 * _DEG
+    p2 = lat2 * _DEG
+    dp = p2 - p1
+    dl = (lon2 - lon1) * _DEG
+    h = math.sin(dp * 0.5) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl * 0.5) ** 2
+    if h > 1.0:
+        h = 1.0
+    return 2.0 * EARTH_RADIUS_M * math.asin(math.sqrt(h))
+
+
+def vincenty_inverse_m(
+    lon1: float, lat1: float, lon2: float, lat2: float, max_iter: int = 200
+) -> Optional[float]:
+    """Ellipsoidal (WGS84) distance by Vincenty's inverse formula, metres.
+
+    Accurate to well below a millimetre. Returns ``None`` when the iteration
+    does not converge (nearly antipodal points).
+    """
+    a = WGS84_A
+    f = WGS84_F
+    b = a * (1.0 - f)
+    big_l = wrap_delta(lon2 - lon1) * _DEG
+    phi1 = lat1 * _DEG
+    phi2 = lat2 * _DEG
+    u1 = math.atan2((1.0 - f) * math.sin(phi1), math.cos(phi1))
+    u2 = math.atan2((1.0 - f) * math.sin(phi2), math.cos(phi2))
+    sin_u1, cos_u1 = math.sin(u1), math.cos(u1)
+    sin_u2, cos_u2 = math.sin(u2), math.cos(u2)
+    lam = big_l
+    sin_sigma = cos_sigma = sigma = cos2_alpha = cos_2sm = 0.0
+    for _ in range(max_iter):
+        sin_lam = math.sin(lam)
+        cos_lam = math.cos(lam)
+        sin_sigma = math.hypot(cos_u2 * sin_lam, cos_u1 * sin_u2 - sin_u1 * cos_u2 * cos_lam)
+        if sin_sigma == 0.0:
+            return 0.0
+        cos_sigma = sin_u1 * sin_u2 + cos_u1 * cos_u2 * cos_lam
+        sigma = math.atan2(sin_sigma, cos_sigma)
+        sin_alpha = cos_u1 * cos_u2 * sin_lam / sin_sigma
+        cos2_alpha = 1.0 - sin_alpha * sin_alpha
+        cos_2sm = cos_sigma - 2.0 * sin_u1 * sin_u2 / cos2_alpha if cos2_alpha != 0.0 else 0.0
+        c = f / 16.0 * cos2_alpha * (4.0 + f * (4.0 - 3.0 * cos2_alpha))
+        lam_prev = lam
+        lam = big_l + (1.0 - c) * f * sin_alpha * (
+            sigma + c * sin_sigma * (cos_2sm + c * cos_sigma * (-1.0 + 2.0 * cos_2sm * cos_2sm))
+        )
+        if abs(lam - lam_prev) < 1e-12:
+            break
+    else:
+        return None
+    u_sq = cos2_alpha * (a * a - b * b) / (b * b)
+    big_a = 1.0 + u_sq / 16384.0 * (4096.0 + u_sq * (-768.0 + u_sq * (320.0 - 175.0 * u_sq)))
+    big_b = u_sq / 1024.0 * (256.0 + u_sq * (-128.0 + u_sq * (74.0 - 47.0 * u_sq)))
+    d_sigma = (
+        big_b
+        * sin_sigma
+        * (
+            cos_2sm
+            + big_b
+            / 4.0
+            * (
+                cos_sigma * (-1.0 + 2.0 * cos_2sm * cos_2sm)
+                - big_b
+                / 6.0
+                * cos_2sm
+                * (-3.0 + 4.0 * sin_sigma * sin_sigma)
+                * (-3.0 + 4.0 * cos_2sm * cos_2sm)
+            )
+        )
+    )
+    return b * big_a * (sigma - d_sigma)
+
+
+def geodesic_distance_m(lon1: float, lat1: float, lon2: float, lat2: float) -> float:
+    """Ellipsoidal distance, falling back to the sphere for antipodal pairs."""
+    d = vincenty_inverse_m(lon1, lat1, lon2, lat2)
+    if d is None:
+        return haversine_m(lon1, lat1, lon2, lat2)
+    return d
+
+
+def destination(
+    lon: float, lat: float, bearing_deg: float, distance_m: float
+) -> Tuple[float, float]:
+    """Point reached from ``(lon, lat)`` along a great circle (mean sphere)."""
+    delta = distance_m / EARTH_RADIUS_M
+    theta = bearing_deg * _DEG
+    phi1 = lat * _DEG
+    lam1 = lon * _DEG
+    sin_phi2 = math.sin(phi1) * math.cos(delta) + math.cos(phi1) * math.sin(delta) * math.cos(theta)
+    sin_phi2 = max(-1.0, min(1.0, sin_phi2))
+    phi2 = math.asin(sin_phi2)
+    y = math.sin(theta) * math.sin(delta) * math.cos(phi1)
+    x = math.cos(delta) - math.sin(phi1) * sin_phi2
+    lam2 = lam1 + math.atan2(y, x)
+    return normalize_lon(lam2 / _DEG), phi2 / _DEG
+
+
+def unit_vector(lon: float, lat: float) -> Tuple[float, float, float]:
+    """Earth-centred unit vector of a point on the sphere."""
+    p = lat * _DEG
+    lam = lon * _DEG
+    cp = math.cos(p)
+    return (cp * math.cos(lam), cp * math.sin(lam), math.sin(p))
+
+
+def cap_bbox(lon: float, lat: float, angle_rad: float) -> Tuple[float, float, float, float]:
+    """Lon/lat bounding box of a spherical cap (centre, angular radius).
+
+    Longitudes are *unwrapped* around ``lon`` (they may leave ``[-180, 180]``).
+    A cap that reaches a pole spans the full 360 degrees of longitude.
+    """
+    r_deg = angle_rad / _DEG
+    south = lat - r_deg
+    north = lat + r_deg
+    if north >= 90.0 or south <= -90.0 or angle_rad >= math.pi / 2:
+        return (-180.0, max(south, -90.0), 180.0, min(north, 90.0))
+    s = math.sin(angle_rad) / math.cos(lat * _DEG)
+    if s >= 1.0:  # pragma: no cover - rounding guard (implies north >= 90)
+        return (-180.0, south, 180.0, north)
+    dlon = math.asin(s) / _DEG
+    return (lon - dlon, south, lon + dlon, north)

geofencing/bench.py

@@ -0,0 +1,191 @@
+"""Synthetic benchmarks (``geofencing bench``)."""
+
+from __future__ import annotations
+
+import math
+import random
+import time
+from typing import Any, Dict, List, Optional
+
+from .engine import GeofenceEngine
+from .events import Position
+from .fences import HAVE_NUMPY, CircleFence, Fence, PolygonFence
+from .index import FenceIndex
+
+
+def star_polygon(
+    rng: random.Random, lon: float, lat: float, radius_deg: float, n: int, concavity: float = 0.5
+) -> List[List[float]]:
+    """A random star-shaped (generally concave) ring, closed, CCW."""
+    ring = []
+    for i in range(n):
+        a = 2.0 * math.pi * i / n
+        r = radius_deg * (1.0 - concavity * rng.random())
+        ring.append(
+            [lon + r * math.cos(a) / max(math.cos(math.radians(lat)), 0.05), lat + r * math.sin(a)]
+        )
+    ring.append(ring[0])
+    return ring
+
+
+def synthetic_fences(
+    n: int,
+    seed: int = 0,
+    region: tuple = (28.6, 40.8, 29.6, 41.3),
+    vertices: int = 24,
+) -> List[Fence]:
+    """``n`` fences (75 % concave polygons, 25 % circles) scattered over ``region``."""
+    rng = random.Random(seed)
+    w, s, e, nn = region
+    out: List[Fence] = []
+    for i in range(n):
+        lon = rng.uniform(w, e)
+        lat = rng.uniform(s, nn)
+        if i % 4 == 3:
+            out.append(CircleFence(f"c{i}", lon, lat, rng.uniform(100.0, 800.0)))
+        else:
+            r = rng.uniform(0.002, 0.008)
+            out.append(PolygonFence.from_polygon(f"p{i}", star_polygon(rng, lon, lat, r, vertices)))
+    return out
+
+
+def _rate(n: int, seconds: float) -> float:
+    return n / seconds if seconds > 0 else float("inf")
+
+
+def run_benchmarks(
+    n_fences: int = 10_000, n_points: int = 20_000, seed: int = 0, include_engine: bool = True
+) -> List[Dict[str, Any]]:
+    """Measure points/s for 1 and ``n_fences`` fences; returns result rows."""
+    rng = random.Random(seed)
+    results: List[Dict[str, Any]] = []
+    # Fence density is held at 10^4 fences per 1 x 0.5 degree (about 85 x 55 km)
+    # so larger runs measure index scaling rather than ever-deeper overlap.
+    k = max(1.0, math.sqrt(n_fences / 10_000))
+    region = (29.1 - 0.5 * k, 41.05 - 0.25 * k, 29.1 + 0.5 * k, 41.05 + 0.25 * k)
+
+    def points(k: int, box: tuple) -> tuple:
+        w, s, e, n = box
+        return [rng.uniform(w, e) for _ in range(k)], [rng.uniform(s, n) for _ in range(k)]
+
+    # 1 fence: a 256-vertex concave polygon, points in its bounding box.
+    single = PolygonFence.from_polygon("big", star_polygon(rng, 29.0, 41.0, 0.2, 256))
+    idx1 = FenceIndex([single])
+    w, s, e, n = single.bbox()
+    xs, ys = points(n_points, (w, s, e, n))
+    t0 = time.perf_counter()
+    hits = sum(1 for x, y in zip(xs, ys) if idx1.containing(x, y))
+    dt = time.perf_counter() - t0
+    results.append(
+        {
+            "scenario": "1 polygon (256 vertices)",
+            "method": "index.containing",
+            "points": n_points,
+            "seconds": dt,
+            "points_per_s": _rate(n_points, dt),
+            "hits": hits,
+        }
+    )
+    t0 = time.perf_counter()
+    hits = sum(1 for x, y in zip(xs, ys) if single.contains(x, y))
+    dt = time.perf_counter() - t0
+    results.append(
+        {
+            "scenario": "1 polygon (256 vertices)",
+            "method": "fence.contains",
+            "points": n_points,
+            "seconds": dt,
+            "points_per_s": _rate(n_points, dt),
+            "hits": hits,
+        }
+    )
+    if HAVE_NUMPY:
+        t0 = time.perf_counter()
+        res = idx1.contains_many(xs, ys)
+        dt = time.perf_counter() - t0
+        results.append(
+            {
+                "scenario": "1 polygon (256 vertices)",
+                "method": "index.contains_many (numpy)",
+                "points": n_points,
+                "seconds": dt,
+                "points_per_s": _rate(n_points, dt),
+                "hits": sum(1 for r in res if r),
+            }
+        )
+
+    # Many fences.
+    t0 = time.perf_counter()
+    fences = synthetic_fences(n_fences, seed=seed, region=region)
+    idx = FenceIndex(fences)
+    build = time.perf_counter() - t0
+    xs, ys = points(n_points, region)
+    t0 = time.perf_counter()
+    hits = sum(len(idx.containing(x, y)) for x, y in zip(xs, ys))
+    dt = time.perf_counter() - t0
+    label = f"{n_fences} fences"
+    results.append(
+        {
+            "scenario": label,
+            "method": "index.containing",
+            "points": n_points,
+            "seconds": dt,
+            "points_per_s": _rate(n_points, dt),
+            "hits": hits,
+            "build_s": build,
+        }
+    )
+    if HAVE_NUMPY:
+        t0 = time.perf_counter()
+        res = idx.contains_many(xs, ys)
+        dt = time.perf_counter() - t0
+        results.append(
+            {
+                "scenario": label,
+                "method": "index.contains_many (numpy)",
+                "points": n_points,
+                "seconds": dt,
+                "points_per_s": _rate(n_points, dt),
+                "hits": sum(len(r) for r in res),
+            }
+        )
+    if include_engine:
+        eng = GeofenceEngine(idx, min_inside_s=5, min_outside_s=5, buffer_m=10, dwell_s=60)
+        n_dev = 100
+        steps = max(1, n_points // n_dev)
+        lon = [rng.uniform(region[0], region[2]) for _ in range(n_dev)]
+        lat = [rng.uniform(region[1], region[3]) for _ in range(n_dev)]
+        fixes: List[Position] = []
+        for step in range(steps):
+            for d in range(n_dev):
+                lon[d] += rng.gauss(0, 0.0003)
+                lat[d] += rng.gauss(0, 0.0003)
+                fixes.append(Position(f"d{d}", lon[d], lat[d], float(step), 5.0))
+        t0 = time.perf_counter()
+        n_ev = sum(1 for _ in eng.process_many(fixes))
+        dt = time.perf_counter() - t0
+        results.append(
+            {
+                "scenario": label,
+                "method": "engine.process (100 devices)",
+                "points": len(fixes),
+                "seconds": dt,
+                "points_per_s": _rate(len(fixes), dt),
+                "hits": n_ev,
+            }
+        )
+    return results
+
+
+def format_results(rows: List[Dict[str, Any]], numpy: Optional[bool] = None) -> str:
+    """Plain-text table of :func:`run_benchmarks` output."""
+    lines = [f"{'scenario':<28} {'method':<30} {'points':>8} {'points/s':>12}"]
+    lines.append("-" * len(lines[0]))
+    for r in rows:
+        lines.append(
+            f"{r['scenario']:<28} {r['method']:<30} {r['points']:>8} {r['points_per_s']:>12,.0f}"
+        )
+    if numpy is None:
+        numpy = HAVE_NUMPY
+    lines.append(f"(numpy {'available' if numpy else 'not installed'})")
+    return "\n".join(lines)

geofencing/cli.py

@@ -0,0 +1,141 @@
+"""Command line interface: ``geofencing check | replay | bench``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import List, Optional
+
+from . import __version__
+from .engine import EngineConfig, GeofenceEngine
+from .index import FenceIndex
+from .io import load_fences, read_positions, write_events
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    idx = FenceIndex(load_fences(args.fences))
+    kw = {}
+    if args.tolerance is not None:
+        kw["tolerance_m"] = args.tolerance
+    if args.exclusive:
+        kw["inclusive"] = False
+    hits = idx.containing(args.lon, args.lat, args.time, **kw)
+    out = {
+        "lon": args.lon,
+        "lat": args.lat,
+        "inside": [f.id for f in hits],
+        "speed_limit": idx.speed_limit_at(args.lon, args.lat, args.time),
+    }
+    if args.time is not None:
+        out["time"] = args.time
+    print(json.dumps(out))
+    return 0 if hits or not args.exit_code else 1
+
+
+def _cmd_replay(args: argparse.Namespace) -> int:
+    idx = FenceIndex(load_fences(args.fences))
+    cfg = EngineConfig(
+        min_inside_s=args.min_inside,
+        min_outside_s=args.min_outside,
+        buffer_m=args.buffer,
+        dwell_s=args.dwell,
+        dwell_repeat_s=args.dwell_repeat,
+        max_accuracy_m=args.max_accuracy,
+        poor_accuracy=args.poor_accuracy,
+        out_of_order=args.out_of_order,
+        reorder_window_s=args.reorder_window,
+    )
+    eng = GeofenceEngine(idx, cfg)
+    if args.state_in:
+        eng.load_state(args.state_in)
+    positions = read_positions(args.positions, fmt=args.format)
+    events = eng.process_many(positions)
+    if args.output in (None, "-"):
+        n = write_events(events, sys.stdout)
+    else:
+        n = write_events(events, args.output)
+    if args.state_out:
+        eng.save_state(args.state_out)
+    s = eng.stats
+    print(
+        f"{n} events from {s['fixes']} fixes "
+        f"({s['ignored_accuracy']} ignored for accuracy, "
+        f"{s['dropped_out_of_order']} out of order) against {len(idx)} fences",
+        file=sys.stderr,
+    )
+    return 0
+
+
+def _cmd_bench(args: argparse.Namespace) -> int:
+    from .bench import format_results, run_benchmarks
+
+    rows = run_benchmarks(args.fences, args.points, args.seed, include_engine=not args.no_engine)
+    if args.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        print(format_results(rows))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="geofencing", description="Fast geofence checks and events.")
+    p.add_argument("--version", action="version", version=f"geofencing {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    c = sub.add_parser("check", help="which fences contain a point")
+    c.add_argument("fences", help="GeoJSON file with fences")
+    c.add_argument("--lat", type=float, required=True)
+    c.add_argument("--lon", type=float, required=True)
+    c.add_argument("--time", help="ISO 8601 time or POSIX seconds (for scheduled fences)")
+    c.add_argument("--tolerance", type=float, help="boundary tolerance in metres")
+    c.add_argument("--exclusive", action="store_true", help="points on the boundary are outside")
+    c.add_argument(
+        "--exit-code", action="store_true", help="exit 1 when no fence contains the point"
+    )
+    c.set_defaults(func=_cmd_check)
+
+    r = sub.add_parser("replay", help="replay a position file through the event engine")
+    r.add_argument("fences", help="GeoJSON file with fences")
+    r.add_argument("positions", help="CSV or JSONL positions")
+    r.add_argument("-o", "--output", help="events JSONL (default: stdout)")
+    r.add_argument(
+        "--format", choices=["csv", "jsonl"], help="positions format (default: by extension)"
+    )
+    r.add_argument("--min-inside", type=float, default=0.0, metavar="S")
+    r.add_argument("--min-outside", type=float, default=0.0, metavar="S")
+    r.add_argument(
+        "--buffer", type=float, default=0.0, metavar="M", help="hysteresis band in metres"
+    )
+    r.add_argument("--dwell", type=float, metavar="S", help="emit DWELL after S seconds inside")
+    r.add_argument("--dwell-repeat", type=float, metavar="S")
+    r.add_argument("--max-accuracy", type=float, metavar="M")
+    r.add_argument("--poor-accuracy", choices=["ignore", "uncertain"], default="ignore")
+    r.add_argument("--out-of-order", choices=["drop", "reorder"], default="drop")
+    r.add_argument("--reorder-window", type=float, default=0.0, metavar="S")
+    r.add_argument("--state-in", help="resume from a saved engine state (JSON)")
+    r.add_argument("--state-out", help="save the engine state (JSON) at the end")
+    r.set_defaults(func=_cmd_replay)
+
+    b = sub.add_parser("bench", help="synthetic throughput benchmark")
+    b.add_argument("--fences", type=int, default=10_000)
+    b.add_argument("--points", type=int, default=20_000)
+    b.add_argument("--seed", type=int, default=0)
+    b.add_argument("--no-engine", action="store_true")
+    b.add_argument("--json", action="store_true")
+    b.set_defaults(func=_cmd_bench)
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except (OSError, ValueError) as exc:
+        print(f"geofencing: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())