Map and GPU rendering¶
The RF Sentry map is a shared evidence surface for stations, aircraft, satellites, received products, and reference-time context. It uses MapLibre for the basemap/globe and custom retained WebGL layers for high-rate or altitude-aware content.
Ownership and evidence boundary¶
The map is a browser-owned presentation consumer, not a second receiver or
intelligence service. Reuse StationIntelligenceService, FtxMapAdapter,
MapStore, shared station selection, Maidenhead/geodesy and MapReferenceTime.
The main RF Sentry window retains receiver leases, IQ, DSP/decoder and timeshift
ownership; the same-origin map portal owns its presentation surface.
Adapters translate shared facts instead of reparsing callsigns/messages or recomputing receiver locations and distances inside map components. Observed RF geography and regulatory/home geocodes remain separate evidence classes. Best Estimate can refine a grid with a compatible regulatory point but must retain both provenance and disagreement; it never overwrites decoded geography. An addressed endpoint is not a heard station, and relationship distances are endpoint great-circle facts, not modeled propagation paths.
Local regulatory refinement uses FCC RAM address hints and a serialized browser
geocoder, not one SQLite dossier per marker. GeocodeService lazily loads the
relevant local state/shard and caches results by algorithm, generation and
normalized address. PO boxes remain postal/locality context, not residence
points. Station evidence
remains the authority for capture-time location and distance semantics.
Data path¶
flowchart TB
INTEL[Intelligence services] --> DELTA[Entity-keyed deltas]
DELTA --> STORE[Map model partitions]
STORE --> MARK[Stable marker slots]
STORE --> TRAIL[Per-entity trail blocks]
STORE --> ARC[Relationship/arc slots]
MARK --> GPU[Retained typed arrays]
TRAIL --> GPU
ARC --> GPU
GPU --> SUB[Dirty ranges via bufferSubData]
SUB --> GL[Custom WebGL layer]
GL --> ML[MapLibre 2D / Globe]
Updating one aircraft does not rebuild unrelated aircraft or serialize a whole feature collection. Stable slots, explicit version counters, and dirty typed-array ranges replace full-buffer churn. Camera changes update projection uniforms rather than recreating entity geometry.
MapHost lazily loads MapLibre and owns its imperative instance, custom RF and
celestial overlays, projection/picking and camera lifecycle. React owns controls
and selected-entity panels, not per-frame geometry. Core map/runtime/worker assets
are appliance-served; no separate map application server or SDR connection is
required. Retained arrays/buffers and dirty ranges avoid repeated full-history
serialization while keeping selection and camera state stable.
Aircraft rendering¶
The map receives compact current snapshots and position deltas. Marker presentation interpolates between authoritative observations, but only decoded positions enter the retained trail. Labels choose the strongest qualified identity: flight/callsign, registration, another supported identity, then ICAO address.
Aircraft category colors are presentation enrichment. Type-appropriate icons, rotor/propeller/jet effects, altitude stems, and label collision work are GPU or render-loop concerns, not per-frame React updates.
Full retained trails are loaded/rendered for a selected aircraft, for all aircraft when Flight Trails is enabled, and for confidently classified government/military aircraft when Military Paths is enabled. Segment colors encode observed altitude along the route. Missing or invalid positions never become giant connecting polygons; every per-aircraft block has explicit boundaries and primitive topology.
Globe altitude and camera¶
Aircraft and satellites use actual altitude in the globe transform rather than being pasted to the surface. Stems join the surface anchor to the 3D object. Focused zoom solves a bounded camera target using the projected aircraft/ ground volume, requested pitch and bearing. It does not clamp the marker to the screen or alter altitude.
Satellite orbit tracks retain their altitude coordinate; they are not generic surface polylines. Celestial stars are an effectively infinite sphere. Sun, Moon, Earth occlusion, terminator, and replay time share the same astronomical reference model.
Reference-time behavior¶
Live uses incremental entities. Historical windows issue indexed worker queries tagged with the current view generation. A stale 24-hour result cannot apply after the operator returns to Live. Hidden/minimized map presentation suspends geometry updates but ingestion continues; reopening catches up from compact state/version deltas rather than replaying all history.
mapTime.ts maps the active lane's selected IQ monotonic cursor through its
UTC/monotonic clock pair. Live and playing-history references advance from a
monotonic presentation anchor; paused history stays fixed. Unchanged/coalesced
IQ snapshots do not reset that anchor or move an advancing object backward.
Lane, seek, play-state or material clock changes are real boundaries and
re-anchor the view instead of being smoothed away.
Both MapWorkspace temporal scheduling and MapHost rendering use the map
document's ownerDocument.defaultView, not a potentially hidden opener window.
Focus, visibilitychange and pageshow derive the current reference and refresh
orbital samples/countdowns on restoration; they do not replay missed callbacks.
Ingestion/persistence continue while invisible drawing is suspended. Context
restoration rebuilds GL resources from retained content where available.
Existing timing caveat: when no usable selected clock pair exists,
mapReferenceTimeForLane() falls back to browser UTC (subtracting behind-live
elapsed time for history). That is an estimated map reference, not verified
sample-clock capture UTC. The fallback must not become RF timestamp evidence;
this documentation change does not alter that runtime behavior.
Celestial Globe¶
src/map/astronomy.ts uses Astronomy Engine for the shared apparent Sun/Moon
and Earth-orientation frame. Stars, Sun, Moon, terminator and greyline all consume
the same capture/replay reference. Adding a second wall-clock Sun model or
MapLibre light calculation would make the sky and Earth shading disagree.
CelestialOverlay uploads the immutable local HYG catalog into a retained GPU
buffer. Proper motion, Earth rotation and reference-time changes update shader
uniforms rather than rebuilding star geometry. Sun/Moon angular sizes, lunar
phase/libration and analytic Earth occultation come from the same ephemeris;
the Moon's appearance uses the bundled NASA/LRO texture.
Ephemerides refresh at bounded cadence while shader-time rotation supplies display motion. The sky shares the existing map render clock, not a separate React animation loop. Star exposure/backdrop preferences do not rebuild the catalog or change Sun/Moon photometry. Context recovery can re-upload retained catalog/texture content; removal releases owned GL resources.
See asset provenance and updates and operator reference-time behavior.
Layer and clutter policy¶
Independent controls govern aircraft labels, ground identifiers, trails, military paths, satellite paths, weather/advisory layers, celestial sky, and other overlays. Geographic products are not all enabled at once. Broad zooms can reduce label/effect prominence without reducing underlying evidence or update fidelity.
Performance invariants¶
- Live work scales with changed entities and changed trail segments.
- Hidden presentation does not rebuild models.
- Map work cannot lower DSP or waterfall quality.
- Full history remains retained even when it is not rendered.
- Additional stable RAM/VRAM is preferred to repeated allocation and garbage collection.
- Selection and camera state remain stable across incremental updates.
Interactive indexing, geocoding, orbital propagation and rendering use browser workers/RAM/GPU. Only bounded reference-data refresh belongs on the Pi. Map faults and presentation cost must remain isolated from realtime DSP, audio, waterfall, decoders and IQ timeshift. Hidden drawing can pause without lowering underlying RF fidelity or deleting history.
Ledger and qualification¶
docs/roadmap/intelligence-maps.md Phase 9E — Interactive Map records acceptance on
2026-09-09. Later geocoder/map hardening records source-aware publication,
regulatory refinement and pop-out timing corrections; the celestial Globe
extension was separately accepted on 2026-09-30. Those are dated checkpoints,
not fresh live validation from this documentation build.
The offline map is geographic, not a street-navigation map; optional online styles require Internet access, Census address coverage depends on source availability, and satellite RF metadata is curated rather than exhaustive. The Post-9E geographic extensions retain their original roadmap status; current adapters and later Phase 10 work do not silently complete every item.
Implementation anchors: src/map/model.ts, store.ts, ftxAdapter.ts,
MapHost.ts, mapTime.ts, astronomy.ts, overlay/rfOverlay.ts,
overlay/celestialOverlay.ts, geocode/GeocodeService.ts and
src/ui/map/MapWorkspace.tsx. Focused regression references include
mapModel.test.ts, mapFtxAdapter.test.ts, mapGeocode.test.ts,
mapAstronomy.test.ts, mapSatellite.test.ts and celestialOverlay.test.ts.
documentation/architecture/map.md preserves the historical consumer handoff.