Merge pull request #52 from riita10069/feat/gps-map-rendering

feat(data_parsing): add GPS-to-BEV map tile rendering utility

Author: m-zain-khawaja

Model/data_parsing/map_rendering/README.md

@@ -0,0 +1,142 @@
+# GPS → BEV Map Tile Rendering
+
+Offline preprocessing utility that turns raw GPS waypoints into BEV map tiles
+in the style of the L2D dataset's pre-rendered map. Use it for datasets that
+do not natively ship map images (e.g. KIT Scenes, NVIDIA PhysicalAI).
+
+## Ego-centric framing
+
+Tiles are rendered **ego-centric**, matching the L2D / NVIDIA / KIT Scenes
+convention:
+
+- Center: the ego pose `(ego_lat, ego_lon)` (defaults to the last GPS sample
+  when omitted in `gps_to_tensor`).
+- Orientation: rotated so the ego forward direction points **up** in the
+  image (forward = +y).
+- Frame: a local equirectangular projection — coordinates are converted from
+  lon/lat to metres relative to the ego, then rotated by `-ego_heading`. The
+  axes share a common metric scale (`ax.set_aspect("equal")`), so there is
+  no lat/lon aspect distortion.
+- Extent: a fixed metric window of `±radius_m` around the origin.
+
+`ego_heading` is in radians, measured CCW from north (so `0` = north, the
+ego is facing north and the tile is north-up).
+
+## When to use
+
+- You have GPS lat/lon traces per clip and want a model input equivalent to
+  L2D's BEV map tile.
+- You are building a dataset offline and can pre-render every tile.
+- You do **not** want to render at training time — fetching road networks via
+  Overpass takes seconds per call and requires internet access.
+
+## Workflow
+
+1. Build a `{clip_id: (latitudes, longitudes)}` mapping from your dataset.
+2. Run `render_and_cache_tiles(...)` once to produce one PNG per clip plus a
+   shared road-network pickle cache.
+3. In the DataLoader, read the PNG, push it through your timm transform like
+   any other camera tile.
+
+## Module layout
+
+| File | Purpose |
+| --- | --- |
+| `gps_to_map.py` | Core: fetch network, map-match, render, end-to-end tensor. |
+| `cache.py`      | Pickle network graphs and batch-render dataset tiles. |
+| `test_gps_to_map.py` | Offline tests; `osmnx.graph_from_point` is mocked. |
+
+## Public API
+
+```python
+from data_parsing.map_rendering import (
+    fetch_road_network,
+    map_match_waypoints,
+    render_map_tile,
+    gps_to_tensor,
+)
+from data_parsing.map_rendering.cache import (
+    cache_network,
+    load_cached_network,
+    render_and_cache_tiles,
+)
+```
+
+### Single-clip example
+
+```python
+import timm
+from data_parsing.map_rendering import gps_to_tensor
+
+backbone = timm.create_model("swinv2_tiny_window8_256", pretrained=False)
+data_cfg = timm.data.resolve_model_data_config(backbone)
+transform = timm.data.create_transform(**data_cfg, is_training=False)
+
+tensor = gps_to_tensor(
+    latitudes=lats,
+    longitudes=lons,
+    transform=transform,
+    ego_heading=heading_rad,  # radians CCW from north
+    # ego_lat / ego_lon default to the last GPS sample
+    radius_m=800,
+)
+# tensor.shape == (3, H, W) — drop straight into the visual_tiles slot.
+```
+
+### Batch preprocessing
+
+```python
+from data_parsing.map_rendering.cache import render_and_cache_tiles
+
+paths = render_and_cache_tiles(
+    dataset_gps_data={clip_id: (lats, lons) for clip_id, lats, lons in clips},
+    output_dir="cache/map_tiles",
+    network_cache_dir="cache/road_networks",
+    radius_m=800,
+)
+```
+
+`network_cache_dir` quantizes centroids to ~100 m so adjacent clips reuse the
+same downloaded graph.
+
+## Style
+
+Defaults match the L2D BEV map palette and dimensions:
+
+| Element | Default |
+| --- | --- |
+| Image size | 640 × 360 |
+| Background | `#111111` |
+| Road network | `#444444` |
+| Route | `#00CCFF` |
+| Raw GPS markers | `#FF3333` |
+| DPI | 200 |
+
+All of these are arguments on `render_map_tile` and `gps_to_tensor`.
+
+## Dependencies
+
+- `osmnx` (and its transitive `geopandas` / `shapely` chain)
+- `matplotlib` (headless `Agg` backend is selected automatically)
+- `Pillow`
+- `networkx`
+- `torch` (only for the tensor output path)
+
+Install with:
+
+```
+pip install osmnx geopandas matplotlib pillow networkx
+```
+
+## Notes
+
+- This is a **data preprocessing** utility. It lives in `data_parsing/`, not
+  `model_components/`. Do not call it from a `Dataset.__getitem__`.
+- Map matching can fail (waypoints outside the fetched bbox, disconnected
+  components). When it does, the renderer falls back to drawing the network
+  plus raw GPS markers.
+- `render_and_cache_tiles` estimates `ego_heading` from the last segment of
+  each GPS trace. If you have a more accurate heading source (IMU, GNSS
+  course-over-ground), prefer calling `render_map_tile` directly with it.
+- Tests must not require internet — `osmnx.graph_from_point` and
+  `osmnx.distance.nearest_nodes` are mocked.

