Files
gods-eye-view/src/data/cctvLod.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

448 lines
18 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.
/**
* @module cctvLod
*
* Pure selection policy for the citywide ambient CCTV card tier.
* Cesium-specific visibility projection stays in cctv.js; this module turns
* the resulting in-view candidates into a bounded, nearest-first ambient
* card set, keeps that set stable across small camera moves (eviction
* grace), and paces static-frame refreshes per source.
*
* Engine adapted from Manjunath's Part C work (`fix/cctv-part-c-review`):
* the zoom-scaled budgets, distance-ranked in-view selection, the
* eviction-grace planner, and the source-aware refresh cadences are his,
* retargeted from the rejected world-space static-plane ring to the
* screen-space thumbnail cards (see
* docs/superpowers/specs/2026-07-29-cctv-ambient-cards-design.md).
*/
// Ambient-card budgets (owner round 2, item C: raised 16/24/32 → 20/28/40 —
// "a lot of empty space"). Owner-tunable as a set, together with the card
// scale waypoints (1,800/6,000/9,500 m, cctvCards.js) and
// CCTV_CARD_MIN_SEP_PX: budgets say how many cameras HOLD cards, the
// waypoints and separation say how many fit on screen.
export const CCTV_AMBIENT_CARD_MAX = 40;
export const CCTV_AMBIENT_CARD_MID = 28;
export const CCTV_AMBIENT_CARD_MIN = 20;
const STREET_HEIGHT_M = 2_500;
const CITY_HEIGHT_M = 15_000;
const DEFAULT_STATIC_REFRESH_MS = 5 * 60 * 1000;
const PROVIDER_STATIC_REFRESH_MS = Object.freeze({
'austin transportation & public works': 5 * 60 * 1000,
'transport for london': 3 * 60 * 1000,
caltrans: 3 * 60 * 1000,
});
/**
* Returns the bounded ambient-card budget for the current viewer height.
* Card counts stay inside the 20..40 range (owner round 2): street level
* keeps the overlay sparse, metro scale earns the full ring.
*
* @param {number} cameraHeightM
* @returns {{cardLimit:number}}
*/
export function cctvLodBudgets(cameraHeightM) {
const height = Number.isFinite(cameraHeightM) ? Math.max(0, cameraHeightM) : CITY_HEIGHT_M;
if (height <= STREET_HEIGHT_M) {
return { cardLimit: CCTV_AMBIENT_CARD_MIN };
}
if (height <= CITY_HEIGHT_M) {
return { cardLimit: CCTV_AMBIENT_CARD_MID };
}
return { cardLimit: CCTV_AMBIENT_CARD_MAX };
}
/**
* Selection-level incumbency (owner field-test finding 4, 2026-07-29): a
* camera currently holding a card ranks with its distance discounted by this
* factor, so a small camera move never batch-swaps the ring — a non-carded
* camera displaces a carded one only when it is meaningfully (>20%) closer.
*/
export const CCTV_CARD_INCUMBENT_FACTOR = 0.8;
/**
* Effective ranking distance for the ambient-card selection: incumbents
* (cameras that already hold a card) get the 20% distance discount.
* @param {number} distanceKm
* @param {boolean} isIncumbent
* @param {number} [factor]
* @returns {number}
*/
export function incumbentRankKm(distanceKm, isIncumbent, factor = CCTV_CARD_INCUMBENT_FACTOR) {
const km = Number.isFinite(distanceKm) ? Math.max(0, distanceKm) : Infinity;
return isIncumbent ? km * factor : km;
}
/** Fraction of the ambient-card rank contributed by screen-center distance. */
export const CCTV_CARD_CENTER_WEIGHT = 0.5;
/** Robust pool-distance percentile used to scale the screen-space term. */
export const CCTV_CARD_SPREAD_PERCENTILE = 0.9;
/** True only when both viewport dimensions are finite positive pixels. */
export function hasFiniteCctvViewport(viewW, viewH) {
return Number.isFinite(viewW) && viewW > 0
&& Number.isFinite(viewH) && viewH > 0;
}
/**
* Returns an anchor's normalized distance from screen center: zero at center,
* one at or beyond a viewport corner.
* @param {number} sx
* @param {number} sy
* @param {number} viewW
* @param {number} viewH
* @returns {number}
*/
export function screenCenterFraction(sx, sy, viewW, viewH) {
if (!hasFiniteCctvViewport(viewW, viewH)) return 0;
if (!Number.isFinite(sx) || !Number.isFinite(sy)) return 1;
const centerX = viewW / 2;
const centerY = viewH / 2;
const halfDiagonalPx = Math.hypot(centerX, centerY) || 1;
return Math.min(1, Math.hypot(sx - centerX, sy - centerY) / halfDiagonalPx);
}
/**
* Returns a robust distance scale for the eligible candidate pool.
* @param {number[]} distancesKm
* @param {number} [percentile]
* @returns {number}
*/
export function cctvCandidateSpreadKm(
distancesKm,
percentile = CCTV_CARD_SPREAD_PERCENTILE,
) {
const finite = (Array.isArray(distancesKm) ? distancesKm : [])
.filter((distanceKm) => Number.isFinite(distanceKm) && distanceKm >= 0)
.sort((a, b) => a - b);
if (!finite.length) return 0;
const p = Math.min(1, Math.max(0, Number.isFinite(percentile) ? percentile : 0));
return finite[Math.round(p * (finite.length - 1))];
}
/**
* Blends viewer distance with screen-center distance in common km units.
* @param {number} distanceKm
* @param {number} centerFraction
* @param {number} spreadKm
* @param {number} [weight]
* @returns {number}
*/
export function blendCenterRankKm(
distanceKm,
centerFraction,
spreadKm,
weight = CCTV_CARD_CENTER_WEIGHT,
) {
const km = Number.isFinite(distanceKm) ? Math.max(0, distanceKm) : Infinity;
if (!Number.isFinite(km)) return Infinity;
const w = Math.min(1, Math.max(0, Number.isFinite(weight) ? weight : 0));
const spread = Number.isFinite(spreadKm) && spreadKm > 0 ? spreadKm : 0;
const fraction = Number.isFinite(centerFraction)
? Math.min(1, Math.max(0, centerFraction))
: 1;
return (1 - w) * km + w * spread * fraction;
}
// Screen-distribution grid (owner round 2, item C — "a lot of empty space"):
// pure nearest-first selection clusters winners at screen center (nearest ==
// most central at typical view pitch) and leaves the periphery bare. The
// viewport is bucketed into this grid and every occupied cell gets its best
// candidate before global rank fills the rest. Owner-tunable together with
// the budgets above.
export const CCTV_CARD_GRID_COLS = 5;
export const CCTV_CARD_GRID_ROWS = 4;
/**
* Screen-space distribution pass (owner round 2, item C). Buckets the
* viewport into a CCTV_CARD_GRID_COLS × CCTV_CARD_GRID_ROWS grid, assigns
* each candidate to its cell (anchors just outside the viewport clamp to
* the edge cells), ranks within cells by effective distance (`rankKm` —
* incumbency discount already applied by the caller), then takes each
* occupied cell's best — nearest cell-winners first, so an under-budget cut
* stays deterministic — until the budget is filled; leftover budget goes to
* the remaining candidates in global rank order. Empty cells are skipped.
* Pure and allocation-honest: decides only WHICH cameras hold cards — the
* per-frame draw-pass declutter stays authoritative over what paints.
*
* @param {Array<{id:string,sx:number,sy:number,rankKm:number}>} candidates
* @param {Object} [options]
* @param {number} [options.budget] - Max ids returned.
* @param {number} [options.viewW] - Viewport width (CSS px).
* @param {number} [options.viewH] - Viewport height (CSS px).
* @param {number} [options.cols]
* @param {number} [options.rows]
* @returns {string[]} Winner ids in priority order (cell winners, then
* global-rank fill).
*/
export function distributeCctvCards(candidates, {
budget = CCTV_AMBIENT_CARD_MAX,
viewW = 0,
viewH = 0,
cols = CCTV_CARD_GRID_COLS,
rows = CCTV_CARD_GRID_ROWS,
} = {}) {
const cap = Number.isFinite(budget) ? Math.max(0, Math.floor(budget)) : 0;
const valid = (Array.isArray(candidates) ? candidates : [])
.filter((c) => c && typeof c.id === 'string' && c.id
&& Number.isFinite(c.sx) && Number.isFinite(c.sy));
if (!cap || !valid.length) return [];
const validViewport = hasFiniteCctvViewport(viewW, viewH);
const width = validViewport ? viewW : 1;
const height = validViewport ? viewH : 1;
const nCols = Math.max(1, Math.floor(cols));
const nRows = Math.max(1, Math.floor(rows));
const byRank = (a, b) => (Number.isFinite(a.rankKm) ? a.rankKm : Infinity)
- (Number.isFinite(b.rankKm) ? b.rankKm : Infinity)
|| a.id.localeCompare(b.id);
/** @type {Map<number, Array>} occupied cell -> its candidates */
const cells = new Map();
for (const candidate of valid) {
const col = Math.min(nCols - 1, Math.max(0, Math.floor((candidate.sx / width) * nCols)));
const row = Math.min(nRows - 1, Math.max(0, Math.floor((candidate.sy / height) * nRows)));
const key = row * nCols + col;
const bucket = cells.get(key);
if (bucket) bucket.push(candidate);
else cells.set(key, [candidate]);
}
const cellBest = [];
const rest = [];
for (const bucket of cells.values()) {
bucket.sort(byRank);
cellBest.push(bucket[0]);
for (let i = 1; i < bucket.length; i++) rest.push(bucket[i]);
}
cellBest.sort(byRank);
rest.sort(byRank);
const picked = cellBest.slice(0, cap);
for (const candidate of rest) {
if (picked.length >= cap) break;
picked.push(candidate);
}
return picked.map((candidate) => candidate.id);
}
/**
* Selects the ambient card cameras from already projected in-view
* candidates: nearest-first up to the zoom budget. Static image cameras
* only — video cameras stay icon-only until explicitly activated (the frame
* endpoint pacing is built for stills), and the ACTIVE camera is excluded
* upstream by the caller (its monitor plane is the richer representation).
* Cameras in `incumbentIds` (current card holders) rank with the 20%
* incumbency discount (finding 4) so the ring changes gradually.
*
* When the caller supplies viewport dimensions (`viewW`/`viewH`) and screen
* anchors (`sx`/`sy` per candidate), ranking blends eye distance with
* screen-center offset before the existing screen-distribution pass. Without
* screen info the original nearest-first cap applies unchanged.
*
* @param {Array<{id:string,distanceKm:number,inView:boolean,isVideo?:boolean,sx?:number,sy?:number}>} candidates
* @param {Object} [options]
* @param {number} [options.cameraHeightM]
* @param {Iterable<string>|Set<string>} [options.incumbentIds]
* @param {number} [options.viewW] - Viewport width (CSS px) — enables the
* screen-distribution pass.
* @param {number} [options.viewH] - Viewport height (CSS px).
* @returns {{cardIds:string[],budgets:{cardLimit:number}}}
*/
export function selectCctvLod(candidates, { cameraHeightM, incumbentIds, viewW, viewH } = {}) {
const budgets = cctvLodBudgets(cameraHeightM);
const incumbents = incumbentIds instanceof Set ? incumbentIds : new Set(incumbentIds || []);
const screened = hasFiniteCctvViewport(viewW, viewH);
if (!screened) {
// Preserve the pre-refinement nearest-first path byte-for-behavior,
// including its acceptance of any non-empty string ID. The stricter
// valid-viewport rules below must not leak into this compatibility branch.
const inView = (Array.isArray(candidates) ? candidates : [])
.filter((candidate) => candidate && typeof candidate.id === 'string' && candidate.id)
.map((candidate) => ({
id: candidate.id,
distanceKm: Number.isFinite(candidate.distanceKm) ? Math.max(0, candidate.distanceKm) : Infinity,
rankKm: incumbentRankKm(candidate.distanceKm, incumbents.has(candidate.id)),
inView: candidate.inView === true,
isVideo: candidate.isVideo === true,
}))
.filter((candidate) => candidate.inView)
.sort((a, b) => (
a.rankKm - b.rankKm
|| a.distanceKm - b.distanceKm
|| a.id.localeCompare(b.id)
));
const cardIds = [];
const seen = new Set();
for (const candidate of inView) {
if (candidate.isVideo || seen.has(candidate.id)) continue;
cardIds.push(candidate.id);
seen.add(candidate.id);
if (cardIds.length >= budgets.cardLimit) break;
}
return { cardIds, budgets };
}
const eligibleById = new Map();
for (const candidate of Array.isArray(candidates) ? candidates : []) {
if (!candidate || typeof candidate.id !== 'string' || !candidate.id.trim()
|| candidate.inView !== true || candidate.isVideo === true
|| !Number.isFinite(candidate.distanceKm)) continue;
const normalized = {
id: candidate.id,
distanceKm: Math.max(0, candidate.distanceKm),
rankKm: Infinity,
sx: Number.isFinite(candidate.sx) ? candidate.sx : NaN,
sy: Number.isFinite(candidate.sy) ? candidate.sy : NaN,
};
const current = eligibleById.get(normalized.id);
if (!current || compareCctvRepresentative(normalized, current, { screened, viewW, viewH }) < 0) {
eligibleById.set(normalized.id, normalized);
}
}
// Only rankable, still-image, in-view, deduplicated candidates influence the
// robust distance scale or consume a bounded ambient-card slot.
const stills = [...eligibleById.values()];
const spreadKm = cctvCandidateSpreadKm(stills.map((candidate) => candidate.distanceKm));
for (const candidate of stills) {
const blendedKm = blendCenterRankKm(
candidate.distanceKm,
screenCenterFraction(candidate.sx, candidate.sy, viewW, viewH),
spreadKm,
);
candidate.rankKm = incumbentRankKm(blendedKm, incumbents.has(candidate.id));
}
stills.sort((a, b) => (
a.rankKm - b.rankKm
|| a.distanceKm - b.distanceKm
|| a.id.localeCompare(b.id)
));
let cardIds;
// Item C: screen-distributed fill. Candidates lacking screen anchors are
// dropped by the distribution pass; top up from the ranked pool
// (defensive — cctv.js always projects anchors for in-view candidates).
cardIds = distributeCctvCards(stills, { budget: budgets.cardLimit, viewW, viewH });
if (cardIds.length < budgets.cardLimit) {
const chosen = new Set(cardIds);
for (const candidate of stills) {
if (cardIds.length >= budgets.cardLimit) break;
if (!chosen.has(candidate.id)) cardIds.push(candidate.id);
}
}
return { cardIds, budgets };
}
function compareCctvRepresentative(a, b, { screened, viewW, viewH }) {
if (a.distanceKm !== b.distanceKm) return a.distanceKm < b.distanceKm ? -1 : 1;
if (screened) {
const centerDelta = screenCenterFraction(a.sx, a.sy, viewW, viewH)
- screenCenterFraction(b.sx, b.sy, viewW, viewH);
if (centerDelta) return centerDelta;
}
const ax = Number.isFinite(a.sx) ? a.sx : Infinity;
const bx = Number.isFinite(b.sx) ? b.sx : Infinity;
if (ax !== bx) return ax < bx ? -1 : 1;
const ay = Number.isFinite(a.sy) ? a.sy : Infinity;
const by = Number.isFinite(b.sy) ? b.sy : Infinity;
if (ay !== by) return ay < by ? -1 : 1;
return 0;
}
export const CCTV_LOD_GRACE_PASSES = 2;
export const CCTV_LOD_GRACE_MS = 5_000;
/**
* Eviction-grace hysteresis for the ambient card set (Part C review finding
* P2, kept verbatim).
*
* Raw per-pass selection has no memory: a camera sitting at the edge of the
* card budget churns in/out on every small camera move, blinking its card
* while orbiting. This planner keeps an already-built card alive for a short
* grace window after it falls out of the selection — it is only dropped once
* it STAYS unselected for `gracePasses` consecutive selection passes or
* `graceMs` of wall time, whichever is crossed first. A newly selected
* camera always enters immediately, and the hard `cardLimit` cap is never
* exceeded: when selected + graced cards would overflow the budget,
* grace-period cards are evicted first, oldest-in-grace first.
*
* Pure function: `graceState` is never mutated; the returned `graceState`
* replaces it for the next pass.
*
* @param {Object} [input]
* @param {string[]} [input.selectedIds] - This pass's selected card ids
* (already budget-capped, nearest-first — `selectCctvLod().cardIds` after
* declutter).
* @param {string[]} [input.builtIds] - Ids that currently have a live card.
* @param {Map<string,{misses:number,since:number}>} [input.graceState] - Prior
* pass's grace bookkeeping (id -> consecutive misses + first-miss timestamp).
* @param {number} [input.nowMs] - Current wall time in ms.
* @param {number} [input.cardLimit] - Hard cap on total kept cards.
* @param {number} [input.gracePasses] - Consecutive unselected passes tolerated.
* @param {number} [input.graceMs] - Max wall-time a card may linger in grace.
* @returns {{keepIds:string[], evictIds:string[], graceState:Map<string,{misses:number,since:number}>}}
*/
export function applyEvictionGrace({
selectedIds = [],
builtIds = [],
graceState = new Map(),
nowMs = 0,
cardLimit = CCTV_AMBIENT_CARD_MAX,
gracePasses = CCTV_LOD_GRACE_PASSES,
graceMs = CCTV_LOD_GRACE_MS,
} = {}) {
const selectedSet = new Set(selectedIds);
const keepIds = [...selectedSet];
const evictIds = [];
const nextGrace = new Map();
const graced = [];
for (const id of builtIds) {
if (typeof id !== 'string' || !id || selectedSet.has(id)) continue;
const prior = graceState.get(id);
const misses = (prior?.misses || 0) + 1;
const since = Number.isFinite(prior?.since) ? prior.since : nowMs;
if (misses > gracePasses || nowMs - since >= graceMs) {
evictIds.push(id);
} else {
graced.push({ id, misses, since });
}
}
// Under cap pressure the grace-period cards go first, oldest-in-grace
// first (they have had the longest chance to return); ties break on more
// misses, then id for determinism.
graced.sort((a, b) => a.since - b.since || b.misses - a.misses || a.id.localeCompare(b.id));
const capacity = Math.max(0, cardLimit - keepIds.length);
const overflow = Math.max(0, graced.length - capacity);
for (let i = 0; i < graced.length; i++) {
if (i < overflow) {
evictIds.push(graced[i].id);
continue;
}
keepIds.push(graced[i].id);
nextGrace.set(graced[i].id, { misses: graced[i].misses, since: graced[i].since });
}
return { keepIds, evictIds, graceState: nextGrace };
}
/**
* Returns the source-aware static-frame refresh cadence. An explicit source
* value wins, bounded to one minute through twenty minutes; otherwise known
* public-pack cadences provide conservative defaults.
*
* @param {Object} camera
* @returns {number}
*/
export function staticFrameRefreshMs(camera) {
const explicit = Number(camera?.frameRefreshMs);
if (Number.isFinite(explicit) && explicit > 0) {
return Math.max(60_000, Math.min(20 * 60 * 1000, Math.round(explicit)));
}
const provider = String(camera?.provider || '').trim().toLowerCase();
return PROVIDER_STATIC_REFRESH_MS[provider] || DEFAULT_STATIC_REFRESH_MS;
}