# KML Map Tool — User Guide

Tauri 2 desktop app for reviewing, correcting and exporting fixed-asset / range-asset annotations produced by the dashcam labelling pipeline. Replaces the legacy FastAPI + Leaflet tools.

---

## Quick start

1. **Login** — pick or create a user when the app opens. The username is stamped on every audit-log entry.
2. **Import data** — top-left **Import…** button:
   - **Fixed assets (JSON)** — point assets like streetlights, signs.
   - **Range assets (JSON)** — linear assets with start / mid / end (e.g., crash barriers).
   - **KML scope polygon** — defines which assets are "in scope". Points outside the polygon are hidden by default.
   - **OSM roads (GeoJSON)** — imported road network for snapping / direction lookups.
   - **Metadata polyline (KML)** — vehicle GPS track from the source video; takes priority over OSM for direction inference.
3. The map auto-centers on the first imported asset. Pan / zoom triggers viewport-bounded fetches (debounced) to keep the deck.gl rendering snappy.

---

## Map basics

- **Basemaps** — Basemap selector at the top. Default: **Google Satellite (deep zoom)** which uses Google Earth tiles and goes deeper than the regular Google Satellite layer (helpful at z≥22 to see streetlights / road surface).
- **Compare mode** — secondary basemap layered side-by-side via the Compare toggle.
- **Layer toggles** — Fixed / Range / OSM / Scope / Metadata visibility.
- **Filters panel** (left side) — narrow the visible set by Asset type, Side, Video, Asset name. Counts update live with the current viewport.
- **Show out-of-scope / Show deleted** — toggles to expose hidden assets for inspection or restore.

---

## Selecting and editing one asset

- **Click an asset** to select. The right-side **Selected** panel shows type, name, row_id, video, side. By default an image popup opens (toggle in Settings).
- **Drag the pin** on the map to move the asset. Range assets show **S / M / E** (start / mid / end) draggable pins.
- **`[` / `]`** keyboard shortcuts step through the visible filtered list.
- **Reset to original** — restores the lat/lng captured at first import. Useful if a snap or drag went wrong.
- **Snap to nearest road** — shifts the asset to the OSM road centerline or its lane-offset side. Direction priority: **metadata polyline → OSM `oneway` → position-based fallback**. Idempotent above 0.5 m drift.
- **Side: Left / Right** — toggle without moving the geometry.
- **Rename class…** — change `asset_name` (e.g. fix a mis-classified label). Pulls suggestions from `classes.txt`.
- **Delete** — soft-delete (recoverable via Restore or Undo).
- **Mark as anchor** — flag for the bulk **Distribute correction** flow (see below).

---

## Lasso selection (for bulk operations)

- **Start lasso** then pick a shape: **circle**, **rect**, or **polygon**.
- Polygon mode: click to add vertices, click near the first vertex (gold ring) or double-click to close. Pan / zoom while drawing — vertices stay anchored to the map.
- **ESC** cancels at any time and clears the lingering polygon panel.
- Once selected, you get bulk actions: **In-scope / Out-of-scope / Auto / Delete / Restore / Rename / Set Left / Set Right / Reset to original / Clear links**.
- Polygon-only extras: **Auto-link L↔R**, **Auto-link by video**, **Auto-link nearest** (see Pair linking).

---

## Cross-side / cross-video pair linking

Common situation: one physical asset (e.g., a median streetlight) is captured in two videos (LHS and RHS) and shows up as two near-duplicate points. Pair linking marks them as the same physical thing without deleting either.

- **Auto-link** — draw a polygon lasso over the area, then pick the matching strategy in the polygon panel:
  - **L↔R**: requires assets to have a `side` label; pairs Left with Right.
  - **By video**: pairs across the two largest video buckets (use when both videos see the same poles from opposite sides).
  - **Nearest**: pairs by proximity regardless of side or video. Use when `video_name` is `Not available` / NA.
- **Pair max** slider (2–60 m, default 30 m) — the maximum allowed pair distance. Independent from the duplicate epsilon.
- Manual links override auto-links:
  - **Right-click an asset → right-click another** — locks them as a pair (pink line). The "anchor" asset gets a status-bar prompt.
  - **Right-click two already-linked assets** — unlinks them.
- **Click a link line** to select it; press **Delete** to clear that link.
- Link colors: **pink = locked manual link** (survives Auto-link re-runs); **blue = auto link** (replaceable on the next re-run).
- Unlink an asset directly via **Unlink** button on the selected panel.
- After fixing a few wrong pairs manually, click **Auto-link** again — locked links stay; orphaned partners get re-matched among the remaining unlocked candidates.

---

## Duplicates

- **Find duplicates** — scans the *currently visible viewport* for clusters of points within the chosen ε (metres). Zoom out to widen the search; zoom out fully to scan everywhere.
- **Cross-video only** — restrict matches to pairs from different videos.
- For each cluster you can **Delete losers** (keep one, delete the rest) or **Move losers out-of-scope**.

