gpxsheet 0.1.1__py3-none-any.whl

gpxsheet/__init__.py

@@ -0,0 +1,137 @@
+"""GPXSheet — motorcycle sport-touring route awareness generator.
+
+Public library API. See ``PRODUCT.md`` for the full design specification.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import Route
+
+__version__ = "0.1.1"  # x-release-please-version
+
+__all__ = [
+    "__version__",
+    "generate_pdf",
+    "generate_strip",
+    "analyze",
+    "analyze_route",
+    "load_route",
+]
+
+DEFAULT_PROFILE = "sport-touring"
+
+
+def generate_pdf(
+    gpx_file: str,
+    output_file: str = "route.pdf",
+    *,
+    profile: str = DEFAULT_PROFILE,
+    fuel_range: float | None = None,
+    use_osm: bool = False,
+    turn_style: str = "stylized",
+    orientation: str = "landscape",
+    paper: str = "letter",
+    lanes_per_page: int = 4,
+    decisions_per_lane: int = 4,
+) -> str:
+    """Generate a tank-bag navigation PDF from a GPX file.
+
+    Args:
+        gpx_file: Path to the input ``.gpx`` route or track.
+        output_file: Path to write the rendered PDF to.
+        profile: One of ``minimalist``, ``sport-touring``, ``rally``.
+        fuel_range: Rider fuel range in miles, used for fuel-gap analysis.
+        use_osm: Enrich with OpenStreetMap road names/fuel (needs the osm extra).
+        turn_style: Strip bend style, ``"stylized"`` or ``"faithful"``.
+        orientation: ``"landscape"`` (one big strip per page) or ``"portrait"``
+            (several stacked strip lanes per page, roadbook-style).
+        paper: Page size, ``"letter"`` or ``"a4"``.
+        lanes_per_page: Portrait only -- number of strip lanes per page.
+        decisions_per_lane: Portrait only -- max decisions per lane.
+
+    Returns:
+        The path to the written PDF.
+    """
+    from .pdf import generate_pdf as _generate_pdf
+
+    return _generate_pdf(
+        gpx_file,
+        output_file,
+        profile=profile,
+        fuel_range=fuel_range,
+        use_osm=use_osm,
+        turn_style=turn_style,
+        orientation=orientation,
+        paper=paper,
+        lanes_per_page=lanes_per_page,
+        decisions_per_lane=decisions_per_lane,
+    )
+
+
+def analyze(
+    gpx_file: str,
+    *,
+    profile: str = DEFAULT_PROFILE,
+    fuel_range: float | None = None,
+    reassurance_interval: float | None = None,
+    use_osm: bool = False,
+    include_hazards: bool = False,
+) -> Route:
+    """Run the route analysis engine on a GPX file.
+
+    Loads the GPX, runs decision-point detection, reassurance-marker placement,
+    fuel analysis and segmentation, and returns the populated :class:`Route`.
+    ``include_hazards`` adds OSM hazard data for validation. See the ``analyze``
+    output mode in ``PRODUCT.md``.
+    """
+    from .analysis import analyze_route as _analyze_route
+    from .gpx import load_route as _load_route
+
+    route = _load_route(gpx_file)
+    return _analyze_route(
+        route,
+        profile=profile,
+        fuel_range=fuel_range,
+        reassurance_interval=reassurance_interval,
+        use_osm=use_osm,
+        include_hazards=include_hazards,
+    )
+
+
+def load_route(gpx_file: str, *, name: str | None = None) -> Route:
+    """Load a GPX file into a :class:`Route` without running analysis."""
+    from .gpx import load_route as _load_route
+
+    return _load_route(gpx_file, name=name)
+
+
+def analyze_route(route: Route, **kwargs) -> Route:
+    """Run analysis on an already-loaded :class:`Route` (see :mod:`gpxsheet.analysis`)."""
+    from .analysis import analyze_route as _analyze_route
+
+    return _analyze_route(route, **kwargs)
+
+
+def generate_strip(
+    gpx_file: str,
+    output_file: str = "route_strip.png",
+    *,
+    profile: str = DEFAULT_PROFILE,
+    fuel_range: float | None = None,
+    use_osm: bool = False,
+    turn_style: str = "stylized",
+) -> str:
+    """Render a route to a schematic map-strip image."""
+    from .strip import generate_strip as _generate_strip
+
+    return _generate_strip(
+        gpx_file,
+        output_file,
+        profile=profile,
+        fuel_range=fuel_range,
+        use_osm=use_osm,
+        turn_style=turn_style,
+    )

gpxsheet/analysis.py

@@ -0,0 +1,436 @@
+"""The route analysis engine.
+
+Geometry-only baseline for the pipeline stages in PRODUCT.md:
+
+    Geometry Cleanup -> Decision Point Detection
+                     -> Reassurance Marker Detection
+                     -> Fuel Analysis
+                     -> (light) Segmentation
+
+Road names, intersection classification and fuel-station discovery come from OSM
+enrichment (see :mod:`gpxsheet.enrich`), which is optional. Without it, decision
+points are detected purely from track geometry (localized heading changes) and
+fuel comes from GPX waypoints that look like fuel stops.
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import replace
+
+from .geo import bearing, bearing_delta, meters_to_miles, miles_to_meters
+from .models import (
+    DecisionKind,
+    DecisionPoint,
+    FuelReport,
+    FuelStop,
+    GeoPoint,
+    ReassuranceMarker,
+    Route,
+    Segment,
+)
+from .profiles import Profile, get_profile
+from .simplify import rdp
+
+# Cleanup tolerance: strip GPS jitter before bearing analysis.
+CLEANUP_TOLERANCE_M = 10.0
+# A turn must accumulate at least this much heading change to count.
+TURN_ANGLE_THRESHOLD_DEG = 35.0
+# ...and do so within this arc length, so sweeping curves (large radius) are
+# excluded while junction-style turns (tight radius) are kept.
+MAX_TURN_ARC_M = 90.0
+# Heading change below this at a vertex is treated as "straight" (breaks a run).
+STRAIGHT_EPS_DEG = 8.0
+# Suppress a reassurance marker only if it falls this close to the route end
+# (where it would be redundant with arrival). Small and fixed so a marker that
+# is genuinely far from the end is never dropped.
+END_MARKER_BUFFER_MILES = 0.5
+# Decision points closer than this do not each start a new segment (avoids
+# degenerate zero-length legs from clustered turns on noisy recorded tracks).
+MIN_SEGMENT_MILES = 0.1
+# Decision points within this distance of each other are collapsed into one
+# (real recorded tracks produce tight clusters at complex intersections).
+MERGE_MIN_SEPARATION_MILES = 0.2
+# OSM decision detection: a road name must hold for at least this distance to
+# count as a real road (filters nearest-edge flapping at junctions). Tuned
+# against real tracks (see git history / tests).
+MIN_ROAD_RUN_MILES = 0.3
+# A road-name change with a heading change below this reads as "Continue onto",
+# not "Left/Right onto".
+CONTINUE_MAX_ANGLE_DEG = 25.0
+# Below this point density the geometry is too sparse to follow roads (e.g. a
+# waypoint-only <rte> with long straight legs); OSM road-name sampling along such
+# straight lines snaps to whatever streets it crosses, so we skip enrichment.
+MIN_POINTS_PER_MILE_FOR_OSM = 1.0
+
+
+def looks_sparse(route: Route) -> bool:
+    """True if the route geometry is too sparse for reliable OSM enrichment.
+
+    Sparse routes (few points over long distances, e.g. device ``<rte>`` exports)
+    are drawn as straight lines between waypoints that do not follow real roads,
+    so sampling OSM road names along them is meaningless.
+    """
+    if route.length_miles <= 0:
+        return False
+    return len(route.points) / route.length_miles < MIN_POINTS_PER_MILE_FOR_OSM
+
+# Fuel-stop detection from waypoint names/symbols when OSM is unavailable.
+_FUEL_HINTS = ("fuel", "gas", "petrol", "station", "shell", "chevron", "76", "arco")
+
+
+def _turn_word(total_angle: float) -> str:
+    direction = "Right" if total_angle > 0 else "Left"
+    if abs(total_angle) >= 100.0:
+        return f"Sharp {direction.lower()}"
+    return direction
+
+
+def _significance_for_turn(total_angle: float) -> int:
+    mag = abs(total_angle)
+    if mag >= 100.0:
+        return 80
+    if mag >= 60.0:
+        return 60
+    return 45
+
+
+def coord_at_meters(route: Route, meters: float) -> tuple[float, float]:
+    """(lat, lon) interpolated along the route at a given along-track distance.
+
+    Linear interpolation between the two bracketing vertices, so results are
+    accurate even on sparsely sampled routes (important for measuring turn
+    angles around a point).
+    """
+    dist = route.distances_m
+    target = max(0.0, min(meters, dist[-1]))
+    hi = 1
+    lo_b, hi_b = 1, len(dist) - 1
+    while lo_b < hi_b:
+        mid = (lo_b + hi_b) // 2
+        if dist[mid] < target:
+            lo_b = mid + 1
+        else:
+            hi_b = mid
+    hi = lo_b
+    lo = hi - 1
+    span = dist[hi] - dist[lo]
+    f = 0.0 if span <= 0 else (target - dist[lo]) / span
+    a, b = route.points[lo], route.points[hi]
+    return a.lat + f * (b.lat - a.lat), a.lon + f * (b.lon - a.lon)
+
+
+def turn_angle_at_mile(route: Route, mile: float, window_m: float = 50.0) -> float:
+    """Signed heading change of the route across a point (+right / -left).
+
+    Compares the bearing approaching ``mile`` with the bearing departing it,
+    sampled ``window_m`` either side. Used to give an OSM road-name-change
+    decision its turn direction.
+    """
+    center_m = miles_to_meters(mile)
+    before = coord_at_meters(route, center_m - window_m)
+    at = coord_at_meters(route, center_m)
+    after = coord_at_meters(route, center_m + window_m)
+    approach = bearing(before[0], before[1], at[0], at[1])
+    depart = bearing(at[0], at[1], after[0], after[1])
+    return bearing_delta(approach, depart)
+
+
+def merge_close_decisions(
+    decisions: list[DecisionPoint], min_separation_miles: float = MERGE_MIN_SEPARATION_MILES
+) -> list[DecisionPoint]:
+    """Collapse decisions closer than ``min_separation_miles`` into one each.
+
+    The representative of a cluster is its highest-significance member (ties
+    broken by sharpest turn), so the rider gets one prompt for a complex
+    intersection instead of several.
+    """
+    if min_separation_miles <= 0 or len(decisions) < 2:
+        return list(decisions)
+    ordered = sorted(decisions, key=lambda d: d.mile)
+    merged: list[DecisionPoint] = []
+    cluster: list[DecisionPoint] = [ordered[0]]
+    for d in ordered[1:]:
+        if d.mile - cluster[-1].mile <= min_separation_miles:
+            cluster.append(d)
+        else:
+            merged.append(_pick_representative(cluster))
+            cluster = [d]
+    merged.append(_pick_representative(cluster))
+    return merged
+
+
+def _pick_representative(cluster: list[DecisionPoint]) -> DecisionPoint:
+    return max(cluster, key=lambda d: (d.significance, abs(d.turn_angle or 0.0)))
+
+
+def detect_decision_points(points: list[GeoPoint]) -> list[DecisionPoint]:
+    """Detect localized turns from cleaned geometry.
+
+    Consecutive same-direction heading changes are grouped into a single turn;
+    a group qualifies as a decision when its total heading change exceeds
+    :data:`TURN_ANGLE_THRESHOLD_DEG` within :data:`MAX_TURN_ARC_M`.
+    """
+    clean = rdp(points, CLEANUP_TOLERANCE_M)
+    if len(clean) < 3:
+        return []
+
+    bearings = [
+        bearing(clean[i].lat, clean[i].lon, clean[i + 1].lat, clean[i + 1].lon)
+        for i in range(len(clean) - 1)
+    ]
+    # Turn angle at interior vertex i (1..len-2) is delta between leg i-1 and leg i.
+    deltas = [bearing_delta(bearings[i - 1], bearings[i]) for i in range(1, len(bearings))]
+
+    # Recompute cumulative distance on the cleaned geometry.
+    from .geo import cumulative_distances
+
+    clean_dist = cumulative_distances([(p.lat, p.lon) for p in clean])
+
+    decisions: list[DecisionPoint] = []
+    run: list[int] = []  # indices into `clean` (vertex index = delta index + 1)
+
+    def flush(run_idx: list[int]) -> None:
+        if not run_idx:
+            return
+        total = sum(deltas[v - 1] for v in run_idx)
+        if abs(total) >= TURN_ANGLE_THRESHOLD_DEG:
+            apex = max(run_idx, key=lambda v: abs(deltas[v - 1]))
+            decisions.append(
+                DecisionPoint(
+                    mile=meters_to_miles(clean_dist[apex]),
+                    instruction=_turn_word(total),
+                    significance=_significance_for_turn(total),
+                    lat=clean[apex].lat,
+                    lon=clean[apex].lon,
+                    kind=DecisionKind.CRITICAL_TURN,
+                    turn_angle=round(total, 1),
+                )
+            )
+
+    # Group consecutive heading changes that are part of the *same* corner: same
+    # turn direction and confined to a short arc. After geometry cleanup, a long
+    # straight (or a separate corner farther along) appears as a far-apart vertex,
+    # which breaks the run so each corner is detected independently. A genuine
+    # sweeping curve spreads its heading change over a long arc, so its per-vertex
+    # deltas stay below the threshold and it is not flagged.
+    sign = 0
+    for vtx in range(1, len(clean) - 1):
+        d = deltas[vtx - 1]
+        if abs(d) < STRAIGHT_EPS_DEG:
+            flush(run)
+            run, sign = [], 0
+            continue
+        d_sign = 1 if d > 0 else -1
+        too_far = bool(run) and (clean_dist[vtx] - clean_dist[run[0]]) > MAX_TURN_ARC_M
+        if run and (d_sign != sign or too_far):
+            flush(run)
+            run = []
+        sign = d_sign
+        run.append(vtx)
+    flush(run)
+
+    decisions.sort(key=lambda d: d.mile)
+    return decisions
+
+
+def generate_reassurance_markers(
+    route: Route, interval_miles: float
+) -> list[ReassuranceMarker]:
+    """Place a marker every ``interval_miles``, labeled by the nearest waypoint."""
+    if interval_miles <= 0 or route.length_miles <= interval_miles:
+        return []
+
+    markers: list[ReassuranceMarker] = []
+    mile = interval_miles
+    while mile < route.length_miles - END_MARKER_BUFFER_MILES:
+        idx = _index_at_mile(route, mile)
+        pt = route.points[idx]
+        label, reason = _label_near(route, idx)
+        markers.append(
+            ReassuranceMarker(
+                mile=round(mile, 1), label=label, lat=pt.lat, lon=pt.lon, reason=reason
+            )
+        )
+        mile += interval_miles
+    return markers
+
+
+def _index_at_mile(route: Route, mile: float) -> int:
+    target_m = miles_to_meters(mile)
+    # distances_m is sorted ascending.
+    lo, hi = 0, len(route.distances_m) - 1
+    while lo < hi:
+        mid = (lo + hi) // 2
+        if route.distances_m[mid] < target_m:
+            lo = mid + 1
+        else:
+            hi = mid
+    return lo
+
+
+def _label_near(route: Route, idx: int, max_miles: float = 1.0) -> tuple[str, str]:
+    """Best label for a point: nearest named waypoint, else the mileage."""
+    pt = route.points[idx]
+    best_name, best_d = None, miles_to_meters(max_miles)
+    from .geo import haversine
+
+    for wp in route.waypoints:
+        if not wp.name:
+            continue
+        d = haversine(pt.lat, pt.lon, wp.lat, wp.lon)
+        if d < best_d:
+            best_name, best_d = wp.name, d
+    if best_name:
+        return best_name, "landmark"
+    return f"{meters_to_miles(route.distances_m[idx]):.0f} mi", "interval"
+
+
+def _looks_like_fuel(wp_name: str | None, wp_symbol: str | None) -> bool:
+    haystack = f"{wp_name or ''} {wp_symbol or ''}".lower()
+    return any(h in haystack for h in _FUEL_HINTS)
+
+
+def detect_fuel_stops(route: Route) -> list[FuelStop]:
+    """Find fuel stops from GPX waypoints (OSM enrichment supersedes this)."""
+    stops: list[FuelStop] = []
+    from .geo import haversine
+
+    for wp in route.waypoints:
+        if not _looks_like_fuel(wp.name, wp.symbol):
+            continue
+        # Project waypoint onto route by nearest vertex for a mileage estimate.
+        nearest = min(
+            range(len(route.points)),
+            key=lambda i: haversine(route.points[i].lat, route.points[i].lon, wp.lat, wp.lon),
+        )
+        stops.append(
+            FuelStop(
+                mile=round(meters_to_miles(route.distances_m[nearest]), 1),
+                name=wp.name or "Fuel",
+                lat=wp.lat,
+                lon=wp.lon,
+            )
+        )
+    stops.sort(key=lambda s: s.mile)
+    return stops
+
+
+def analyze_fuel(route: Route, fuel_range: float | None) -> FuelReport:
+    """Longest fuel gap and range warning, given detected fuel stops."""
+    stops = route.fuel_stops
+    miles = [0.0] + [s.mile for s in stops] + [route.length_miles]
+    gaps = [b - a for a, b in zip(miles, miles[1:], strict=False)]
+    longest = max(gaps) if gaps else route.length_miles
+    return FuelReport(
+        longest_gap_miles=round(longest, 1),
+        recommended=[s.name for s in stops],
+        exceeds_range=bool(fuel_range and longest > fuel_range),
+        fuel_range_miles=fuel_range,
+    )
+
+
+def build_segments(route: Route) -> list[Segment]:
+    """Split the route into legs between decision points.
+
+    Decision points closer together than :data:`MIN_SEGMENT_MILES` (e.g. the
+    tight clusters real recorded tracks produce at complex intersections) do not
+    each start a new leg, so no degenerate zero-length segments are emitted.
+    Legs are numbered sequentially ("Leg N"); enrichment renames them to the
+    dominant road name for each leg.
+    """
+    boundaries = [0.0] + [d.mile for d in route.decision_points] + [route.length_miles]
+    boundaries = sorted({round(b, 3) for b in boundaries})
+    segments: list[Segment] = []
+    start = boundaries[0]
+    for end in boundaries[1:]:
+        if end - start < MIN_SEGMENT_MILES:
+            continue  # too short to be its own leg; fold into the next boundary
+        segments.append(
+            Segment(
+                name=f"Leg {len(segments) + 1}",
+                start_mile=round(start, 1),
+                end_mile=round(end, 1),
+            )
+        )
+        start = end
+    # Extend the final leg to the route end if a trailing sliver was folded in.
+    if segments and segments[-1].end_mile < round(route.length_miles, 1):
+        segments[-1] = replace(segments[-1], end_mile=round(route.length_miles, 1))
+    return segments
+
+
+def analyze_route(
+    route: Route,
+    *,
+    profile: str | Profile = "sport-touring",
+    fuel_range: float | None = None,
+    reassurance_interval: float | None = None,
+    use_osm: bool = False,
+    include_hazards: bool = False,
+) -> Route:
+    """Run the full analysis, populating ``route`` in place.
+
+    ``include_hazards`` adds OSM hazard data (ferry crossings; unpaved mileage is
+    always captured when OSM runs) for :func:`gpxsheet.validate.validate_route`.
+    Returns the same :class:`Route` for convenience.
+    """
+    prof = profile if isinstance(profile, Profile) else get_profile(profile)
+    interval = (
+        reassurance_interval
+        if reassurance_interval is not None
+        else prof.reassurance_interval_miles
+    )
+
+    # 1. Geometry baseline: localized turns, clustered firings collapsed. On
+    #    twisty roads this over-detects (curves look like turns) -- OSM in step 2
+    #    replaces these with junction/road-name decisions when available.
+    route.decision_points = merge_close_decisions(detect_decision_points(route.points))
+    route.fuel_stops = detect_fuel_stops(route) if prof.include_fuel else []
+    route.segments = build_segments(route)
+
+    # 2. OSM enrichment: replaces decisions with durable road-name changes,
+    #    segments with the named roads, and adds OSM fuel. Must run after step 1.
+    #    Degrades to geometry-only (with a warning) when the extra is missing, the
+    #    route is too sparse, or the live Overpass query fails -- so OSM can be the
+    #    default without breaking core installs or offline use.
+    if use_osm:
+        from .enrich import osm_available
+
+        if not osm_available():
+            warnings.warn(
+                "OSM enrichment requested but the 'osm' extra is not installed "
+                "(pip install 'gpxsheet[osm]'); using geometry-only analysis.",
+                stacklevel=2,
+            )
+        elif looks_sparse(route):
+            warnings.warn(
+                "Route geometry is sparse (likely a waypoint-only <rte>); skipping "
+                "OSM enrichment, which would sample road names along straight lines "
+                "that do not follow roads. Using geometry-only analysis.",
+                stacklevel=2,
+            )
+        else:
+            from .enrich import enrich_route
+
+            try:
+                enrich_route(
+                    route, include_fuel=prof.include_fuel, include_hazards=include_hazards
+                )
+            except Exception as exc:  # network/Overpass/data failure -> fall back
+                warnings.warn(
+                    f"OSM enrichment failed ({type(exc).__name__}: {exc}); "
+                    "using geometry-only analysis.",
+                    stacklevel=2,
+                )
+
+    # 3. Apply the profile's display threshold to whatever decisions step 1/2
+    #    produced, then derive products that depend on the final fuel stops.
+    route.decision_points = [
+        d for d in route.decision_points if d.significance >= prof.decision_threshold
+    ]
+    route.fuel_report = analyze_fuel(route, fuel_range) if prof.include_fuel else None
+    route.reassurance_markers = (
+        generate_reassurance_markers(route, interval) if prof.include_reassurance else []
+    )
+    return route