Live NEXRAD / weather-radar tile overlay on the map (storm tracking)

[jensenpat]

Feature: live NEXRAD / weather-radar tile overlay on the map

Follow-on to the common mapping engine + PSK Reporter map (#3565). Add a read-only weather-radar overlay on top of the OSM basemap to track live storms, refreshing every 10–15 min with aggressive timestamped caching. Reusable on any MapView consumer (PSK Reporter map now; AetherModem APRS tab later).

Why it's a clean fit

MapView is already a slippy-tile renderer (EPSG:3857, XYZ {z}/{x}/{y}.png, shared cached QNetworkAccessManager, per-layer opacity). Radar is just a second tile layer above OSM at reduced opacity — minimal new code, no API key on the recommended path.

Providers (deep-research verified)

Primary (US): Iowa Environmental Mesonet (IEM) N0Q base reflectivity

• Latest CONUS composite: https://mesonet.agron.iastate.edu/cache/tile.py/1.0.0/ridge::USCOMP-N0Q-0/{z}/{x}/{y}.png (-0 = moving "latest", short TTL).
• Immutable archived frame: ridge::USCOMP-N0Q-YYYYMMDDHHMM/{z}/{x}/{y}.png (cache forever; use for animation).
• Cache tiers: /cache/tile.py/... = 5-min; /c/tile.py/... = 14-day (prefer /c/ for stable/timestamped names).
• Animation: layer suffix nexrad-n0q-mXXm (XX = 05–55 by 5 → ~11 frames), or WMS-Time …/cgi-bin/wms/nexrad/n0q-t.cgi? (nexrad-n0q-wmst, 5-min steps, archive to 2011).
• Cadence: N0Q regenerated every 5 min, CONUS.
• Attribution: "Radar data: Iowa Environmental Mesonet (IEM), Iowa State University."

Fallback (global): RainViewer (key-less, free)

• Index: GET https://api.rainviewer.com/public/weather-maps.json → host, radar.past[], radar.nowcast[] (each time Unix ts + path like /v2/radar/1609402200).
• Tile URL: {host}{path}/{size}/{z}/{x}/{y}/{color}/{options}.png (size 256/512, color = scheme id, options = {smooth}_{snow}). Max zoom ~7.
• Frame paths embed the timestamp → naturally immutable; only re-fetch the index per refresh.
• Attribution: "Weather radar by RainViewer."

Authoritative (future, not v1): NOAA/NWS

• Public domain, time-enabled, but WMS/ArcGIS-export only — not XYZ tiles → needs a separate WMS GetMap layer. Skip for v1.
• nowCOAST GeoServer WMS 1.3.0 https://nowcoast.noaa.gov/geoserver/observations/weather_radar/ows (layer conus_base_reflectivity_mosaic); ArcGIS ImageServer https://mapservices.weather.noaa.gov/eventdriven/rest/services/radar/radar_base_reflectivity_time/ImageServer. Credit "NOAA/NWS."

Refresh & caching

• NEXRAD precip-mode volume scans complete ~4.5–6 min; IEM 5-min. A 10–15 min client refresh is conservative and compliant.
• Address every frame by explicit UTC timestamp → immutable URL → cache indefinitely in the shared QNetworkDiskCache. Use the "latest"/-0 pointer only for the live tip with a short TTL. Re-fetch only the index/latest pointer on the interval.

Integration points (from codebase scout)

• src/gui/map/MapView.cpp ctor: add a second tile layer after m_map->addItem(new QGVLayerOSM()) — QGVLayerOSM(url) accepts an XYZ template with ${z}/${x}/${y}; set setOpacity(...) + setZValue(5) (above OSM, below m_markerLayer). Reuses the shared NAM + 256 MB disk cache automatically.
• New MapView API: setWeatherOverlay(enabled) / opacity setter (keep it generic + reusable, not PSK-specific).
• src/gui/PskReporterMapDialog.cpp top bar: "Radar" checkbox + opacity slider following the existing Paths-checkbox + AppSettings pattern (keys e.g. RadarOverlayEnabled, RadarOpacity).
• dBZ legend can reuse MapView::setLegend(...).
• New files only if needed: src/gui/map/MapWeatherLayer.{h,cpp} (a QGVLayerTilesOnline/QGVLayerOSM subclass) — required if IEM turns out to be TMS (Y-flipped) or for the RainViewer index→URL builder.

Open questions / pre-build checks

• IEM Y-axis: is tile.py/1.0.0/ TMS (Y-flipped) or XYZ/Google like OSM? Page documents Z/X/Y — verify against QGeoView's loader and flip Y if genuinely TMS.
• RainViewer terms: confirm free-tier redistribution/commercial-use terms for a shipped desktop app; respect ~10-min frame cadence.
• dBZ ramp: source exact NWS standard reflectivity color breakpoints for the legend (not enumerated in verified sources).
• IEM per-timestamp archived-frame availability window via tile.py (WMS-T extent starts 2011; tile-cache vs archive availability TBD).

Proposed scope

• Phase 1: IEM N0Q latest-frame overlay on MapView — toggle + opacity slider + dBZ legend + valid-time label, 10-min refresh, timestamped caching, off by default.
• Phase 2: animation loop (last ~10 frames) + global RainViewer option.

Read-only public data throughout; no API keys on the recommended path.

💻 Generated with Claude Code (Fable 5.0) with architecture by @jensenpat

[aethersdr-agent]

Triage: well-scoped feature, hard-blocked on #3565

Labeled New Feature / GUI / maintainer-review. The research here is thorough and the architecture is sound, so the main triage finding is about sequencing, not feasibility.

Blocker: the mapping engine this builds on isn't on main yet

Every integration point this issue names is introduced by #3565 (feat(gui): common Qt mapping engine + PSK Reporter map), which is currently open / unmerged. Verified against main (9610203c):

• git grep -l "MapView\|QGVLayerOSM\|PskReporterMap" → no matches
• find for *mapview*, *pskreporter*map*, *qgeoview* → nothing
• third_party/QGeoView/ (the vendored LGPL tile engine) → not present
• Only pskreporter reference on main is a log-filename string at src/main.cpp:319

So src/gui/map/MapView.cpp, the shared QNetworkAccessManager + 256 MB QNetworkDiskCache, PskReporterMapDialog.cpp, and MapView::setLegend(...) don't exist to extend until #3565 lands. This work cannot start before #3565 merges — every file/line citation in the issue body refers to #3565's tree, not the current one.

Technical note for whoever implements it: the QGVLayerOSM(url) claim

The issue assumes a radar layer can be added as QGVLayerOSM(url) with an XYZ template. In stock QGeoView, QGVLayerOSM is a fixed subclass of QGVLayerTilesOnline that hardcodes the OSM URL in tilePosToUrl() — its constructor does not take a URL template. So unless #3565's vendored patch adds a URL-accepting ctor, the radar overlay should be the MapWeatherLayer : QGVLayerTilesOnline subclass the issue already proposes as a fallback — that's the correct primary path, not the fallback. Worth confirming against third_party/QGeoView/AETHERSDR-PATCHES.md once #3565 is in.

Pre-build checks that should be resolved before implementation (not reporter questions)

These are the issue's own open items; flagging for the maintainer because they're real and need source verification, not info from the reporter:

1. IEM tile.py/1.0.0/ axis — TMS (Y-flipped) vs XYZ/Google. QGeoView's loader is XYZ; if IEM is TMS the MapWeatherLayer subclass must flip Y. Cheap to verify with a single tile fetch against a known lat/lon.
2. RainViewer redistribution terms for a shipped desktop app (Phase 2) — confirm key-less free-tier commercial/redistribution terms before bundling it.
3. dBZ legend ramp — needs the exact NWS standard reflectivity breakpoints; not enumerated in the cited sources.

Recommendation

• Hold until feat(gui): common Qt mapping engine + PSK Reporter map #3565 merges, then implement Phase 1 only (IEM N0Q latest-frame overlay: toggle + opacity slider + dBZ legend + valid-time label, 10-min refresh, timestamped /c/ caching, off by default). Read-only public data, no API key — clean and low-risk.
• Phase 2 (animation loop + RainViewer global option) as a separate PR after Phase 1, gated on resolving the RainViewer terms.

No reporter follow-up needed — the open questions are implementation-time verifications, not missing information. Recommend aetherclaude-eligible once #3565 is merged, scoped to Phase 1.

---

_{🤖 aethersdr-agent · cost: $1.3538 · model: claude-opus-4-8}