---

## Distribute correction (GPS bias fix)

When the GPS is uniformly off for a whole video / stretch, you don't want to drag every streetlight by hand.

1. **Filter** the map to the affected slice (e.g., `video=X`, `name=Streetlight`).
2. Click an asset → **Mark as anchor** (gold ring appears).
3. **Drag** the gold-ringed asset to where it should be. Repeat for as many anchors as you like.
4. Click **Distribute correction** in the yellow panel that appears at the top of the actions sidebar.
   - **1 anchor** → all visible assets shift by the same Δlat/Δlng (uniform).
   - **2+ anchors** → row_id-sorted piecewise linear interpolation between consecutive anchors. Assets *outside* the first–last anchor span are not touched.
5. **Undo** in Recent actions reverts the entire distribution in one step.

Range assets (start / mid / end) translate as a rigid body — all three vertices shift by the same Δ.

---

## OSM road editing

- **OSM tools…** modal — generate roads for the visible bbox (Overpass), import existing GeoJSON, export current roads, prune small road classes.
- **OSM edit mode** — drag any road's vertex to refine the centerline. Markers are gated by zoom ≥ 14 and capped at 80 vertices / 40 ghost dots per viewport so the map stays responsive.
- **Flip road direction** — cycle a road's `oneway` between 0 / 1 / -1 when it's wrong.
- **Lane offset (m)** — controls the parallel offset used by snap-to-road. Range 0.1–30 m.

---

## Snap-to-road

- **Per-asset** — Snap to nearest road on the selected panel.
- **Bulk visible** — snap every visible fixed asset to the nearest road (50 m max).
- **Snap by video** — snap every asset (fixed + range) for a given video.
- Range assets snap all three vertices independently (not just mid).
- Direction priority: **metadata polyline > OSM `oneway` > position-based**.

---

## Centerline override

Some asset classes (expansion joint, vms gantry) belong on the road centerline, not the LHS/RHS offset. Settings → **Snap to centerline (instead of offset lane)** lets you tick those class names.

---

## Settings ⚙ modal

- **Image popup**
  - On / off (when off, marker pins still appear but no image opens on click).
  - Width: S / M / L / XL.
  - Aspect ratio: 16:9 / 4:3 / 3:2 / 1:1.
- **Snap to centerline names** — list of asset_names that should snap to centerline.
- **Image folder (offline)** — a local folder used to resolve `image_path` URLs to disk (HTTPS URLs always pass through unchanged).

---

## Export

The **Export data…** button writes every non-deleted asset in one of four formats:

- **`.json` Source JSON** — round-trippable. Same shape `import_fixed_assets` and `import_range_assets` accept (separate `fixed` and `range` arrays). Includes `image_path*`, `side`, `deleted`, etc.
- **`.geojson`** — FeatureCollection. Points for fixed assets, LineStrings for ranges. Properties include `image_path*`, `link_pair_id`, `link_locked`, `in_scope`, `modified`.
- **`.kml`** — Placemarks for GIS tools. Includes name, description, geometry.
- **`.csv`** — full row dump for spreadsheets / external pipelines.

OSM roads can be exported separately via **OSM tools… → Export current roads** (writes GeoJSON with `name`, `highway`, `oneway` preserved).

---

## Keyboard shortcuts

| Key | Action |
|---|---|
| `[` / `]` | Step prev / next asset in the filtered list |
| `ESC` | Cancel: lasso / link-pick / draw-road / road-edit / image popup |
| `Delete` / `Backspace` | Unlink the currently-selected link line |

---

## Undo / Redo

Every state-changing action writes an audit row. The **Recent actions** panel shows the last N. Click **Undo** on any row to revert; **Redo** on a previously undone row replays it. Multi-asset operations (bulk delete, distribute, auto-link) revert as a single atomic step. Road edits (OSM vertex drag, create / delete / flip) are not audited.

---

## Performance notes

- Viewport-bounded fetch: `assets` only contains rows inside the current map bbox, debounced ~400 ms after pan / zoom.
- Bulk operations use 500-id chunks to stay safely under SQLite's 999-bind-param ceiling.
- Auto-link / Distribute over very large viewports may take several seconds at 50k+ rows; prefer narrowing with filters or zoom first.
- Image prefetching warms the previous / next two thumbnails so `[` / `]` navigation feels instant.

---

## Troubleshooting

- **No assets visible after import** — check Filters panel (especially Videos), Show out-of-scope toggle, and whether a stale KML scope from a previous import is filtering everything out.
- **Streetlights not visible on satellite** — switch to **Google Satellite (deep zoom)** basemap and zoom to z≥22.
- **Snap moves assets to the wrong side** — load the metadata polyline (gives true vehicle heading), or fix the OSM road's `oneway` direction.
- **Re-importing wipes my edits** — re-import preserves rows where `modified=1` (manual moves) and rows the user deleted; only `modified=0` geometry is re-stamped from source. If you need a fresh start, use **Reset DB** in the Data section first.