Map overhaul: terrain-aware RF tools (Coverage / LOS / Scan), WASM ITM, donut clusters, 3D terrain

[SimmerV]

Summary

Large, multi-phase upgrade to the Map page. Adds a full terrain-aware RF toolbox powered by NTIA's Longley-Rice ITM compiled to WebAssembly, introduces WebGL donut clusters, ships 3D terrain with a real Tilezen DEM under the hood, and polishes dozens of smaller map UX issues.

Highlights

• Coverage prediction tool — terrain-aware raster paint using NTIA ITM v1.4 (vendored + compiled to WASM). 200 km max radius, up to 2048² output at "Survey" detail, iso-margin contours, visibility rays, asymmetric RX profile (different hardware / antenna / height on the receive side), GeoJSON + KML export.
• Line-of-Sight tool — interactive elevation profile with Fresnel zone, 3D LOS tube with obstruction pylons, ITM path-loss alongside pure geometric analysis, asymmetric endpoints with per-side hardware.
• Scan tool — "best neighbors" ranking within 200 km, ITM-backed per-candidate path loss. Standalone link-budget config (independent from Coverage) with TX hardware/antenna/height, RX hardware/antenna, modem preset, environment clutter, and chipset-aware sensitivity. Draggable cyan origin pin repositions + recomputes on drop. Left-click class pills filter the list, right-click toggles map visibility (Blocked hidden by default). Pinned origin row at top of the results returns the map to the pre-scan view after flying to a target.
• Traceroute tool — full implementation in place but currently parked behind a "Coming soon" label in the tools drawer while the UX is polished. All underlying compute and wiring stays in the branch for future enablement.
• 3D terrain — Mapbox raster-dem integration with exaggeration slider and sky layer.
• Donut cluster markers — WebGL custom layer showing online/offline ratio per cluster, terrain-aware positioning, auto-spiderfy for co-located nodes.
• Bulk-DEM fetch via AWS Tilezen (USGS 3DEP in US, SRTM global) with Mapbox terrain-rgb fallback. Provider-independent — the compute layer no longer depends on the map viewport.

New infrastructure

• NTIA ITM (Longley-Rice) v1.4 vendored + compiled to WASM with a typed TS wrapper (frontend/wasm/itm/, itm.ts, itm.test.ts — physics-validated against published reference cases).
• Web Worker pool for parallel ITM compute (~5.8× on 8 cores), per-slice progress + user Cancel.
• DEM abstraction (terrainDEM.ts, terrainRgb.ts, viewshed.ts) with R2 viewshed and 4/3-earth refraction.
• Coverage raster layer (coverageRaster.ts) with marching-squares contour extraction (coverageContours.ts) and margin-gated visibility rays (coverageRays.ts).
• LOS tube custom layer (losTubeLayer.ts) with clearance-colored segments and obstruction pylons.
• Tools drawer system (MapToolsDrawer.tsx) — global tool discovery; greyed tools auto-open the 3D terrain setup.

UX polish

• Search bar with autocomplete, URL state sync, keyboard navigation.
• Role-based node colors + filter pills (role + channel) on the quick-controls bar.
• Magenta→cyan palette migration across tool overlays.
• Mesh health widget and telemetry sparklines in the details panel.
• Per-link highlight on neighbor-row hover; curved arcs for mutual links, dash patterns by link type.
• Fixed-size Map Settings panel with collapsible sections (Appearance / 3D Terrain / My Node / Export).
• Coverage panel: inline RX-asymmetry pill toggles the gear popover; Environment as button group; click-to-edit origin coords; "Reset to handheld" default.
• Scan panel: independent gear popover with full link-budget config; click on the map (or anywhere outside the panel) closes the popover without exiting the tool.
• Legend: new Cluster-ring and Selected-node entries; directionally-clearer link labels.

Accuracy fixes landed along the way

• queryTerrainElevation({ exaggerated: false }) across every call site — terrain readings are now real MSL metres regardless of exaggeration slider or zoom level.
• Tilezen 3DEP replaces Mapbox terrain-rgb as the primary DEM (≈10 m native vs ≈30 m, with cleaner bare-earth in forested regions).
• scannedPixels field added to CoverageResult so the "no terrain data" diagnostic works at all Detail tiers (was hard-coded to 256²).
• Chipset-aware RX sensitivity (SX1276 boards incur a +2 dB sensitivity penalty vs. SX1262).

Performance

• Donut cluster rebuilds debounced (120 ms trailing) against moveend.
• Coverage raster uploads via Blob URL instead of data URL (skips ~100–200 ms base64 encoding at 2048²).
• Tool-close path reclaims the Survey-resolution GPU texture.
• Single-pass multi-threshold marching squares for contour extraction.
• Cursor-elevation readout suppressed during marker drag so the scan/coverage origin pin tracks the cursor without stutter.
• Comment cleanup pass across 40+ map files (−1,714 net lines).

[Copilot]

Pull request overview

Large Map page overhaul that adds terrain-aware RF analysis (Coverage / LOS / Scan) backed by NTIA Longley‑Rice ITM compiled to WebAssembly, plus new map UI systems (tools drawer, search, quick filters), cluster rendering, and 3D-terrain plumbing.

Changes:

• Added an ITM v1.4 WASM build pipeline (vendor fetch, emcc build, Docker builder) and a typed TS wrapper + vitest correctness suite.
• Implemented new terrain/DEM sampling + RF analysis modules (LOS, viewshed, coverage raster/contours/rays, scan ranking) and supporting workers/pool.
• Introduced multiple new map UI components (tools drawer, panels, search, quick controls, telemetry sparklines) and cluster donut rendering layers.

Reviewed changes

Copilot reviewed 53 out of 57 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
frontend/wasm/itm/shim.h	Emscripten export shim for upstream ITM symbols
frontend/wasm/itm/fetch-vendor.sh	Script to clone pinned NTIA/itm and normalize sources for emcc
frontend/wasm/itm/build.sh	emcc build script producing single-file JS + .d.ts
frontend/wasm/itm/README.md	Documentation for the WASM build, rationale, and validation plan
frontend/wasm/itm/Dockerfile	Self-contained Docker image to build/copy WASM artifacts
frontend/wasm/itm/.gitignore	Ignore vendored sources and intermediate outputs
frontend/src/slices/apiSlice.ts	Adds per-node telemetry RTK Query endpoint/hook
frontend/src/pages/map/viewshed.ts	Per-pixel viewshed computation + knife-edge loss helper
frontend/src/pages/map/utils.ts	Adds role colors + filtered GeoJSON builder + cluster layer toggles
frontend/src/pages/map/types.ts	Expands shared map types and details payload shape
frontend/src/pages/map/terrainDEM.ts	DEM sampling/bounds/downsample helpers for worker compute
frontend/src/pages/map/storage.ts	Persists new 3D terrain settings keys; style URL helper tweak
frontend/src/pages/map/scanAnalysis.ts	Main-thread “best neighbors” scan analysis + GeoJSON export
frontend/src/pages/map/pathAnalysis.ts	Traceroute path extraction between two nodes
frontend/src/pages/map/losTubeLayer.ts	Mapbox custom layer for 3D LOS tube + obstruction pylons
frontend/src/pages/map/losAnalysis.ts	Geometric LOS + Fresnel + knife-edge loss analysis
frontend/src/pages/map/linkFeatures.ts	Link feature generation (neighbors/traceroutes) + ID normalization helper
frontend/src/pages/map/itm.ts	Lazy-loaded WASM wrapper + context pooling for hot loops
frontend/src/pages/map/itm.test.ts	Vitest correctness suite for WASM ITM (skips when not built)
frontend/src/pages/map/detailsHtml.ts	Removed legacy HTML-string details renderer
frontend/src/pages/map/detailsDom.ts	Removed legacy DOM manipulation details panel helpers
frontend/src/pages/map/coverageWorkerPool.ts	Worker pool to parallelize coverage slicing
frontend/src/pages/map/coverageSliceWorker.ts	Worker entry: per-slice raster compute using ITM context
frontend/src/pages/map/coverageRays.ts	Visibility ray extraction constrained by viewshed + margin
frontend/src/pages/map/coverageRaster.ts	ITM-backed per-pixel raster renderer (alloc-minimized hot loop)
frontend/src/pages/map/coverageContours.ts	Marching-squares contour extraction over margin grid
frontend/src/pages/map/coverageAnalysis.ts	Shared coverage presets/constants + link budget helpers
frontend/src/pages/map/clusterMarkers.ts	HTML donut markers for clusters (visual overlay)
frontend/src/pages/map/clusterIcons.ts	Pre-rendered donut sprite images + Mapbox expressions
frontend/src/pages/map/clusterDonutLayer.ts	WebGL custom layer for terrain-aware donut clusters
frontend/src/pages/map/TelemetrySection.tsx	Node telemetry sparklines section using per-node telemetry query
frontend/src/pages/map/Sparkline.tsx	Inline SVG sparkline component
frontend/src/pages/map/PathHopList.tsx	Hop list rendering for traceroute paths
frontend/src/pages/map/MapTraceroutePanel.tsx	UI panel for traceroute paths between nodes
frontend/src/pages/map/MapToolsDrawer.tsx	Tools drawer UI + tool gating/coming-soon behaviors
frontend/src/pages/map/MapSearchBar.tsx	Search/autocomplete UI with keyboard navigation
frontend/src/pages/map/MapQuickControls.tsx	Bottom pill filters (days/links/clustering/role/channel)
frontend/src/pages/map/MapLosPanel.tsx	LOS analysis panel UI with endpoint configs + profile
frontend/src/pages/map/MapLegend.tsx	Legend restyle + new cluster ring entry
frontend/src/pages/map/MapHealthWidget.tsx	Mesh “health” widget (counts/avg SNR/diameter)
frontend/src/pages/map/FilterDropup.tsx	Portal-based pill dropup component
frontend/src/pages/map/ElevationProfile.tsx	SVG elevation profile with hover tooltip + Fresnel visualization
frontend/src/index.css	Tailwind v4 theming + new utility CSS/animations + map control tweaks
frontend/src/generated/itm/itm.d.ts	Placeholder TS types for generated WASM module import
frontend/src/generated/itm/.gitignore	Ignore generated outputs while keeping placeholders checked-in
frontend/src/components/Menu.tsx	Overlay-mode nav behavior for map full-bleed layout
frontend/src/components/Layout.tsx	Uses Menu overlay mode on map; adjusts left padding logic
frontend/package.json	Adds build:wasm script to build/copy ITM artifacts
frontend/index.html	Adds viewport-fit=cover + safe-area padding

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.