# 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. - **Per-video metadata (JSON)** — vehicle GPS track per video; takes priority over OSM for direction inference. **Persists in the SQLite database**, so you only pick the file once — every subsequent app start hydrates it automatically. Cleared only by the **Clear** button on the Per-video metadata row, or by **Reset DB**. 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). --- ## Single-video focus mode When you want to inspect / clean one video's worth of data in isolation: - **Tap that video's metadata polyline on the map**, or - **Leave exactly one video checked in the Filters panel**. Either path triggers focus mode: - Other videos' metadata polylines are hidden — only the focused track renders. - OSM roads are spatially filtered to those within ~75 m of the focused track (cheap spatial-hash buffer; recomputed on each switch). - Clicking the metadata line again, or unchecking the lone video filter, restores the full view. Focus mode also unlocks the bulk OSM road tools (multi-select / hide / merge — see **OSM road editing**). Selection and hidden state are session-scoped: they reset whenever you exit OSM edit mode or change the focused video. --- ## 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 ### Modes - **OSM tools…** modal — generate roads for the visible bbox or for a buffer around imported assets (Overpass), import existing GeoJSON, export current roads, prune small road classes. - **Edit OSM roads** button — toggles OSM edit mode. While on, every other layer is dimmed and only OSM roads are interactive. - **Magnifier** button — cursor-following circular lens that zooms +3 levels around the cursor; renders satellite + OSM cyan + dashed-green metadata + red asset dots. Toggle on, hover anywhere, then ESC or click again to exit. - **Lane offset (m)** — controls the parallel offset used by snap-to-road. Range 0.1–30 m. ### Two click models OSM edit mode behaves differently depending on whether a single video is focused (see **Single-video focus mode**): - **Non-focus** — click a road to enter the legacy single-road vertex editor (the only road remains visible; vertex pins appear). One road at a time. - **Focus mode** — click a road to **toggle multi-select** (yellow highlight). All roads stay visible. When the selection narrows to **exactly one** road, the vertex editor automatically engages on it (Flip / Simplify / Delete this road / Ignore for snap appear inline). Click the road again to drop back to multi-select. ### Modifying a road's vertices (single road active) - **Drag a yellow `•` pin** — moves that vertex. Saved immediately. - **Click a yellow `+` ghost pin** between two vertices — inserts a new vertex at that midpoint. - **Flip direction** — cycles `oneway` through forward (`1`) → reverse (`-1`) → undirected (`0`). - Vertex handles render at z ≥ 14; zoom in if you don't see them. ### Deleting vertices **A. Surgical — Shift-click + Del** 1. **Shift-click** a vertex pin → turns red with `✕`. Repeat to mark more. 2. Press **Del** → all marked vertices removed in one shot. 3. **Clear marks** unselects without deleting. Shift-click a marked vertex to unmark. 4. The road must keep ≥ 2 vertices. **B. Sweeping — Simplify by tolerance** 1. **Simplify (m)** slider (0.5–20 m, default 2 m). Higher = more aggressive. 2. Click **Simplify this road** → Douglas-Peucker on the polyline. 3. Status bar reports `before → after` vertex counts. ### Bulk road tools (focus mode only) A "Bulk road tools — focus: