map and chainage calculation

README.md

@@ -166,6 +166,45 @@ pass back. All Phase 3 routes require `Authorization: Bearer <token>`.
 - `POST /api/videos/:id/push`        — body = export doc + `verify_time_ms`; replace annotations,
                                        mark `verified`, record verifier + time, clear claim
 
+### Map / GPS / road_type / chainage
+
+The server image bundles exiftool; a serial background sweep extracts each video's GPS
+track (`gps_status`: `pending → ok | none | error`). The raw track is immutable —
+a kept "Viterbi" correction lives beside it and is preferred by the map + chainage.
+`road_type` + the four chainage values are injected into every claim/export doc and
+re-stamped on push (server-authoritative). **Every annotation** additionally gets its
+**frame-exact** `lat`/`lon`/`chainage_m`/`sr_chainage_m` (range annotations also
+`end_*`): frame 15 of a 30 fps video is t = 0.5 s — halfway between two 1 Hz GPS
+samples — so it gets the halfway position/chainage, not a second/video boundary.
+Distances are WGS84-ellipsoidal (no spherical bias); calibration anchors persist in
+`chainage_calibrations` so this works at any time after a recompute.
+
+- `GET  /api/projects/:id/map`         — per-video map rows: track (≤400 pts), status,
+                                         road_type, chainage, `gps_status` (member/admin)
+- `GET  /api/projects/:id/tracks.kml?token=` — all tracks as KML LineStrings colored by
+                                         status + calibration points (Google Earth)
+- `POST /api/videos/:id/gps/rescan`    — re-queue a video for the exiftool sweep (admin)
+- `POST /api/projects/:id/gps/rescan_all` — re-queue every video (admin; background)
+- `POST /api/videos/:id/gps/correct`   `{action: preview|keep|discard}` — spike smoothing +
+                                         missing-start stitch from the previous file (by GPS
+                                         timestamp, duration-guarded); the scan sweep applies
+                                         the same pipeline automatically as 'auto' (raw never
+                                         changes; discard blocks re-auto-correction) (admin)
+- `GET/POST /api/projects/:id/road_types`      — list / replace label set (`{names}`, admin)
+- `POST /api/projects/:id/road_type_assign`    `{video_ids, road_type}` — bulk-assign ('' clears, admin)
+- `GET/POST /api/projects/:id/chainage/points` — client calibration points (POST admin:
+                                         `{lat, lon, chainage_m, note?, road_type?}`)
+- `POST /api/projects/:id/chainage/points/bulk` `{points: […]}` — transactional bulk insert;
+                                         the dashboard's **KML import** uses this (placemark
+                                         names like `12+400` or `12.4` become chainage) (admin)
+- `DELETE /api/chainage/points/:id`    — remove a point (admin)
+- `POST /api/projects/:id/chainage/recompute`  `{video_ids, road_type}` — order the videos into a
+                                         route, snap the points, distribute the client-vs-GPS error
+                                         piecewise-linearly; writes `chainage_*` (client) +
+                                         `sr_chainage_*` (measured, immutable) + `route_seq` (admin)
+- `POST /api/projects/:id/chainage/quick`      `{video_ids, start_m, end_m, road_type}` — the
+                                         two-point case: points at the route ends + same recompute (admin)
+
 ### Env
 
 | var           | default                                  | meaning                                            |