Files
gods-eye-view/src/data/firmsHeatmap.js
T
Bilawal Sidhu b6da93b8ac release: v0.1.0 — one-click install, keyless boot, in-app Provider Settings (#142)
The first formal release.

- One-click install via Pinokio; keyless boot lands on a live Esri World
  Imagery satellite globe with keyless terrain, with automatic OSM fallback
  and graceful degradation when terrain is unavailable.
- Provider Settings (the POWER UP panel): add, replace, or remove API keys
  inside the app; credential files made owner-only before any secret is
  written; external keys shown read-only; the panel refuses shared or proxied
  servers.
- Keyless capability responses for the optional HUD summary and place search.
- Aircraft-identity voice answers cover operator, type, and route, and say so
  plainly when enrichment is unavailable.
- README rewritten keyless-first; concise 0.1.0 changelog section; CI
  workflow included.

Gates: 2,672 unit tests pass / 0 fail, build clean, tracking regression
108/108, map-source tray QA pass, setup doctor ready.
2026-08-31 17:49:45 -05:00

1608 lines
62 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import * as Cesium from 'cesium';
import { governorRequestRender } from '../renderGovernor.js';
import {
registerSpriteCollection,
restoreSpriteOrder,
restoreSpriteOrderOnEnable,
} from './spriteOrder.js';
import {
clearSelectedEntityContextForLayer,
getContextStore,
registerEntityContext,
selectEntityContext,
} from './contextStore.js';
import {
isOwnedByOtherLayer,
registerPickOwner,
resolvePickId,
unregisterPickOwner,
} from './pickRegistry.js';
import { adaptFirmsRecords } from './firmsAdapt.js';
import { fireAnchorHeight, warmFireAnchorFloors } from './fireAnchors.js';
import { horizonOccluder } from './iconOrientation.js';
import {
accentForSeverity,
fireDetectionKey,
FIRMS_AMBIENT_COHORT_LIMIT,
FIRMS_OVERLAY_SOURCE_ID,
satelliteShortName,
} from './firmsLabels.js';
import {
clearOverlaySource,
hitTestWorldOverlay,
setOverlayEntries,
setOverlaySourceVisible,
} from '../overlays/worldOverlay.js';
import { requestWorldFocus } from '../worldFocus.js';
/** Same-origin live-fires proxy (vite.config.js firmsProxy — key stays server-side). */
const FIRMS_API_URL = '/api/firms';
/** Client poll interval; the proxy's 30 min TTL is what guards upstream quota. */
const REFRESH_INTERVAL_MS = 600_000;
/**
* LOD bands keyed by camera height. `cells` bands render aggregated
* ground-clamped heat rectangles; `detections` bands (< ~750km plus the
* local band) render individual fire detections as glow-sprite billboards.
* Labels in every band go through the shared screen-space greedy declutter
* (hard cap MAX_AMBIENT_LABELS) — there are no per-band label knobs.
*/
const LOD_LEVELS = [
{ id: 'global', minHeight: 9000000, mode: 'cells', gridDegrees: 2.0, maxCells: 1800, labelDistance: 12000000 },
{ id: 'regional', minHeight: 3000000, mode: 'cells', gridDegrees: 1.0, maxCells: 3600, labelDistance: 8500000 },
{ id: 'local', minHeight: 750000, mode: 'detections', maxDetections: 2500, labelDistance: 4500000 },
{ id: 'close', minHeight: 0, mode: 'detections', maxDetections: 3000, labelDistance: 1800000 },
];
const LOD_CHECK_MS = 650;
/** +/-10% hysteresis on LOD band edges so slow zooms don't thrash rebuilds. */
const LOD_HYSTERESIS = 0.1;
/** Padding fraction applied to the camera view rectangle before clipping. */
const VIEW_PADDING = 0.3;
/** Number of top-FRP detections registered in the shared context store. */
const CONTEXT_TOP_N = 50;
/** Hard cap on ambient (non-selected) labels, regardless of zoom/density. */
const MAX_AMBIENT_LABELS = FIRMS_AMBIENT_COHORT_LIMIT;
/** Min screen-space separation between accepted labels, in CSS pixels. */
const LABEL_MIN_SEP_PX = 150;
/** Candidates projecting outside the canvas by more than this are skipped. */
const LABEL_VIEW_MARGIN_PX = 16;
/**
* Anchors below this height get a separate LIFTED point for occlusion tests
* (never for rendering). Mirrors the flights layer's `cullPosition` idiom
* (`renderAltitudeM < 10` → test at 12 m): `fireAnchorHeight` is ground floor
* + lift, and in negative-geoid coastal regions that lands a few tens of
* metres BELOW the WGS84 ellipsoid — EllipsoidalOccluder then judges such a
* point "beyond the horizon" while its true-surface neighbours stay visible,
* so near-limb fires would blink out for a datum reason.
*/
const CULL_LIFT_THRESHOLD_M = 10;
/** Height of the lifted occlusion-test point (flights uses the same 12 m). */
const CULL_LIFT_M = 12;
/** Color stops shared by cell heat fills and detection glow sprites. */
const DETECTION_COLOR_STOPS = [
{ name: 'red', color: Cesium.Color.RED },
{ name: 'orange', color: Cesium.Color.ORANGE },
{ name: 'yellow', color: Cesium.Color.YELLOW },
];
/** Pre-baked radial-glow sprites keyed by `<colorStop>:<sizeBucket>`. */
const glowSpriteCache = new Map();
const scratchViewRect = new Cesium.Rectangle();
const scratchCenterA = new Cesium.Cartographic();
const scratchCenterB = new Cesium.Cartographic();
const scratchWindowCoord = new Cesium.Cartesian2();
/**
* Map one internal fire record (firmsAdapt.js shape) to a plain JSON-safe
* analyst record (analyst query engine seam). Pure — no Cesium types.
* Missing/unknown fields are null, never NaN/undefined. The id reuses the
* layer's FIRE-##### pick-id convention (index keys pick ids and
* context-store ids, so the two stay consistent).
* @param {Object|null|undefined} fire - Internal fire record.
* @returns {{id: string, lat: number|null, lon: number|null, frp: number|null,
* confidence: number|null, satellite: string|null, acqTime: number|null}}
*/
export function mapAnalystRecord(fire) {
const num = (v) => (Number.isFinite(v) ? v : null);
const text = (v) => { const t = String(v ?? '').trim(); return t || null; };
return {
id: `FIRE-${String(fire?.index ?? 0).padStart(5, '0')}`,
lat: num(fire?.lat),
lon: num(fire?.lon),
frp: num(fire?.frp),
confidence: num(fire?.confidence), // normalized 0..1 (firmsAdapt.normalizeConfidence)
satellite: text(fire?.satellite) || text(fire?.sensor),
acqTime: Number.isFinite(fire?.acqMs) && fire.acqMs > 0 ? fire.acqMs : null, // epoch ms; 0 = unparseable → null
};
}
export function createFirmsHeatmapLayer({
id,
name,
icon = '▲',
source = 'NASA FIRMS',
overlayHost = {
setEntries: setOverlayEntries,
setVisible: setOverlaySourceVisible,
clearSource: clearOverlaySource,
hitTest: hitTestWorldOverlay,
},
screenSpaceEventHandlerFactory = (viewer) => (
new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas)
),
}) {
let _viewer = null;
let _dataSource = null;
let _billboards = null;
let _enabled = false;
let _destroyed = false;
let _loading = false;
/** True when the proxy answered 503 {error:'no_key'} — FIRMS_MAP_KEY unset. */
let _keyRequired = false;
/** True when the proxy served a cached payload past TTL (upstream failing). */
let _stale = false;
/** Surfaced error string when the live fetch failed outright. */
let _error = null;
let _fires = [];
let _firesByFrp = [];
let _count = 0;
let _cellCount = 0;
let _lastUpdate = null;
let _currentLodId = null;
let _currentLodIndex = -1;
let _lastViewRect = null;
let _preRenderRemover = null;
let _moveEndSettleRemover = null;
let _lastLodCheck = 0;
let _contextIds = new Set();
let _clickHandler = null;
let _moveEndRemover = null;
let _selectedFire = null;
/** Priority-ordered label candidates from the last rebuild (detections or cells). */
let _labelCandidates = [];
let _labelLodDistance = 0;
/** pick id string -> fire record, for the currently rendered sprites. */
const _pickIndexById = new Map();
/** Actionable card id -> current detection record painted for that id. */
const _fireByCardId = new Map();
/**
* Occlusion-test anchors index-aligned with the billboard collection (the
* collection is cleared and refilled in one ordered pass per rebuild, and
* nothing else adds to it). Lifted where the render anchor sits at/below
* the ellipsoid — see {@link fireCullPosition}.
* @type {Array<Cesium.Cartesian3>}
*/
const _cullPositions = [];
/**
* gridDegrees -> heat-sorted full cell list. The full-grid aggregation is
* viewport-independent but walks every detection (~200k live), so it is
* computed once per grid size per data refresh; renders only clip + cap
* (field-test round 1: intermediate-zoom chug during LOD rebuilds).
* @type {Map<number, Array<Object>>}
*/
const _cellCacheByGrid = new Map();
/** Camera idle snapshot so the throttled LOD check is ~free when parked. */
let _camSnapValid = false;
const _camPos = new Cesium.Cartesian3();
const _camDir = new Cesium.Cartesian3();
return {
id,
name,
icon,
source,
// Live layer: the manager calls update() every 10 minutes while enabled,
// which refetches through the /api/firms proxy (the proxy's 30 min TTL —
// not this interval — is what protects the upstream FIRMS quota).
updateInterval: REFRESH_INTERVAL_MS,
init(viewer) {
if (_destroyed) return;
_viewer = viewer;
_dataSource = new Cesium.CustomDataSource(id);
_dataSource.show = false;
viewer.dataSources.add(_dataSource);
},
async enable(viewer) {
if (_destroyed) return;
_enabled = true;
_viewer = viewer;
if (!_dataSource) this.init(viewer);
if (_dataSource) _dataSource.show = true;
if (_billboards) {
// The camera can have moved anywhere while the layer was off: moveEnd
// was not being listened to, and the preRender watcher is inert while
// disabled AND while the (untimed) refetch below is in flight. So the
// retained per-sprite show flags describe the OLD viewpoint. Re-cull
// BEFORE the collection becomes visible — otherwise re-enabling at a
// new location flashes far-side fires through the planet (and keeps
// near-side ones hidden) until the fetch resolves.
refreshHorizonCulling();
_billboards.show = true;
}
overlayHost.setVisible(FIRMS_OVERLAY_SOURCE_ID, true);
installLodWatcher();
installMoveEndWatcher();
installClickHandler();
registerPickOwner(id, (pickedId) => _pickIndexById.has(pickedId));
if (!_fires.length && !_loading) await loadHeatmap();
restoreSpriteOrderOnEnable('firms', viewer);
},
disable() {
_enabled = false;
clearFireSelection();
if (_dataSource) _dataSource.show = false;
if (_billboards) _billboards.show = false;
overlayHost.clearSource(FIRMS_OVERLAY_SOURCE_ID);
overlayHost.setVisible(FIRMS_OVERLAY_SOURCE_ID, false);
clearSelectedEntityContextForLayer(id);
removeClickHandler();
removeMoveEndWatcher();
unregisterPickOwner(id);
removeLodWatcher();
},
async update() {
if (_destroyed || !_enabled || _loading) return;
// Scheduled 10-minute poll (and the manager's immediate first update):
// refetch live fires through the proxy and re-render. Viewport-driven
// re-renders between polls are handled by the LOD watcher.
await loadHeatmap();
},
destroy(viewer) {
if (_destroyed) return;
_destroyed = true;
_enabled = false;
removeLodWatcher();
removeMoveEndWatcher();
removeClickHandler();
unregisterPickOwner(id);
if (_dataSource && viewer) {
viewer.dataSources.remove(_dataSource, true);
}
_dataSource = null;
removeDetectionCollections(viewer);
clearContextRegistrations();
clearSelectedEntityContextForLayer(id);
_fires = [];
_firesByFrp = [];
_cellCacheByGrid.clear();
_count = 0;
_cellCount = 0;
_lastUpdate = null;
_keyRequired = false;
_stale = false;
_error = null;
_currentLodId = null;
overlayHost.clearSource(FIRMS_OVERLAY_SOURCE_ID);
overlayHost.setVisible(FIRMS_OVERLAY_SOURCE_ID, false);
_currentLodIndex = -1;
_lastViewRect = null;
_selectedFire = null;
_labelCandidates = [];
_labelLodDistance = 0;
_pickIndexById.clear();
_fireByCardId.clear();
_cullPositions.length = 0;
_camSnapValid = false;
},
/**
* Layer stats for the data panel. Degraded feed states surface through
* `error` (established qa-failstate pattern: a dead feed must never look
* like a healthy empty layer) with a matching human `loadingLabel`:
* 'LIVE · updated Xm ago' fresh, 'STALE · cached Xh' when the proxy
* served past-TTL cache, 'KEY REQUIRED' keyless.
*/
getStats() {
const now = Date.now();
const staleText = _lastUpdate ? `STALE · cached ${formatAge(now - _lastUpdate) || '<1h'}` : 'STALE';
let loadingLabel = '';
if (_loading) {
loadingLabel = _fires.length ? 'refreshing...' : 'loading...';
} else if (_keyRequired) {
loadingLabel = 'KEY REQUIRED';
} else if (_stale) {
loadingLabel = staleText;
} else if (_error) {
loadingLabel = _error;
} else if (_lastUpdate) {
loadingLabel = `LIVE · updated ${formatAgoMinutes(now - _lastUpdate)}`;
}
return {
count: _count,
cells: _cellCount,
lastUpdate: _lastUpdate,
loading: _loading,
stale: _stale,
error: _keyRequired ? 'KEY REQUIRED' : (_stale ? staleText : _error),
loadingLabel,
};
},
/**
* Strongest currently-loaded detection (by FRP) for voice targeting
* ("take me to the biggest fire").
* @returns {{latitude: number, longitude: number, frp: number, label: string}|null}
*/
getStrongestFire() {
const strongest = _firesByFrp.length ? _firesByFrp[0] : null;
if (!strongest) return null;
return {
latitude: strongest.lat,
longitude: strongest.lon,
frp: strongest.frp,
label: `Fire · FRP ${formatFrp(strongest.frp)} MW`,
};
},
/**
* Detection-overlay seam, shaped like the other layers' detectable
* objects (traffic/flights). NOT yet registered in initDetection's layer
* list — wiring fires through the detection/label-arbiter pipeline is a
* deliberate post-PR#1 task; when that happens the arbiter replaces this
* layer's greedy declutter as the SELECTOR and the shared overlay remains
* the renderer. Walks the FRP-sorted index so the strongest fires come first.
* @param {{maxCount?: number}} [options]
* @returns {Array<{position: Cesium.Cartesian3, id: string, type: string}>}
*/
getDetectableObjects(options = {}) {
if (!_enabled || !_firesByFrp.length) return [];
const maxCount = Number.isFinite(options.maxCount)
? Math.max(1, Math.floor(options.maxCount))
: 250;
const result = [];
for (const fire of _firesByFrp) {
result.push({
position: firePosition(fire),
id: `FIRE-${String(fire.index).padStart(5, '0')}`,
type: 'FIRE',
});
if (result.length >= maxCount) break;
}
return result;
},
/**
* Snapshot the layer's in-memory fire records as plain JSON-safe
* objects for the analyst query engine. Walks the FRP-sorted index so
* truncation keeps the STRONGEST fires (200k+ detections can be live —
* the cap is load-bearing, not cosmetic). On-demand only (called at
* most once per spoken query) — zero per-frame cost, no listeners, no
* caching. Returns [] while the layer is disabled or empty.
* @param {number} [maxCount=2000] - Maximum records to return (truncation).
* @returns {Array<Object>} See mapAnalystRecord for the record shape.
*/
getAnalystRecords(maxCount = 2000) {
if (!_enabled || !_firesByFrp.length) return [];
const limit = Number.isFinite(maxCount) ? Math.max(1, Math.floor(maxCount)) : 2000;
const result = [];
for (const fire of _firesByFrp) {
result.push(mapAnalystRecord(fire));
if (result.length >= limit) break;
}
return result;
},
/** Test seam that binds the production click path and indexes. */
_bindInteractionForTest(viewer, fires = []) {
_viewer = viewer;
_enabled = true;
_fires = fires;
_firesByFrp = [...fires];
_pickIndexById.clear();
_labelLodDistance = 1e7;
_labelCandidates = fires.map((fire) => {
_pickIndexById.set(`firms-${fire.index}`, fire);
return { fire, position: firePosition(fire) };
});
rebuildAmbientLabels();
installClickHandler();
return _clickHandler;
},
};
/**
* Fetch live fires from the /api/firms proxy and swap them in. Handles the
* three degraded states distinctly: keyless (503 {error:'no_key'} → KEY
* REQUIRED, no retry storm — the 10 min poll re-checks cheaply without
* touching upstream), stale (proxy served past-TTL cache → surfaced via
* getStats), and outright failure (existing fires are KEPT — old data
* beats a wiped map). A click-selected fire survives the swap when the
* same detection (lat/lon/acqMs) is still present.
*/
async function loadHeatmap() {
if (!_dataSource) return;
_loading = true;
try {
const response = await fetch(FIRMS_API_URL, { cache: 'no-store' });
if (!response.ok) {
let payload = null;
try {
payload = await response.json();
} catch { /* non-JSON error body — fall through to the generic error */ }
if (response.status === 503 && payload?.error === 'no_key') {
_keyRequired = true;
_error = null;
_stale = false;
return;
}
throw new Error(`FIRMS HTTP ${response.status}`);
}
const payload = await response.json();
_keyRequired = false;
_error = null;
_stale = Boolean(payload?.stale);
const previousSelection = _selectedFire;
_selectedFire = null;
_fires = adaptFirmsRecords(payload?.fires);
_cellCacheByGrid.clear(); // aggregation is per-dataset — new fires, new cells
_firesByFrp = [..._fires].sort((a, b) => b.frp - a.frp);
_count = _fires.length;
// Data age, not response age: a stale proxy payload truthfully reads old.
_lastUpdate = Number.isFinite(payload?.fetchedAt) ? payload.fetchedAt : Date.now();
// Settle the previous selection BEFORE the LOD rebuild. renderCurrentLod
// runs refreshContextRegistrations(), which deletes every context record
// not in the new top-N — including the one the store still points at.
// Clearing after that deletion fails the ownership guard inside
// clearSelectedEntityContextForLayer and emits nothing at all, so an
// eviction-aware readout never hears that its subject is gone.
const reselected = findMatchingFire(previousSelection);
if (!reselected && previousSelection) {
// The selected detection is not in the new payload: it left the feed
// rather than being deselected. Eviction-aware readouts hold their
// last-known values for this instead of tearing down.
clearSelectedEntityContextForLayer(id, { evicted: true });
}
renderCurrentLod(true);
if (reselected) selectFire(reselected);
} catch (error) {
console.warn(`[Data:${id}] FIRMS live load failed:`, error);
_error = 'live feed unavailable';
} finally {
_loading = false;
}
}
/**
* Find the record in the freshly-loaded set matching a previous selection.
* Identity is the detection itself (lat/lon/acquisition time) — indices
* are regenerated every fetch, so object/index identity cannot be used.
* @param {?Object} previous - Previously selected fire record.
* @returns {?Object} Matching new record.
*/
function findMatchingFire(previous) {
if (!previous) return null;
const key = fireDetectionKey(previous);
return _fires.find((fire) => fireDetectionKey(fire) === key) || null;
}
/**
* Rebuild the render for the current LOD band and viewport. Skips work
* when neither the (hysteresis-damped) LOD band nor the padded view
* rectangle changed meaningfully.
* @param {boolean} force - Rebuild even if LOD/view appear unchanged.
* @returns {boolean} True when a rebuild actually ran. Callers use this to
* avoid a second horizon walk in the same tick: a rebuild already culls
* its freshly-added sprites, an early-out does not.
*/
function renderCurrentLod(force = false) {
if (!_dataSource || !_fires.length || !_viewer) return false;
const lodIndex = selectLodIndex(cameraHeight());
const lod = LOD_LEVELS[lodIndex];
const viewRect = computeViewRect();
if (!force && lodIndex === _currentLodIndex && !viewChangedEnough(viewRect)) return false;
_currentLodIndex = lodIndex;
_currentLodId = lod.id;
_lastViewRect = viewRect ? Cesium.Rectangle.clone(viewRect) : null;
const bounds = viewRect ? paddedDegreeBounds(viewRect) : null;
if (lod.mode === 'detections') {
renderDetections(lod, bounds);
} else {
renderCells(aggregateFires(lod, bounds), lod, bounds);
}
return true;
}
/**
* Bin all detections into grid cells, then viewport-clip BEFORE the
* top-N cap so fires in view never lose their slot to higher-scoring
* cells on other continents. `bounds === null` (sky/horizon or
* near-global view) falls back to the global top-N behavior.
* @param {Object} lod - Active LOD descriptor.
* @param {?Object} bounds - Padded view bounds in degrees, or null.
* @returns {Array<Object>} Cells sorted by heat score, capped.
*/
function aggregateFires(lod, bounds) {
const gridDegrees = lod.gridDegrees;
let sorted = _cellCacheByGrid.get(gridDegrees);
if (!sorted) {
const cells = new Map();
for (const fire of _fires) {
const latCell = Math.floor(fire.lat / gridDegrees) * gridDegrees;
const lonCell = Math.floor(fire.lon / gridDegrees) * gridDegrees;
const key = `${latCell.toFixed(3)}:${lonCell.toFixed(3)}`;
// confidence is normalized 0..1 — weight ×4 preserves the old 0..100×0.04 scale.
const intensity = Math.max(1, fire.frp * 0.18 + fire.confidence * 4 + fire.brightness * 0.01);
const existing = cells.get(key) || {
latCell,
lonCell,
count: 0,
intensity: 0,
maxFrp: 0,
night: 0,
newestAcqMs: 0,
};
existing.count += 1;
existing.intensity += intensity;
existing.maxFrp = Math.max(existing.maxFrp, fire.frp);
existing.newestAcqMs = Math.max(existing.newestAcqMs, fire.acqMs);
if (fire.night) existing.night += 1;
cells.set(key, existing);
}
// Heat-sorted once; per-render clipping below preserves the order.
sorted = [...cells.values()].sort((a, b) => heatScore(b) - heatScore(a));
_cellCacheByGrid.set(gridDegrees, sorted);
}
if (!bounds) return sorted.slice(0, lod.maxCells);
const clipped = [];
for (const cell of sorted) {
if (!cellIntersectsBounds(cell, gridDegrees, bounds)) continue;
clipped.push(cell);
if (clipped.length >= lod.maxCells) break;
}
return clipped;
}
/**
* Render aggregated heat cells (global/regional bands) as ground-clamped
* rectangles. Cell labels do NOT live on the entities anymore — they go
* through the same unclamped, screen-space-decluttered label pipeline as
* detections (see {@link rebuildAmbientLabels}).
* @param {Array<Object>} cells - Aggregated cells, heat-sorted descending.
* @param {Object} lod - Active LOD descriptor.
* @param {?Object} bounds - Padded view bounds in degrees, or null.
*/
function renderCells(cells, lod, bounds) {
ensureDetectionCollections();
_dataSource.entities.removeAll();
if (_billboards) _billboards.removeAll();
_pickIndexById.clear();
_cullPositions.length = 0;
_cellCount = cells.length;
const maxScore = Math.max(1, ...cells.map(heatScore));
_labelCandidates = [];
_labelLodDistance = lod.labelDistance;
for (const cell of cells) {
const score = heatScore(cell);
const normalized = Math.min(1, Math.sqrt(score / maxScore));
const alpha = 0.16 + normalized * 0.5;
const color = heatColor(normalized, alpha);
const centerLon = cell.lonCell + lod.gridDegrees / 2;
const centerLat = cell.latCell + lod.gridDegrees / 2;
const position = Cesium.Cartesian3.fromDegrees(centerLon, centerLat, 0);
_dataSource.entities.add({
rectangle: {
coordinates: Cesium.Rectangle.fromDegrees(
cell.lonCell,
cell.latCell,
cell.lonCell + lod.gridDegrees,
cell.latCell + lod.gridDegrees
),
material: new Cesium.ColorMaterialProperty(color),
heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
},
position,
properties: {
count: cell.count,
intensity: score,
maxFrp: cell.maxFrp,
night: cell.night,
},
});
// Cells arrive heat-sorted, so candidate order doubles as label priority.
// Accent is resolved here because `normalized` only exists in this walk.
_labelCandidates.push({
position,
cullPosition: cellCullPosition(centerLon, centerLat),
fire: null,
cell,
accent: cellAccent(normalized),
});
}
rebuildAmbientLabels();
refreshContextRegistrations(topFiresWithinBounds(bounds));
}
/**
* Render individual detections (local/close bands) as pre-baked
* radial-glow sprite billboards sized by FRP, capped per viewport by
* highest FRP, depth test disabled. The 3D Tiles mesh is never sampled
* per point; instead, the CLOSE band (where terrain parallax is actually
* visible) batch-warms the shared cached DEM floor for its rendered
* subset and re-renders once floors land, so anchors sit on the terrain
* (firePosition). The local band keeps cold anchors at height 0 — at
* ≥750 km camera height the divergence is invisible and warming a
* continent-wide viewport would waste the DEM proxy.
* Labels are not built here; candidates feed {@link rebuildAmbientLabels}.
* @param {Object} lod - Active LOD descriptor.
* @param {?Object} bounds - Padded view bounds in degrees, or null.
*/
function renderDetections(lod, bounds) {
ensureDetectionCollections();
_dataSource.entities.removeAll();
if (!_billboards) return;
_billboards.removeAll();
_pickIndexById.clear();
_cullPositions.length = 0;
let candidates;
if (bounds) {
// Walk the pre-sorted FRP index and early-exit at the cap — the old
// collect-then-sort touched and sorted every in-view detection per
// rebuild (tens of thousands mid-zoom; field-test round 1 chug).
candidates = [];
for (const fire of _firesByFrp) {
if (!boundsContainPoint(bounds, fire.lat, fire.lon)) continue;
candidates.push(fire);
if (candidates.length >= lod.maxDetections) break;
}
} else {
// Sky/horizon view: fall back to the globally strongest detections.
candidates = _firesByFrp.slice(0, lod.maxDetections);
}
_cellCount = candidates.length;
_labelCandidates = [];
_labelLodDistance = lod.labelDistance;
for (const fire of candidates) {
const coreSize = frpPixelSize(fire.frp);
const position = firePosition(fire);
const cullPosition = fireCullPosition(fire);
const pickId = `firms-${fire.index}`;
_pickIndexById.set(pickId, fire);
_cullPositions.push(cullPosition);
_billboards.add({
id: pickId,
position,
image: glowSprite(detectionColorStop(fire), sizeBucket(coreSize)),
verticalOrigin: Cesium.VerticalOrigin.CENTER,
horizontalOrigin: Cesium.HorizontalOrigin.CENTER,
disableDepthTestDistance: Number.POSITIVE_INFINITY,
});
// FRP-sorted walk: candidate order doubles as label priority.
_labelCandidates.push({ position, cullPosition, fire, cell: null });
}
// Freshly-added sprites default to show=true; cull the far side now so a
// rebuild never flashes through-the-planet detections while the camera
// sits still (the moveEnd/preRender hooks only fire on camera motion).
refreshHorizonCulling();
rebuildAmbientLabels();
refreshContextRegistrations(candidates.slice(0, CONTEXT_TOP_N));
if (lod.id === 'close') {
// Batched (chunked ≤200, sequential, session-cached) DEM warm for the
// rendered subset; fires are static so each coarse cell resolves once
// ever. Re-render ONLY when a floor actually landed — a failed resolve
// reports false, so this chain terminates instead of looping against a
// down proxy (the next camera-driven rebuild retries).
warmFireAnchorFloors(candidates).then((warmed) => {
if (!warmed || !_enabled || !_viewer) return;
const currentLod = LOD_LEVELS[_currentLodIndex];
if (!currentLod || currentLod.mode !== 'detections') return;
renderCurrentLod(true);
});
}
}
/**
* Rebuild the card entries for the shared world-overlay host: the
* selected-fire detail card (if any) plus at most MAX_AMBIENT_LABELS
* ambient cards picked by a greedy screen-space declutter — walk the
* priority-ranked candidates, project each with
* SceneTransforms.worldToWindowCoordinates, and accept only candidates
* ≥ LABEL_MIN_SEP_PX from every already-accepted card. Candidates whose
* projection fails are dropped silently. SELECTION runs here, on LOD/
* viewport rebuilds and camera moveEnd — never per frame; RENDERING is
* the host, which re-projects the accepted entries every frame so
* cards track the camera smoothly.
*/
function rebuildAmbientLabels() {
if (!_viewer) return;
const scene = _viewer.scene;
const now = Date.now();
const entries = [];
/** @type {Array<{x: number, y: number}>} Screen positions of accepted labels. */
const accepted = [];
// worldToWindowCoordinates happily projects points on the FAR side of the
// planet, so without this the ≤18 ambient slots get spent on fires the
// overlay host will then horizon-cull at paint time (`horizonCull: true`
// in applyFirmsOverlayPolicy) — near-side fires silently lose their cards.
// Shared with the sprite pass (fireHorizonOccluder) so cards and sprites
// never disagree about which hemisphere a detection is on.
const occluder = fireHorizonOccluder();
const beyondHorizon = (position) => (
occluder ? occluder.isPointVisible(position) !== true : false
);
_fireByCardId.clear();
if (_selectedFire) {
const selectedCard = buildSelectedFireCard(_selectedFire, now);
_fireByCardId.set(selectedCard.id, _selectedFire);
entries.push(selectedCard);
const screen = Cesium.SceneTransforms.worldToWindowCoordinates(
scene,
firePosition(_selectedFire),
scratchWindowCoord
);
// Seed the accepted list so ambient cards keep clear of the detail card.
// A selected fire behind the limb is not painted, so it must not reserve
// screen space either.
if (screen && !beyondHorizon(fireCullPosition(_selectedFire))) {
accepted.push({ x: screen.x, y: screen.y });
}
}
const width = scene.canvas.clientWidth;
const height = scene.canvas.clientHeight;
let ambientCount = 0;
for (const candidate of _labelCandidates) {
if (ambientCount >= MAX_AMBIENT_LABELS) break;
if (candidate.fire && candidate.fire === _selectedFire) continue;
// Spend the bounded cohort only on the visible hemisphere. At global
// LOD, far-side cells can still project on-canvas; accepting those first
// starves front-side cards before the host applies its authoritative cull.
if (beyondHorizon(candidate.cullPosition || candidate.position)) continue;
const screen = Cesium.SceneTransforms.worldToWindowCoordinates(
scene,
candidate.position,
scratchWindowCoord
);
if (!screen) continue; // projection failed (e.g. behind camera) — drop silently
if (screen.x < -LABEL_VIEW_MARGIN_PX || screen.x > width + LABEL_VIEW_MARGIN_PX
|| screen.y < -LABEL_VIEW_MARGIN_PX || screen.y > height + LABEL_VIEW_MARGIN_PX) continue;
if (!screenSeparated(accepted, screen)) continue;
accepted.push({ x: screen.x, y: screen.y });
ambientCount += 1;
const card = candidate.fire
? buildFireCard(candidate, now)
: buildCellCard(candidate, now);
if (candidate.fire) _fireByCardId.set(card.id, candidate.fire);
entries.push(card);
}
overlayHost.setEntries(
FIRMS_OVERLAY_SOURCE_ID,
entries.map((entry) => {
const card = applyFirmsOverlayPolicy(entry, _labelLodDistance);
if (!card.interactive) return card;
return {
...card,
accessibilityLabel: `Focus fire detection ${card.title}, ${card.details.join(', ')}`,
activate: () => {
const fire = _fireByCardId.get(card.id);
if (!fire) return false;
selectAndFocusFire(fire);
return true;
},
};
}),
{
cohortLimit: FIRMS_AMBIENT_COHORT_LIMIT,
collisionCapacity: FIRMS_AMBIENT_COHORT_LIMIT,
moving: false,
},
);
}
/**
* Install the LEFT_CLICK handler for fire selection (enable-time only,
* mirroring the flight layers). Clicking a fire sprite selects it and
* surfaces it in the shared context store; clicking empty space clears
* the selection. Picks owned by sibling layers are left alone.
*/
function installClickHandler() {
if (_clickHandler || !_viewer) return;
_clickHandler = screenSpaceEventHandlerFactory(_viewer);
_clickHandler.setInputAction((click) => {
const picked = _viewer.scene.pick(click.position);
const fire = pickedFire(picked);
if (fire) {
selectAndFocusFire(fire);
return;
}
// A pick that belongs to a sibling layer (e.g. an aircraft) is not
// "empty space" — leave the selection alone and let that layer handle it.
if (picked) {
const pickedId = resolvePickId(picked);
if (pickedId && isOwnedByOtherLayer(id, pickedId)) return;
}
const cardHit = overlayHost.hitTest?.(click.position?.x, click.position?.y, {
sourceId: FIRMS_OVERLAY_SOURCE_ID,
});
if (cardHit) {
const carded = _fireByCardId.get(cardHit.entryId);
if (carded) selectAndFocusFire(carded);
return;
}
clearFireSelection();
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);
}
function removeClickHandler() {
if (_clickHandler) {
_clickHandler.destroy();
_clickHandler = null;
}
}
/** Select one stable detection and request one UI-owned camera transfer. */
function selectAndFocusFire(fire) {
selectFire(fire);
requestWorldFocus({
kind: 'fire',
id: fireDetectionKey(fire),
label: 'FIRE',
position: firePosition(fire),
});
}
/**
* Resolve a scene pick to one of this layer's fire records, or null.
* BillboardCollection picks surface our id either on picked.primitive.id
* or directly on picked.id depending on the CesiumJS pick path.
* @param {*} picked - Result of scene.pick().
* @returns {?Object} Fire record.
*/
function pickedFire(picked) {
if (!picked) return null;
const primitiveId = picked.primitive?.id;
if (typeof primitiveId === 'string' && _pickIndexById.has(primitiveId)) {
return _pickIndexById.get(primitiveId);
}
if (typeof picked.id === 'string' && _pickIndexById.has(picked.id)) {
return _pickIndexById.get(picked.id);
}
return null;
}
/**
* Select a fire: show its detail label and mark it selected in the shared
* context store so voice "what's selected" resolves to it.
* @param {Object} fire - Detection record.
*/
function selectFire(fire) {
_selectedFire = fire;
try {
registerFireContext(fire);
_contextIds.add(fireDetectionKey(fire));
selectEntityContext(fire.contextEntity);
} catch {
// context store unavailable — the selection label still works
}
rebuildAmbientLabels();
}
function clearFireSelection() {
if (!_selectedFire) return;
_selectedFire = null;
clearSelectedEntityContextForLayer(id);
rebuildAmbientLabels();
}
/**
* Ambient labels are placed via screen-space projection, so they need a
* re-declutter after the camera settles — on moveEnd, never per frame.
*/
function installMoveEndWatcher() {
if (_moveEndRemover || !_viewer) return;
_moveEndRemover = _viewer.camera.moveEnd.addEventListener(() => {
if (!_enabled) return;
// Settled-camera exactness for the horizon pass (the throttled preRender
// watcher can last have run up to LOD_CHECK_MS before the camera
// stopped). Runs ahead of the `_loading` gate on purpose: the sprites on
// screen during a refresh are the ones that need culling.
refreshHorizonCulling();
if (_loading) return;
rebuildAmbientLabels();
});
}
function removeMoveEndWatcher() {
if (_moveEndRemover) {
_moveEndRemover();
_moveEndRemover = null;
}
}
/**
* Register the top detections of the current render set in the shared
* context store (voice "what's burning here") and drop stale entries
* from the previous rebuild.
* @param {Array<Object>} fires - FRP-ranked detections to register.
*/
function refreshContextRegistrations(fires) {
let store = null;
try {
store = getContextStore();
} catch {
return;
}
const nextIds = new Set();
for (const fire of fires) {
nextIds.add(registerFireContext(fire));
}
// The click-selected fire must stay queryable ("what's selected") even
// when it falls outside the top-N context slice.
if (_selectedFire) {
nextIds.add(registerFireContext(_selectedFire));
}
for (const staleId of _contextIds) {
if (!nextIds.has(staleId)) store.entities.delete(staleId);
}
_contextIds = nextIds;
}
/**
* Register one fire in the shared context store (idempotent) and return
* its record id.
* @param {Object} fire - Detection record.
* @returns {string} Context record id.
*/
function registerFireContext(fire) {
const recordId = fireDetectionKey(fire);
if (!fire.contextEntity) {
fire.contextEntity = {
show: true,
};
}
// Refreshed every registration: the anchor re-grounds onto the DEM when
// its floor cell warms, and voice targeting must project the same point
// the sprite renders at.
fire.contextEntity.__localBaseCartesian = firePosition(fire);
registerEntityContext(fire.contextEntity, {
id: recordId,
layerId: id,
layerName: name,
source: 'NASA FIRMS',
dataSource: _dataSource,
label: `Fire · FRP ${formatFrp(fire.frp)} MW`,
latitude: fire.lat,
longitude: fire.lon,
properties: {
frp: fire.frp,
confidence: confidenceBucket(fire.confidence),
age: fire.acqMs > 0 ? formatAge(Date.now() - fire.acqMs) : 'unknown',
sensor: fire.sensor || 'unknown',
},
});
return recordId;
}
function clearContextRegistrations() {
if (!_contextIds.size) return;
try {
const store = getContextStore();
for (const recordId of _contextIds) store.entities.delete(recordId);
} catch {
// store unavailable — nothing to clean
}
_contextIds = new Set();
}
/**
* Top-FRP detections within the given bounds (or globally when bounds is
* null). Walks the pre-sorted FRP index so it stays a single cheap pass.
* @param {?Object} bounds - Padded view bounds in degrees, or null.
* @param {number} limit - Max detections returned.
* @returns {Array<Object>}
*/
function topFiresWithinBounds(bounds, limit = CONTEXT_TOP_N) {
if (!bounds) return _firesByFrp.slice(0, limit);
const top = [];
for (const fire of _firesByFrp) {
if (!boundsContainPoint(bounds, fire.lat, fire.lon)) continue;
top.push(fire);
if (top.length >= limit) break;
}
return top;
}
function ensureDetectionCollections() {
if (!_viewer || _billboards) return;
_billboards = new Cesium.BillboardCollection({
scene: _viewer.scene,
blendOption: Cesium.BlendOption.TRANSLUCENT,
});
_billboards.show = _enabled;
_viewer.scene.primitives.add(_billboards);
registerSpriteCollection('firms', _billboards);
restoreSpriteOrder(_viewer);
overlayHost.setVisible(FIRMS_OVERLAY_SOURCE_ID, _enabled);
}
function removeDetectionCollections(viewer) {
const scene = viewer?.scene || _viewer?.scene;
if (scene && !scene.isDestroyed?.()) {
try {
if (_billboards) scene.primitives.remove(_billboards);
} catch { /* already torn down */ }
}
_billboards = null;
overlayHost.clearSource(FIRMS_OVERLAY_SOURCE_ID);
overlayHost.setVisible(FIRMS_OVERLAY_SOURCE_ID, false);
}
/**
* Shared horizon occluder positioned at the current camera, or null when
* there is no usable camera yet (init order / headless stubs).
* `viewer.camera` and `viewer.scene.camera` are the SAME object in Cesium;
* both are probed so a partial stub (either shape) still gets a real
* occluder rather than silently degrading to "nothing is ever occluded".
* @returns {?Cesium.EllipsoidalOccluder}
*/
function fireHorizonOccluder() {
const camera = _viewer?.camera?.positionWC ? _viewer.camera : _viewer?.scene?.camera;
if (!camera?.positionWC) return null;
return horizonOccluder(camera);
}
/**
* Hide detection sprites that sit beyond the ellipsoid horizon (see
* {@link applyHorizonCull}). Runs on the cadences that already exist in this
* layer — the throttled LOD preRender watcher (camera-moved only), camera
* moveEnd, and each detection rebuild — never as a new per-frame pass.
* No-ops in the `cells` bands, where the collection is empty.
*/
function refreshHorizonCulling() {
if (!_billboards || !_billboards.length) return;
applyHorizonCull(_billboards, fireHorizonOccluder(), _cullPositions);
}
function cameraHeight() {
return _viewer?.camera?.positionCartographic?.height ?? Number.POSITIVE_INFINITY;
}
/** Raw LOD index for a camera height (0 = global ... 3 = close). */
function rawLodIndex(height) {
const index = LOD_LEVELS.findIndex((level) => height >= level.minHeight);
return index === -1 ? LOD_LEVELS.length - 1 : index;
}
/**
* LOD selection with ±10% hysteresis around band floors: a band switch
* only happens once the camera clears the boundary by the margin, so a
* slow zoom oscillating on an edge cannot trigger a rebuild every check.
* @param {number} height - Camera height in meters.
* @returns {number} LOD index to render.
*/
function selectLodIndex(height) {
const raw = rawLodIndex(height);
if (_currentLodIndex < 0 || raw === _currentLodIndex) return raw;
let index = _currentLodIndex;
// Zooming out: enter a coarser band only after clearing its floor by +10%.
while (index > raw && height >= LOD_LEVELS[index - 1].minHeight * (1 + LOD_HYSTERESIS)) index -= 1;
// Zooming in: leave the current band only after dropping 10% below its floor.
while (index < raw && height <= LOD_LEVELS[index].minHeight * (1 - LOD_HYSTERESIS)) index += 1;
return index;
}
/** Current camera view rectangle, or null when looking at sky/horizon. */
function computeViewRect() {
try {
const rect = _viewer?.camera?.computeViewRectangle(
_viewer?.scene?.globe?.ellipsoid,
scratchViewRect
);
return rect || null;
} catch {
return null;
}
}
/**
* True when the camera view rectangle drifted far enough from the last
* rendered one that the padding is at risk of being consumed (pan) or
* the footprint changed notably (zoom within a band).
* @param {?Cesium.Rectangle} viewRect - Current view rectangle.
* @returns {boolean}
*/
function viewChangedEnough(viewRect) {
if (!viewRect) return false; // sky/horizon — keep the current render
if (!_lastViewRect) return true; // previous render was global fallback
const lastWidth = Cesium.Rectangle.computeWidth(_lastViewRect);
const lastHeight = Cesium.Rectangle.computeHeight(_lastViewRect);
const width = Cesium.Rectangle.computeWidth(viewRect);
const height = Cesium.Rectangle.computeHeight(viewRect);
if (width > lastWidth * 1.3 || width < lastWidth * 0.75) return true;
if (height > lastHeight * 1.3 || height < lastHeight * 0.75) return true;
const lastCenter = Cesium.Rectangle.center(_lastViewRect, scratchCenterA);
const center = Cesium.Rectangle.center(viewRect, scratchCenterB);
const latShift = Math.abs(center.latitude - lastCenter.latitude);
let lonShift = Math.abs(center.longitude - lastCenter.longitude);
if (lonShift > Math.PI) lonShift = Cesium.Math.TWO_PI - lonShift;
return latShift > lastHeight * VIEW_PADDING * 0.6 || lonShift > lastWidth * VIEW_PADDING * 0.6;
}
function installLodWatcher() {
if (_preRenderRemover || !_viewer) return;
// The LOD sweep is throttle-gated inside preRender. When the camera
// settles just inside the throttle window, the final rebuild would wait
// for a frame that idle mode never produces — schedule one. (perf wave 2)
if (!_moveEndSettleRemover) {
_moveEndSettleRemover = _viewer.camera.moveEnd.addEventListener(() => {
if (!_enabled) return;
setTimeout(() => governorRequestRender('firms-lod-settle'), LOD_CHECK_MS + 40);
});
}
_preRenderRemover = _viewer.scene.preRender.addEventListener(() => {
// NOTE: `_loading`/empty-data are deliberately NOT part of this guard.
// A refresh has no timeout, and sprites from the previous payload stay
// on screen throughout it — so the horizon pass below must keep running
// while a fetch is in flight. Only the rebuild is gated on fresh data.
if (!_enabled) return;
const now = performance.now();
if (now - _lastLodCheck < LOD_CHECK_MS) return;
_lastLodCheck = now;
// Idle camera: two scratch compares and out — no view-rect math, no
// aggregation, no allocation while the user is parked.
const camera = _viewer.camera;
if (_camSnapValid
&& Cesium.Cartesian3.equalsEpsilon(camera.positionWC, _camPos, 0, 0.5)
&& Cesium.Cartesian3.equalsEpsilon(camera.directionWC, _camDir, 0, 1e-7)) {
return;
}
Cesium.Cartesian3.clone(camera.positionWC, _camPos);
Cesium.Cartesian3.clone(camera.directionWC, _camDir);
_camSnapValid = true;
// The camera moved, so the horizon moved. A rebuild culls its own fresh
// sprites (renderDetections); an early-out — same LOD band and view
// rect, or a refresh in flight — does not, so cull here instead.
// Exactly ONE occlusion walk per tick either way, bounded by the
// idle-gate + LOD_CHECK_MS throttle above: a parked camera costs
// nothing, a moving one pays one ≤maxDetections show-flip walk at
// ~1.5 Hz.
const rebuilt = (_fires.length && !_loading) ? renderCurrentLod(false) : false;
if (!rebuilt) refreshHorizonCulling();
});
}
function removeLodWatcher() {
if (_preRenderRemover) {
_preRenderRemover();
_preRenderRemover = null;
}
if (_moveEndSettleRemover) {
_moveEndSettleRemover();
_moveEndSettleRemover = null;
}
}
}
/**
* Expand a view rectangle by VIEW_PADDING per side and convert to degree
* bounds with an explicit anti-meridian wrap flag. Returns null for
* near-global views where clipping would be pointless.
* @param {Cesium.Rectangle} rect - Camera view rectangle (radians).
* @returns {?{west: number, south: number, east: number, north: number, wraps: boolean}}
*/
function paddedDegreeBounds(rect) {
const width = Cesium.Rectangle.computeWidth(rect);
const height = Cesium.Rectangle.computeHeight(rect);
if (width >= Math.PI * 1.85) return null;
const padLon = width * VIEW_PADDING;
const padLat = height * VIEW_PADDING;
const south = Math.max(-Cesium.Math.PI_OVER_TWO, rect.south - padLat);
const north = Math.min(Cesium.Math.PI_OVER_TWO, rect.north + padLat);
let west = rect.west - padLon;
let east = rect.east + padLon;
let wraps;
if (width + padLon * 2 >= Cesium.Math.TWO_PI) {
west = -Math.PI;
east = Math.PI;
wraps = false;
} else {
west = Cesium.Math.negativePiToPi(west);
east = Cesium.Math.negativePiToPi(east);
wraps = west > east;
}
return {
west: Cesium.Math.toDegrees(west),
south: Cesium.Math.toDegrees(south),
east: Cesium.Math.toDegrees(east),
north: Cesium.Math.toDegrees(north),
wraps,
};
}
/** Point-in-bounds test in degrees, anti-meridian aware. */
function boundsContainPoint(bounds, lat, lon) {
if (lat < bounds.south || lat > bounds.north) return false;
if (bounds.wraps) return lon >= bounds.west || lon <= bounds.east;
return lon >= bounds.west && lon <= bounds.east;
}
/** Cell-rectangle/bounds intersection test in degrees, anti-meridian aware. */
function cellIntersectsBounds(cell, gridDegrees, bounds) {
if (cell.latCell + gridDegrees < bounds.south || cell.latCell > bounds.north) return false;
const west = cell.lonCell;
const east = cell.lonCell + gridDegrees;
if (bounds.wraps) return east >= bounds.west || west <= bounds.east;
return east >= bounds.west && west <= bounds.east;
}
function heatScore(cell) {
return cell.intensity + cell.count * 0.8 + cell.night * 0.6 + cell.maxFrp * 0.12;
}
function heatColor(value, alpha) {
if (value > 0.72) return Cesium.Color.RED.withAlpha(alpha);
if (value > 0.42) return Cesium.Color.ORANGE.withAlpha(alpha);
return Cesium.Color.YELLOW.withAlpha(alpha);
}
/**
* Pick a sprite color stop from FRP + confidence, reusing the same
* yellow → orange → red thresholds as the aggregated heat cells.
* @param {Object} fire - Detection record.
* @returns {{name: string, color: Cesium.Color}}
*/
function detectionColorStop(fire) {
const heat = Math.min(1, Math.sqrt(Math.max(0, fire.frp) / 150) * 0.85 + fire.confidence * 0.15);
if (heat > 0.72) return DETECTION_COLOR_STOPS[0];
if (heat > 0.42) return DETECTION_COLOR_STOPS[1];
return DETECTION_COLOR_STOPS[2];
}
/** FRP → core marker pixel size, clamped to 8..28px. */
function frpPixelSize(frp) {
return Math.max(8, Math.min(28, Math.round(8 + Math.sqrt(Math.max(0, frp)) * 2)));
}
/** Quantize a core size to a 2px bucket so the sprite cache stays tiny. */
function sizeBucket(coreSize) {
return Math.max(8, Math.min(28, Math.round(coreSize / 2) * 2));
}
/**
* Build (and cache) a radial-glow sprite: hot near-white center fading
* through the stop color to a transparent edge. The glow lives in the
* sprite itself because global bloom defaults OFF.
* @param {{name: string, color: Cesium.Color}} stop - Color stop.
* @param {number} corePx - Bucketed core size in pixels.
* @returns {string} PNG data URL.
*/
function glowSprite(stop, corePx) {
const key = `${stop.name}:${corePx}`;
const cached = glowSpriteCache.get(key);
if (cached) return cached;
const dimension = corePx * 2;
const canvas = document.createElement('canvas');
canvas.width = dimension;
canvas.height = dimension;
const context = canvas.getContext('2d');
if (!context) return '';
const radius = dimension / 2;
const rgb = [
Math.round(stop.color.red * 255),
Math.round(stop.color.green * 255),
Math.round(stop.color.blue * 255),
].join(',');
const gradient = context.createRadialGradient(radius, radius, 0, radius, radius, radius);
gradient.addColorStop(0, 'rgba(255,255,235,0.95)');
gradient.addColorStop(0.25, `rgba(${rgb},0.9)`);
gradient.addColorStop(0.55, `rgba(${rgb},0.35)`);
gradient.addColorStop(1, `rgba(${rgb},0)`);
context.fillStyle = gradient;
context.fillRect(0, 0, dimension, dimension);
const dataUrl = canvas.toDataURL('image/png');
glowSpriteCache.set(key, dataUrl);
return dataUrl;
}
/**
* Lazily-cached Cartesian3 anchor at the shared ground floor (DEM/mesh cell
* + lift) when the floor is warm, else ellipsoid height 0 (owner field
* finding 2026-07-21: height-0 anchors read as buried under high terrain at
* close/oblique zoom). Warm-cache read only — floors are warmed in batch by
* renderDetections for the close band; everything else (cell-band context
* registrations, detectable objects) just rides whatever is already warm.
* Fires are static and floor cells latch, so each detection re-allocates at
* most once per floor state (cold 0 → warm DEM). Rendering stays depth-test
* free either way (contacts are ALWAYS visible — never below the surface,
* slightly above is fine).
* @param {Object} fire - Detection record.
* @returns {Cesium.Cartesian3}
*/
function firePosition(fire) {
const height = fireAnchorHeight(fire.lat, fire.lon);
if (!fire.position || fire.positionHeight !== height) {
fire.position = Cesium.Cartesian3.fromDegrees(fire.lon, fire.lat, height);
fire.positionHeight = height;
}
return fire.position;
}
/**
* Occlusion-test anchor for one detection. Returns the render position
* outright for anchors comfortably above the ellipsoid (the common case) and
* a lazily-cached lifted point otherwise — see CULL_LIFT_THRESHOLD_M. This
* NEVER feeds rendering: the datum-correct anchor from {@link firePosition}
* is what the sprite and the card are drawn at.
* @param {Object} fire - Detection record.
* @returns {Cesium.Cartesian3}
*/
export function fireCullPosition(fire) {
const position = firePosition(fire);
if (fire.positionHeight >= CULL_LIFT_THRESHOLD_M) return position;
if (!fire.cullPosition) {
fire.cullPosition = Cesium.Cartesian3.fromDegrees(fire.lon, fire.lat, CULL_LIFT_M);
}
return fire.cullPosition;
}
/**
* Occlusion-test anchor for an aggregated heat cell. Cell centers are built at
* height 0 (exactly on the ellipsoid), which the occluder treats as a limb
* boundary case, so they get the same lift as sub-ellipsoid fire anchors.
* @param {number} lon - Cell center longitude in degrees.
* @param {number} lat - Cell center latitude in degrees.
* @returns {Cesium.Cartesian3}
*/
function cellCullPosition(lon, lat) {
return Cesium.Cartesian3.fromDegrees(lon, lat, CULL_LIFT_M);
}
/**
* Horizon-cull a billboard collection against an ellipsoid occluder.
*
* The Cesium globe is hidden in this app (Google 3D Tiles render the planet),
* so nothing writes far-side depth — and these sprites are additionally
* always-on-top (`disableDepthTestDistance: INFINITY`, so a detection is never
* swallowed by terrain it sits on). Without an explicit occluder pass, fires on
* the opposite side of the Earth shine through the planet at tilted mid-altitude
* views. Same pattern as the flights/CCTV layers' `EllipsoidalOccluder` passes.
*
* Pure and allocation-free: reads `billboard.position`, writes `billboard.show`
* only when it actually flips (assigning `show` dirties the collection's vertex
* buffer). Accepts any `{length, get(i)}` shape so it is unit-testable without
* a WebGL scene.
*
* @param {?{length: number, get: function(number): (Object|undefined)}} billboards
* Billboard collection (or collection-shaped stub).
* @param {?{isPointVisible: function(Object): boolean}} occluder Horizon occluder.
* @param {?Array<Cesium.Cartesian3>} [cullPositions=null] Index-aligned lifted
* occlusion-test anchors (see {@link fireCullPosition}); falls back to the
* billboard's own render position wherever an entry is absent.
* @returns {number} Count of billboards left visible (0 when nothing to test).
*/
export function applyHorizonCull(billboards, occluder, cullPositions = null) {
if (!billboards || typeof billboards.get !== 'function') return 0;
if (typeof occluder?.isPointVisible !== 'function') return 0;
const total = Number(billboards.length) || 0;
let visibleCount = 0;
for (let i = 0; i < total; i += 1) {
const billboard = billboards.get(i);
if (!billboard) continue;
const point = (cullPositions && cullPositions[i]) || billboard.position;
const visible = occluder.isPointVisible(point) === true;
if (billboard.show !== visible) billboard.show = visible;
if (visible) visibleCount += 1;
}
return visibleCount;
}
/**
* True when `screen` is at least LABEL_MIN_SEP_PX away from every accepted
* screen position (greedy declutter accept test).
* @param {Array<{x: number, y: number}>} accepted - Accepted label positions.
* @param {Cesium.Cartesian2} screen - Candidate window coordinates.
* @returns {boolean}
*/
function screenSeparated(accepted, screen) {
const minSq = LABEL_MIN_SEP_PX * LABEL_MIN_SEP_PX;
for (let i = 0; i < accepted.length; i += 1) {
const dx = screen.x - accepted[i].x;
const dy = screen.y - accepted[i].y;
if (dx * dx + dy * dy < minSq) return false;
}
return true;
}
/**
* Card model for a click-selected fire — the full-detail card, drawn last
* (on top) and never distance-faded by the overlay.
* Exported for unit tests.
* @param {Object} fire - Detection record.
* @param {number} nowMs - Current epoch milliseconds.
* @returns {Object} firmsLabels entry.
*/
export function buildSelectedFireCard(fire, nowMs) {
const meta = [`${confidenceBucket(fire.confidence)} conf`];
if (fire.acqMs > 0) {
const age = formatAge(nowMs - fire.acqMs);
if (age) meta.push(`${age} ago`);
}
const sat = satelliteShortName(fire.satellite);
meta.push(sat ? `${fire.sensor || 'VIIRS'} ${sat}` : (fire.sensor || 'sensor n/a'));
return {
id: `selected-fire:${fireDetectionKey(fire)}`,
actionable: true,
position: firePosition(fire),
// Host-side horizon test uses this instead of the render anchor.
cullPosition: fireCullPosition(fire),
gapPx: frpPixelSize(fire.frp),
accent: accentForSeverity(detectionColorStop(fire).name),
title: `FIRE · ${formatFrp(fire.frp)} MW`,
details: [
meta.join(' · '),
formatLatLon(fire.lat, fire.lon) + (fire.night ? ' · NIGHT' : ''),
],
selected: true,
priority: Number.MAX_SAFE_INTEGER,
};
}
/**
* Card model for an ambient fire detection, e.g. title "▲ 47 MW", detail
* "high · 14h · N20". Ages are computed against each detection's acquisition
* time — with the live feed everything reads under 24 h (and a stale cache
* reads truthfully old). Exported for unit tests.
* @param {{fire: Object, position: Cesium.Cartesian3}} candidate - Label candidate.
* @param {number} nowMs - Current epoch milliseconds.
* @returns {Object} firmsLabels entry.
*/
export function buildFireCard(candidate, nowMs) {
const fire = candidate.fire;
const meta = [confidenceBucket(fire.confidence)];
if (fire.acqMs > 0) {
const age = formatAge(nowMs - fire.acqMs);
if (age) meta.push(age);
}
const sat = satelliteShortName(fire.satellite) || fire.sensor;
if (sat) meta.push(sat);
return {
id: `fire:${fireDetectionKey(fire)}`,
actionable: true,
position: candidate.position,
cullPosition: candidate.cullPosition || candidate.position,
gapPx: frpPixelSize(fire.frp),
accent: accentForSeverity(detectionColorStop(fire).name),
title: `▲ ${formatFrp(fire.frp)} MW`,
details: [meta.join(' · ')],
selected: false,
priority: Number(fire.frp) || 0,
};
}
/**
* Card model for an aggregated heat cell, e.g. title "14 FIRES", detail
* "max 210 MW · new 3h". Accent comes from the candidate (heat-normalized
* score is only known at renderCells time). Exported for unit tests.
* @param {{cell: Object, position: Cesium.Cartesian3, accent: string}} candidate
* @param {number} nowMs - Current epoch milliseconds.
* @returns {Object} firmsLabels entry.
*/
export function buildCellCard(candidate, nowMs) {
const cell = candidate.cell;
const noun = cell.count === 1 ? 'FIRE' : 'FIRES';
const parts = [`max ${formatFrp(cell.maxFrp)} MW`];
if (cell.newestAcqMs > 0) {
const age = formatAge(nowMs - cell.newestAcqMs);
if (age) parts.push(`new ${age}`);
}
return {
id: `cell:${cell.latCell ?? 'x'}:${cell.lonCell ?? 'x'}`,
position: candidate.position,
cullPosition: candidate.cullPosition || candidate.position,
gapPx: 10,
accent: candidate.accent || accentForSeverity('yellow'),
title: `${cell.count} ${noun}`,
details: [parts.join(' · ')],
selected: false,
priority: Number(cell.maxFrp) || 0,
};
}
/**
* Add the host-owned layout/fade/collision fields to a source-formatted FIRMS
* card. Selected fires share the collision domain so their protected rect
* excludes ambient cards, but bypass both the 18-card cohort and distance fade.
* @param {Object} card Source-formatted card.
* @param {number} fadeDistance Current LOD fade distance in metres.
* @returns {Object}
*/
export function applyFirmsOverlayPolicy(card, fadeDistance) {
const selected = card?.selected === true;
const rawGap = Number(card?.gapPx) || 10;
const gapPx = Math.max(12, rawGap + 8);
return {
...card,
variant: selected ? 'selected' : 'card',
protected: selected,
collisionGroup: 'ambient-card',
cardStyle: 'tactical',
gapPx,
leaderOffsetPx: Math.max(2, gapPx - 6),
verticalOnly: true,
viewportMargin: 4,
maxDistance: selected ? Number.POSITIVE_INFINITY : fadeDistance,
distanceFadeStartRatio: 0.7,
edgeFade: 'keyhole',
horizonCull: true,
terrainOcclusion: false,
// Aggregate cells omit actionable because they do not identify one fire.
interactive: card?.actionable === true,
};
}
/**
* Heat-normalized cell score → severity accent, mirroring heatColor's
* red/orange/yellow thresholds.
* @param {number} normalized - 0..1 normalized heat score.
* @returns {string} "r, g, b" accent string.
*/
function cellAccent(normalized) {
if (normalized > 0.72) return accentForSeverity('red');
if (normalized > 0.42) return accentForSeverity('orange');
return accentForSeverity('yellow');
}
/** Coordinate line like "30.512°N 75.831°E". */
function formatLatLon(lat, lon) {
const latPart = `${Math.abs(lat).toFixed(3)}°${lat >= 0 ? 'N' : 'S'}`;
const lonPart = `${Math.abs(lon).toFixed(3)}°${lon >= 0 ? 'E' : 'W'}`;
return `${latPart} ${lonPart}`;
}
function formatFrp(frp) {
return frp >= 10 ? frp.toFixed(0) : frp.toFixed(1);
}
/** Millisecond delta → "<1h" / "Xh" / "Xd", or '' for invalid input. */
function formatAge(deltaMs) {
if (!Number.isFinite(deltaMs) || deltaMs < 0) return '';
const hours = deltaMs / 3600000;
if (hours < 1) return '<1h';
if (hours < 48) return `${Math.round(hours)}h`;
return `${Math.round(hours / 24)}d`;
}
/** Millisecond delta → "<1m ago" / "Xm ago" / "Xh ago" (fresh-feed readout). */
function formatAgoMinutes(deltaMs) {
if (!Number.isFinite(deltaMs) || deltaMs < 0) return 'just now';
const minutes = Math.floor(deltaMs / 60000);
if (minutes < 1) return '<1m ago';
if (minutes < 90) return `${minutes}m ago`;
return `${Math.round(minutes / 60)}h ago`;
}
/** Normalized 0..1 confidence → low/nominal/high display bucket. */
function confidenceBucket(confidence) {
if (confidence >= 0.75) return 'high';
if (confidence >= 0.45) return 'nominal';
return 'low';
}