====== Speed-warning app & map-matcher ======

A driver-facing feature that shows the current speed limit on the cluster and warns on over-speed —
built **on our own software**, independent of the OEM and of any cloud, as a proof that we can.

===== On the car =====

The dashboard app renders a **speed-limit sign** on the reachable cluster panel ([[displays]]) and a
"SLOW DOWN" warning when the driven speed exceeds the limit. Live speed comes from CAN; position
from GPS.

===== The map-matcher =====

Naively snapping each GPS fix to the nearest road jumps around under bridges, in tunnels, and onto
parallel streets. Instead we use a small **HMM map-matcher** (Newson–Krumm style) that fits the
GPS trace to the road //sequence//:

  * **Road topology** is recovered from **coincident OSM vertices** — roads that share the exact
    same node are connected; a bridge/tunnel that merely crosses does //not// share a node, so it is
    correctly kept unconnected. This alone stops the "jump onto the stacked road" problem.
  * **Emission + transition** scoring (GPS distance, heading, and how far you actually moved by
    odometry) plus **Viterbi backtracking** enforce a consistent path instead of per-fix guessing.
  * The car's **CAN speed** (odometry) and the GPS **Doppler heading** are used as inputs — better
    than position-differencing.

===== Three real-world fixes (validated on a recorded drive) =====

  * **Time-dependent limits.** Some signs are conditional (e.g. //30 km/h on weekdays 07:00–19:00,
    50 otherwise//). OSM encodes this as ''maxspeed:conditional''. We now evaluate the rule against
    the local time, so the displayed limit switches correctly through the day.
  * **Autobahn carriageway flip.** The matcher sometimes snapped to the //opposite// carriageway.
    Root cause turned out to be a **candidate-search bug**, not direction: motorways have long
    segments with vertices hundreds of metres apart, so the correct carriageway was never even
    offered as a candidate. Fixing the spatial index (rasterizing each road's //segments//, not just
    its vertices) plus a one-way direction gate eliminated it.
  * **Tunnel jump-out.** In a tunnel the GPS drifts onto the surface streets above. On this car the
    reported GPS //accuracy does not degrade// in tunnels, so we cannot rely on it. Instead we use
    the OSM ''tunnel'' flag: when the road we are on enters a tunnel we **coast along it on CAN
    odometry** and stop trusting the drifting GPS until it re-acquires at the exit. Because the
    coast is only triggered inside tunnels, open-road matching is unchanged.

The result on a real ~700 km drive: carriageway flips essentially eliminated, tunnels held, and the
conditional 30/50 zone displayed correctly for the time of day.