Model/data_parsing/map_rendering/__init__.py

@@ -0,0 +1,20 @@
+"""Offline GPS-to-map-tile rendering for datasets that lack BEV map images.
+
+See README.md for the full preprocessing workflow. The rendered tiles match
+the L2D BEV map format and can be fed through the same timm transform as
+camera tiles.
+"""
+
+from .gps_to_map import (
+    fetch_road_network,
+    gps_to_tensor,
+    map_match_waypoints,
+    render_map_tile,
+)
+
+__all__ = [
+    "fetch_road_network",
+    "gps_to_tensor",
+    "map_match_waypoints",
+    "render_map_tile",
+]

Model/data_parsing/map_rendering/cache.py

@@ -0,0 +1,181 @@
+"""Caching helpers for the map rendering pipeline.
+
+Network fetches via osmnx are slow (seconds each, internet required). This
+module persists fetched graphs to disk and renders/persists tiles for an
+entire dataset in one batch so the DataLoader only ever reads PNGs.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+import pickle
+from pathlib import Path
+from typing import Mapping, Sequence
+
+import networkx as nx
+
+from .gps_to_map import (
+    DEFAULT_IMAGE_SIZE,
+    DEFAULT_RADIUS_M,
+    EARTH_RADIUS_M,
+    fetch_road_network,
+    map_match_waypoints,
+    render_map_tile,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def cache_network(graph: nx.MultiDiGraph, filepath: str | Path) -> None:
+    """Pickle a road-network graph to disk."""
+    path = Path(filepath)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("wb") as f:
+        pickle.dump(graph, f)
+
+
+def load_cached_network(filepath: str | Path) -> nx.MultiDiGraph | None:
+    """Load a pickled road-network graph, or `None` if the file is missing."""
+    path = Path(filepath)
+    if not path.exists():
+        return None
+    try:
+        with path.open("rb") as f:
+            return pickle.load(f)
+    except (OSError, pickle.UnpicklingError) as exc:
+        logger.warning("failed to load cached network %s: %s", path, exc)
+        return None
+
+
+def render_and_cache_tiles(
+    dataset_gps_data: Mapping[str, tuple[Sequence[float], Sequence[float]]],
+    output_dir: str | Path,
+    radius_m: int = DEFAULT_RADIUS_M,
+    image_size: tuple[int, int] = DEFAULT_IMAGE_SIZE,
+    network_cache_dir: str | Path | None = None,
+    skip_existing: bool = True,
+) -> list[Path]:
+    """Pre-render and persist a BEV map tile for every clip in a dataset.
+
+    Args:
+        dataset_gps_data: mapping of `clip_id -> (latitudes, longitudes)`.
+        output_dir: where rendered PNG tiles are written (`{clip_id}.png`).
+        radius_m: render radius around each clip's centroid.
+        image_size: output `(W, H)`.
+        network_cache_dir: if given, fetched graphs are persisted here keyed by
+            centroid so neighbouring clips share a cached download.
+        skip_existing: do not re-render clips whose PNG already exists.
+
+    Returns:
+        List of paths to the rendered tile files (including pre-existing ones).
+    """
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    net_cache = Path(network_cache_dir) if network_cache_dir else None
+    if net_cache is not None:
+        net_cache.mkdir(parents=True, exist_ok=True)
+
+    rendered: list[Path] = []
+    for clip_id, (lats, lons) in dataset_gps_data.items():
+        tile_path = out / f"{clip_id}.png"
+        if skip_existing and tile_path.exists():
+            rendered.append(tile_path)
+            continue
+
+        if not lats:
+            logger.warning("clip %s has no GPS samples; skipping", clip_id)
+            continue
+
+        ego_lat = float(lats[-1])
+        ego_lon = float(lons[-1])
+        ego_heading = _heading_from_trace(lats, lons, ego_lat)
+
+        graph = _load_or_fetch_network(
+            ego_lat, ego_lon, radius_m, net_cache
+        )
+        if graph is None:
+            logger.warning("clip %s: failed to obtain road network; skipping", clip_id)
+            continue
+
+        _, route = map_match_waypoints(graph, list(lats), list(lons))
+        raw_points = list(zip(lats, lons))
+        try:
+            image = render_map_tile(
+                graph,
+                route_nodes=route,
+                ego_lat=ego_lat,
+                ego_lon=ego_lon,
+                ego_heading=ego_heading,
+                raw_gps_points=raw_points,
+                radius_m=radius_m,
+                image_size=image_size,
+            )
+        except Exception as exc:  # noqa: BLE001 — matplotlib/osmnx errors vary
+            logger.warning(
+                "clip %s: render failed (%s); skipping",
+                clip_id,
+                exc,
+                exc_info=True,
+            )
+            continue
+
+        image.save(tile_path)
+        rendered.append(tile_path)
+
+    return rendered
+
+
+def _heading_from_trace(
+    lats: Sequence[float], lons: Sequence[float], ref_lat: float
+) -> float:
+    """Estimate ego heading (radians) from the last segment of the GPS trace.
+
+    Uses atan2(east, north) so 0 rad ≡ north and the value matches the
+    `ego_heading` convention in `render_map_tile`. Falls back to 0 when the
+    trace has fewer than two distinct samples.
+    """
+    if len(lats) < 2:
+        return 0.0
+    cos_lat = math.cos(math.radians(ref_lat))
+    deg_to_m = EARTH_RADIUS_M * math.pi / 180.0
+    dx = (lons[-1] - lons[-2]) * cos_lat * deg_to_m
+    dy = (lats[-1] - lats[-2]) * deg_to_m
+    if dx == 0.0 and dy == 0.0:
+        return 0.0
+    return math.atan2(dx, dy)
+
+
+def _load_or_fetch_network(
+    center_lat: float,
+    center_lon: float,
+    radius_m: int,
+    cache_dir: Path | None,
+) -> nx.MultiDiGraph | None:
+    """Return a cached graph if available, otherwise fetch and cache it.
+
+    Centroids are quantized to ~100 m so nearby clips reuse the same download.
+    """
+    if cache_dir is not None:
+        key = f"{round(center_lat, 3)}_{round(center_lon, 3)}_{radius_m}.pkl"
+        cache_path = cache_dir / key
+        cached = load_cached_network(cache_path)
+        if cached is not None:
+            return cached
+    else:
+        cache_path = None
+
+    try:
+        graph = fetch_road_network(center_lat, center_lon, radius_m=radius_m)
+    except Exception as exc:  # noqa: BLE001 — network/Overpass failures
+        logger.warning(
+            "fetch_road_network(%.4f, %.4f) failed: %s",
+            center_lat,
+            center_lon,
+            exc,
+        )
+        return None
+
+    if cache_path is not None:
+        cache_network(graph, cache_path)
+    return graph