Files
gods-eye-view/src/data/cctv.js
T

4826 lines
193 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 cctv
*
* CCTV camera data layer for God's Eye View.
*
* Architecture:
* - Camera catalog: built from seed definitions (CAMERA_SEEDS) merged with live
* sources fetched from the backend (/api/cctv/sources). Each camera record
* holds a base pose, a calibration offset, computed intrinsics/extrinsics,
* and an anchor position on the globe.
*
* - Coverage geometry (v2): a true pitched frustum pyramid per camera — 4
* corner rays from the mount to the far-plane corners plus the closed
* far-plane rectangle (5 polylines), rendered as Cesium entities with
* neighbor-limited visibility. All geometry is pure pose math
* (computeFrustumGeometry) — zero steady-state scene queries.
*
* - Monitor plane (v2): the live frame renders on a plane entity capping the
* far end of the frustum ("monitor at the end of the cone"), oriented
* perpendicular to the view axis (static — never billboarded). Video feeds
* bind the HTMLVideoElement directly (Cesium updates video textures
* per-frame); image feeds alternate two offscreen canvases so the texture
* re-uploads on every repaint tick (<=1Hz). One live plane at a time. On
* activation a single scene.pickFromRay obstruction probe (§9.1 — the ONLY
* raycast in the subsystem) clamps the plane's range short of the first
* tile hit so the end cap never clips into buildings.
*
* - Ambient card tier (2026-07-29 design): the LOD-selected nearby static
* cameras (cctvLod.js — zoom-scaled 16/24/32 budget, eviction grace)
* additionally get a screen-space thumbnail card (cctvCards.js) showing
* their latest paced static frame. Reselection is camera.moveEnd-driven
* (never per frame); frame fetches go through a global 1-per-second gate;
* camera icons stay visible at every zoom (cards annotate, never replace).
* The active camera keeps the monitor plane and is excluded from the card
* ring by default. An opt-in presentation option can also publish its
* protected thumbnail without changing the ambient quota.
*
* - Health sync: periodic fetch of /api/cctv/health to update per-camera
* source status shown in the UI.
*
* - Auto-hop: timed camera cycling with view-context awareness (snaps to
* nearest camera when the viewer pans to a new region).
*
* All mutable state is module-scoped. The exported `cctvLayer` object
* implements the standard layer interface (init/enable/disable/update/destroy)
* plus CCTV-specific methods (selectCamera, cycleCamera, focusNearest, etc.).
*/
import * as Cesium from 'cesium';
import { registerSpriteCollection, restoreSpriteOrder } from './spriteOrder.js';
import {
CCTV_ACTIVATION_RESULT,
activateCctvCameraFromWorldClick,
} from '../cctvFocusRequest.js';
import { bindTrackingClickGesture, isTrackingClickGesture } from './trackingClickGesture.js';
import {
clearOverlaySource,
hitTestWorldOverlay,
setOverlayEntries,
setOverlaySourceVisible,
} from '../overlays/worldOverlay.js';
import { CITY_POIS } from '../locations.js';
import {
registerPickOwner,
resolvePickId,
unregisterPickOwner,
} from './pickRegistry.js';
import { resolveEllipsoidalGround } from './terrainHeights.js';
import { cachedGroundFloor, resolveGroundFloorCells, warmGroundFloor } from './groundFloor.js';
import { sampleMeshFloorCells } from './meshFloorSampler.js';
import { horizonOccluder } from './iconOrientation.js';
import { cameraHue, viewshedColors, createFrustumVolumePrimitive } from './cctvViewshed.js';
import { createCalibrationGizmo, GIZMO_ID_PREFIX } from './cctvGizmo.js';
import {
CCTV_AMBIENT_CARD_MAX,
applyEvictionGrace,
selectCctvLod,
staticFrameRefreshMs,
} from './cctvLod.js';
import {
CCTV_CARD_FETCH_BURST_LIMIT,
CCTV_CARD_FETCH_BURST_SPACING_MS,
CCTV_FRAME_CANVAS_W,
CCTV_FRAME_CANVAS_H,
applyFrameResult,
cardFetchPolicy,
createCctvThumbnailOverlayEntry,
createFrameSlot,
declutterCctvCards,
CCTV_OVERLAY_SOURCE_ID,
planFrameCachePrune,
frameFetchDue,
} from './cctvCards.js';
import {
advanceSpriteFocus,
focusAlphaNeedsWrite,
focusNowMs,
focusPassIsNeeded,
getFocusTarget,
onFocusTargetAppear,
} from './focusDeemphasis.js';
import { holdContinuousRender, releaseContinuousRender } from '../renderGovernor.js';
// ---------------------------------------------------------------------------
// API endpoints
// ---------------------------------------------------------------------------
const FRAME_ENDPOINT = '/api/cctv/frame';
const SOURCE_ENDPOINT = '/api/cctv/sources';
const HEALTH_ENDPOINT = '/api/cctv/health';
const MEDIA_ENDPOINT = '/api/cctv/media';
// ---------------------------------------------------------------------------
// Timing and geometry constants
// ---------------------------------------------------------------------------
const DEFAULT_UPDATE_INTERVAL_MS = 10000;
const MIN_AUTO_HOP_SEC = 8;
const MAX_AUTO_HOP_SEC = 90;
const HEALTH_SYNC_INTERVAL_MS = 7000;
const ACTIVE_FRAME_REFRESH_MS = 10000;
const IDLE_FRAME_REFRESH_MS = 60000;
const PROJECTION_ACTIVE_REFRESH_MS = 10000;
const PROJECTION_IDLE_REFRESH_MS = 60000;
const PROJECTION_CANVAS_WIDTH = 1920;
const PROJECTION_CANVAS_HEIGHT = 1080;
// Downsample grid for the unchanged-frame signature (drawProjectionFrame).
// 64x36 keeps the 16:9 aspect and reads ~9 KB per check versus the 8.3 MB a
// full-resolution compare would touch.
const FRAME_SIGNATURE_W = 64;
const FRAME_SIGNATURE_H = 36;
const COVERAGE_NEIGHBOR_LIMIT = 14;
const COVERAGE_NEIGHBOR_RADIUS_KM = 1.8;
// Staggered geometry/frame loading: ground-sampled coverage geometry is
// refined in small batches (active camera first, then nearest-to-viewer) so
// enabling the layer never raycasts every camera in a single frame.
const GEO_LOAD_BATCH_SIZE = 4;
const GEO_LOAD_BATCH_DELAY_MS = 120;
const GEO_TRACKING_BATCH_SIZE = 2;
const GEO_TRACKING_BATCH_DELAY_MS = 250;
const GEO_PROGRESS_NOTIFY_INTERVAL_MS = 300;
const GEO_PROGRESS_NOTIFY_BATCH_LIMIT = 10;
// Throttle for placeholder repaints — the projection RAF loop must not
// re-fill a 1080p canvas on every frame while a feed image is still loading.
const PLACEHOLDER_REPAINT_MS = 750;
// v1 key is retired dead data (product rule #3, §9.3 — WIPE CLEAN, no
// legacy import): kept here only as a documented constant so nothing ever
// re-reads it by accident. Exported for the unit suite's "v1 is ignored"
// assertion; there is NO read path for this key anywhere in the module.
export const CCTV_CALIBRATION_STORAGE_KEY_V1 = 'godsEyeView.cctv.calibration.v1';
/** v2 store key. Entries: { values: <7-field calibration offsets>, source: 'manual', savedAt: <epoch ms> }. */
export const CCTV_CALIBRATION_STORAGE_KEY_V2 = 'godsEyeView.cctv.calibration.v2';
// H5: throttle for double-buffered canvas texture swaps (<=1Hz; each swap is a
// full 1080p texture re-upload because Cesium re-uploads only on a NEW image
// object reference).
const PROJECTION_TEXTURE_SWAP_MS = 1000;
const PROJECTION_VERT_ASPECT = PROJECTION_CANVAS_WIDTH / PROJECTION_CANVAS_HEIGHT;
// V2 frustum geometry (design §2a/§6): the far-cap center + corners never sink
// below groundAlt + this clearance, so a fabricated pitch (-24°) cannot bury
// the monitor plane in the 3D tiles. Exported for the unit suite.
export const FRUSTUM_GROUND_CLEARANCE_M = 2;
/** Public result codes for explicit CCTV camera flights. */
export const CCTV_FOCUS_RESULT = Object.freeze({
FOCUSED: 'focused',
NO_ACTIVE_CAMERA: 'no-active-camera',
TRACKING_HOLDS_VIEW: 'tracking-holds-view',
COCKPIT_ACTIVE: 'cockpit-active',
});
// §9.1 activation obstruction probe: clamp the plane's effective range to just
// short of the first pickFromRay hit along the frustum axis, with a floor so a
// point-blank obstruction never collapses the frustum to zero. The floor is
// the old H6 monitor's 8-15 m distance band: small enough that a pitched-down
// camera whose axis meets the street ~25 m out still clamps SHORT of the hit
// (a larger floor would push the plane back through the obstruction).
const PROBE_CLEARANCE_M = 4;
const PROBE_MIN_RANGE_M = 12;
// Bounded wait for the enable-time ground-prior batch: warm proxy disk cache
// resolves in milliseconds; a cold/slow upstream must never hang layer init,
// so past this budget init proceeds on catalog fallbacks and the batch applies
// post-hoc (applyLateGroundPriors) when it lands.
const GROUND_PRIOR_INIT_WAIT_MS = 8000;
/** Default calibration offsets — all zeroed, range scale 1x. */
const DEFAULT_CAMERA_CALIBRATION = Object.freeze({
offsetNorthM: 0,
offsetEastM: 0,
headingDeg: 0,
pitchDeg: 0,
fovDeg: 0,
rangeScale: 1,
heightM: 0,
});
/**
* Returns whether a calibration patch moves the camera's ground anchor.
* Rotational, optical, range, and manual-height edits preserve the existing
* ground reference; only north/east translation needs a new floor.
* @param {Object|null|undefined} patch
* @returns {boolean}
*/
export function calibrationPatchMovesAnchor(patch) {
if (!patch || typeof patch !== 'object') return false;
return Object.prototype.hasOwnProperty.call(patch, 'offsetNorthM') ||
Object.prototype.hasOwnProperty.call(patch, 'offsetEastM');
}
/** Base64-encoded SVG camera icon for billboard rendering. */
const CAMERA_ICON = (() => {
const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36">
<defs>
<linearGradient id="lens" x1="0" y1="0" x2="1" y2="1">
<stop offset="0%" stop-color="#c9f6ff"/>
<stop offset="45%" stop-color="#6fd9ff"/>
<stop offset="100%" stop-color="#1a5f78"/>
</linearGradient>
</defs>
<g transform="translate(4 6)">
<rect x="0" y="8" width="20" height="9" rx="2.5" fill="#0e1720" stroke="#75e7ff" stroke-width="1.2"/>
<rect x="17" y="10" width="10" height="5" rx="1.5" fill="#132433" stroke="#75e7ff" stroke-width="1"/>
<circle cx="24" cy="12.5" r="3.1" fill="url(#lens)" stroke="#dbfbff" stroke-width="0.8"/>
<rect x="6.4" y="17" width="4.2" height="8.5" rx="1.2" fill="#10212d" stroke="#75e7ff" stroke-width="1"/>
<rect x="4.2" y="24" width="8.6" height="2.5" rx="1.1" fill="#0b151d" stroke="#4ecde7" stroke-width="0.8"/>
</g>
</svg>`;
return 'data:image/svg+xml;base64,' + btoa(svg);
})();
/**
* Seed camera definitions used when no live sources are available.
* Each seed references a city from CITY_POIS and a POI index within that city,
* plus offsets to place the camera near the POI.
*/
const CAMERA_SEEDS = [
{ id: 'nyc-midtown-w', cityId: 'nyc', poiIndex: 1, label: 'Midtown West @ 34th', offsetNorthM: 120, offsetEastM: -70, headingDeg: 206, fovDeg: 74, rangeM: 880, elevationM: 26 },
{ id: 'nyc-wtc-n', cityId: 'nyc', poiIndex: 2, label: 'WTC North Plaza', offsetNorthM: 95, offsetEastM: 34, headingDeg: 164, fovDeg: 68, rangeM: 760, elevationM: 32 },
{ id: 'nyc-times-square-ne', cityId: 'nyc', poiIndex: 1, label: 'Times Sq Northeast', offsetNorthM: 230, offsetEastM: 120, headingDeg: 218, fovDeg: 66, rangeM: 640, elevationM: 24 },
{ id: 'sf-market-5th', cityId: 'sf', poiIndex: 2, label: 'Market & 5th', offsetNorthM: -160, offsetEastM: 80, headingDeg: 320, fovDeg: 70, rangeM: 780, elevationM: 20 },
{ id: 'sf-financial-district', cityId: 'sf', poiIndex: 1, label: 'SF Financial Core', offsetNorthM: 110, offsetEastM: 52, headingDeg: 205, fovDeg: 72, rangeM: 760, elevationM: 24 },
{ id: 'tokyo-shibuya-scramble', cityId: 'tokyo', poiIndex: 4, label: 'Shibuya Crossing', offsetNorthM: 180, offsetEastM: 46, headingDeg: 18, fovDeg: 82, rangeM: 640, elevationM: 30 },
{ id: 'tokyo-ginza-core', cityId: 'tokyo', poiIndex: 0, label: 'Ginza Core', offsetNorthM: -180, offsetEastM: 150, headingDeg: 245, fovDeg: 70, rangeM: 690, elevationM: 28 },
{ id: 'tokyo-asakusa-n', cityId: 'tokyo', poiIndex: 3, label: 'Asakusa North Gate', offsetNorthM: 110, offsetEastM: -65, headingDeg: 192, fovDeg: 68, rangeM: 620, elevationM: 24 },
{ id: 'london-city-a1', cityId: 'london', poiIndex: 4, label: 'City Cluster A1', offsetNorthM: 80, offsetEastM: 65, headingDeg: 220, fovDeg: 71, rangeM: 720, elevationM: 27 },
{ id: 'london-soho-core', cityId: 'london', poiIndex: 2, label: 'Soho Core', offsetNorthM: 210, offsetEastM: 120, headingDeg: 206, fovDeg: 70, rangeM: 700, elevationM: 22 },
{ id: 'paris-rivoli', cityId: 'paris', poiIndex: 4, label: 'Rue de Rivoli', offsetNorthM: 55, offsetEastM: 85, headingDeg: 248, fovDeg: 66, rangeM: 640, elevationM: 22 },
{ id: 'paris-champs-n', cityId: 'paris', poiIndex: 1, label: 'Champs-Élysées North', offsetNorthM: 130, offsetEastM: -38, headingDeg: 175, fovDeg: 68, rangeM: 700, elevationM: 26 },
{ id: 'dc-mall-center', cityId: 'dc', poiIndex: 1, label: 'National Mall Center', offsetNorthM: 120, offsetEastM: 20, headingDeg: 258, fovDeg: 78, rangeM: 940, elevationM: 24 },
{ id: 'dc-pentagon-s', cityId: 'dc', poiIndex: 3, label: 'Pentagon South', offsetNorthM: -100, offsetEastM: 92, headingDeg: 14, fovDeg: 66, rangeM: 620, elevationM: 21 },
{ id: 'dubai-difc-loop', cityId: 'dubai', poiIndex: 4, label: 'DIFC Loop', offsetNorthM: 92, offsetEastM: -45, headingDeg: 196, fovDeg: 70, rangeM: 720, elevationM: 26 },
{ id: 'dubai-downtown-east', cityId: 'dubai', poiIndex: 0, label: 'Downtown East', offsetNorthM: -130, offsetEastM: 190, headingDeg: 322, fovDeg: 72, rangeM: 760, elevationM: 28 },
{ id: 'austin-congress-s', cityId: 'austin', poiIndex: 0, label: 'Congress Southbound', offsetNorthM: -165, offsetEastM: 40, headingDeg: 12, fovDeg: 74, rangeM: 760, elevationM: 24 },
{ id: 'austin-downtown-west', cityId: 'austin', poiIndex: 1, label: 'Downtown West', offsetNorthM: -120, offsetEastM: -160, headingDeg: 120, fovDeg: 69, rangeM: 700, elevationM: 20 },
];
// ---------------------------------------------------------------------------
// Visual style constants
// ---------------------------------------------------------------------------
const IDLE_CAMERA_COLOR = Cesium.Color.fromCssColorString('#6be8ff').withAlpha(0.88);
const ACTIVE_CAMERA_COLOR = Cesium.Color.fromCssColorString('#ffd97a').withAlpha(0.95);
const IDLE_COVERAGE_COLOR = Cesium.Color.fromCssColorString('#2fe0ff').withAlpha(0.24);
const IDLE_COVERAGE_CENTER_MUTED = Cesium.Color.fromCssColorString('#2fe0ff').withAlpha(0.2);
const IDLE_COVERAGE_EDGE_MUTED = Cesium.Color.fromCssColorString('#2fe0ff').withAlpha(0.18);
const ACTIVE_COVERAGE_EDGE = Cesium.Color.fromCssColorString('#8dff87').withAlpha(0.58);
const ACTIVE_COVERAGE_CENTER = Cesium.Color.fromCssColorString('#d7ff8d').withAlpha(0.82);
// H6: dimmer depth-fail materials let the active frustum wireframe read
// through buildings while in monitor fallback mode.
const ACTIVE_COVERAGE_EDGE_DEPTHFAIL = Cesium.Color.fromCssColorString('#8dff87').withAlpha(0.18);
const ACTIVE_COVERAGE_CENTER_DEPTHFAIL = Cesium.Color.fromCssColorString('#d7ff8d').withAlpha(0.26);
const PLANE_OUTLINE_COLOR = Cesium.Color.fromCssColorString('#6be8ff').withAlpha(0.55);
// ---------------------------------------------------------------------------
// Module-scoped mutable state
// ---------------------------------------------------------------------------
let _viewer = null;
let _billboards = null;
let _records = [];
let _recordById = new Map();
let _coverageEntities = [];
let _projectionEntities = [];
let _enabled = false;
let _activeCameraId = null;
let _coverageMode = 'on'; // 'off' | 'on' (wireframes) | 'viewshed' (color-coded volumes)
let _showProjection = true;
let _autoHop = false;
// An explicit empty-space deselect keeps AUTO HOP configured but prevents its
// timer from silently choosing a replacement. A later explicit activation or
// AUTO HOP toggle-on releases the hold.
let _autoHopSuspended = false;
let _autoHopSec = 18;
let _lastHopAt = 0;
let _lastViewContext = '';
let _clickHandler = null;
let _count = 0;
let _lastUpdate = null;
let _lastHealthSyncAt = 0;
let _lastError = null;
let _healthById = new Map();
let _calibrationById = new Map();
let _listeners = new Set();
let _projectionRaf = 0;
let _removeFocusAppearListener = null;
let _lastFocusStyleAt = 0;
/** Icons whose animated emphasis remains outside the 1.0 deadband. */
let _activeFocusStyleCount = 0;
const _scratchFocusScreen = new Cesium.Cartesian2();
// Staggered geometry-load queue state (see startGeometryLoadQueue).
let _geoQueue = [];
let _geoQueueTimer = 0;
let _geoLoading = false;
let _geoLoadTotal = 0;
let _geoLoadDone = 0;
let _geoProgressNotifier = null;
// One-shot completion latch for shared floor resolution: the enable-time queue
// can drain while DEM cells or 3D tiles are still loading. The first update()
// tick that sees projectionTilesReady() re-enqueues unresolved records ONCE;
// shared mesh cells remain one-shot and idle ticks stay sample-free. Reset by
// startGeometryLoadQueue so each enable-time drain gets its own completion pass.
let _tilesReadyReenqueued = false;
// Calibration ADJUST mode (viewshed/gizmo design §3c): while true, the active
// camera renders the direct-manipulation gizmo. Reset on layer disable.
let _calibrationMode = false;
let _gizmo = null;
let _lastTransientNotifyAt = 0;
// Cached handle on the active Google Photorealistic 3D Tileset, discovered
// lazily from scene.primitives. Shared mesh-floor sampling is gated on its
// tilesLoaded flag so a coarse-LOD miss is never baked in. Cleared when the
// tileset is destroyed / the layer tears down.
let _activeTileset = null;
// Task 5: last surface regime the record geometry was recomputed for. The
// map-stack change listener compares the CURRENT regime (derived live from
// scene.globe.show) against this so bing→osm switches (same 'terrain-globe'
// regime) don't trigger a pointless full-catalog rewrite.
let _lastAppliedRegime = null;
// Task 5: window listener handle for the 'gev:map-stack-changed' CustomEvent
// main.js dispatches from MapStackController's onChange (removed in destroy).
let _mapStackListener = null;
// Field-test fix (2026-07-06): camera.moveEnd handle for the horizon-culling
// pass (removed in destroy). Event-driven only — never a per-frame loop, so
// the zero-steady-state-work invariant holds.
let _horizonCullListener = null;
// Ambient card tier state (2026-07-29 design). The card set is rebuilt only
// on moveEnd/enable/activation (refreshAmbientCards); frame slots are STABLE
// objects shared with the overlay host so landed frames appear without an
// entry rebuild.
let _cardIds = new Set();
/** @type {Map<string,{misses:number,since:number}>} */
let _cardGraceState = new Map();
/** @type {Map<string,{frame:*, stamp:number, failCount:number, lastAttemptAt:number}>} */
let _cardFrameSlots = new Map();
let _cardFetchTimer = 0;
/** In-flight card-frame fetch count (burst allows up to 4, steady is 1). */
let _cardFetchInFlightCount = 0;
/** @type {Set<HTMLImageElement>} in-flight fetches, detached on teardown. */
const _cardFetchImages = new Set();
/** @type {Set<string>} camera ids with an in-flight fetch (no double-fetch). */
const _cardFetchPendingIds = new Set();
let _cardFetchCount = 0;
let _cardLastFetchAt = 0;
let _cardMinFetchSpacingMs = null;
/** Pacer mode telemetry: 'burst' during cold fill, 'steady' after. */
let _cardFetchMode = 'steady';
/**
* Card budget while the staggered geometry drain is running — the raised
* 20/28/40 tiers resume when loading completes (see refreshAmbientCards).
*/
const CCTV_AMBIENT_CARD_DRAIN_CAP = 16;
// Global static-frame pacing (field finding 3): the pacer ticks at the burst
// spacing (250 ms) but cardFetchPolicy gates launches — cold fill (selected
// cards still missing their FIRST frame) allows up to 4 in-flight fetches at
// 250 ms spacing; steady state keeps the salvaged Part C gate of at most one
// request per second with an in-flight fetch blocking the tick, so slow
// responses only lower the rate.
const CARD_FETCH_TICK_MS = CCTV_CARD_FETCH_BURST_SPACING_MS;
// In-view margin so cards whose anchors sit just beyond an edge don't churn
// while the operator makes minor camera adjustments (Part C recordIsInView).
const CARD_VIEW_MARGIN = 0.06;
/** Card leader gap: clears the 24px icon (12px half + breathing room). */
const CARD_GAP_PX = 16;
const CCTV_OVERLAY_SOURCE_OPTIONS = Object.freeze({
cohortLimit: CCTV_AMBIENT_CARD_MAX,
collisionCapacity: CCTV_AMBIENT_CARD_MAX,
moving: true,
solveIntervalMs: 125,
});
export const CCTV_PROJECTION_OVERLAY_SOURCE_ID = 'cctv-projection';
export const CCTV_PROJECTION_OVERLAY_SOURCE_OPTIONS = Object.freeze({
cohortLimit: 1,
collisionCapacity: 0,
moving: false,
});
const DEFAULT_CCTV_OVERLAY_HOST = Object.freeze({
clearSource: clearOverlaySource,
hitTest: hitTestWorldOverlay,
setEntries: setOverlayEntries,
setVisible: setOverlaySourceVisible,
});
let _cctvOverlayHost = DEFAULT_CCTV_OVERLAY_HOST;
let _projectionOverlayOwnerId = null;
/**
* Product presentation option. Shipped behavior keeps the active camera's
* thumbnail absent because its monitor plane is the active representation.
*/
let _activeCameraCardEnabled = false;
// Hover-summoned card (follow-up round 2, item B): pointing at a cardless camera
// icon shows its card immediately as a PINNED entry (budget-exempt, top
// draw-pass declutter priority).
/** Min spacing between hover scene.pick calls (event-driven, user gesture). */
const HOVER_PICK_THROTTLE_MS = 120;
/** How long the hover card lingers after the pointer leaves the icon. */
const HOVER_RELEASE_MS = 1_000;
/** Camera id currently holding the hover-summoned pinned card (or null). */
let _hoverCardId = null;
let _hoverReleaseTimer = 0;
let _hoverLastPickAt = 0;
/** Test seam: republishes host entries through the real push path, so tests
* can observe the pristine module default without touching the setter. */
export function _pushAmbientCardEntriesForTest() {
pushAmbientCardEntries();
}
/** Test seam for exercising real layer lifecycle paths without a DOM host. */
export function _setCctvOverlayHostForTest(host = null) {
_cctvOverlayHost = host ? { ...DEFAULT_CCTV_OVERLAY_HOST, ...host } : DEFAULT_CCTV_OVERLAY_HOST;
_projectionOverlayOwnerId = null;
}
/**
* Build the protected label associated with one active monitor plane.
* @param {{cameraId: string, name: string, position: Cesium.Cartesian3|Function}} input
* @returns {Object} Shared-host presentation entry.
*/
export function createCctvProjectionOverlayEntry({ cameraId, name, position }) {
return {
id: String(cameraId),
position,
variant: 'selected',
selected: true,
protected: true,
paintLane: 'selected',
collisionGroup: 'ambient-card',
priority: Number.MAX_SAFE_INTEGER - 1,
title: String(name || cameraId || 'CAMERA'),
details: [],
accent: '#6be8ff',
interactive: false,
gapPx: 6,
verticalOnly: true,
placement: 'above',
edgeFade: 'keyhole',
horizonCull: true,
terrainOcclusion: false,
};
}
/**
* Configures optional CCTV card presentation without changing card density.
* The active-camera thumbnail defaults OFF, preserving the shipped behavior
* where the monitor plane is the camera's sole active representation.
*
* @param {Object} [options]
* @param {boolean} [options.activeCameraCardEnabled=false]
* @returns {{activeCameraCardEnabled:boolean}}
*/
export function setCctvCardPresentationOptions({ activeCameraCardEnabled = false } = {}) {
_activeCameraCardEnabled = activeCameraCardEnabled === true;
if (_enabled) pushAmbientCardEntries();
_viewer?.scene?.requestRender?.();
return { activeCameraCardEnabled: _activeCameraCardEnabled };
}
// True between camera.moveStart and moveEnd — hover picking pauses while the
// camera is in motion (picks during a flight would fight the reselection).
let _cameraMoving = false;
let _moveStartListener = null;
/**
* Converts degrees to radians.
* @param {number} deg
* @returns {number}
*/
function toRad(deg) {
return Cesium.Math.toRadians(deg);
}
/**
* Normalizes a heading angle to the [0, 360) range.
* @param {number} deg
* @returns {number}
*/
function normalizeHeading(deg) {
let v = deg % 360;
if (v < 0) v += 360;
return v;
}
/**
* Clamps a value to [min, max].
* @param {number} value
* @param {number} min
* @param {number} max
* @returns {number}
*/
function clamp(value, min, max) {
return Math.max(min, Math.min(max, value));
}
/**
* Normalizes an angle to the (-180, 180] range.
* @param {number} deg
* @returns {number}
*/
function normalizeSignedAngle(deg) {
let value = deg % 360;
if (value > 180) value -= 360;
if (value <= -180) value += 360;
return value;
}
/**
* Returns the absolute angular difference between two headings in degrees.
* @param {number} aDeg
* @param {number} bDeg
* @returns {number} Value in [0, 180].
*/
function angularDeltaAbs(aDeg, bDeg) {
return Math.abs(normalizeSignedAngle(aDeg - bDeg));
}
/**
* Task 5 (height-datum fix): maps the scene's `globe.show` flag to the surface
* regime key the per-camera ground cache is keyed by (spec §2 "cache by
* surface regime", collapsed to two keys — ion World Terrain and Re:Earth
* globe terrain get the same handling):
*
* - `google-3d` — photoreal stack: globe hidden, the visible Google 3D
* tileset IS the surface → one-shot scene sampling refines.
* - `terrain-globe` — any globe stack: the Re:Earth point-height prior IS the
* resolution (zero scene queries).
*
* Only an explicit `false` (the photoreal stack hides the globe) selects
* `google-3d`; undefined/null (no viewer / torn down) must fall to the regime
* that never touches the scene. Pure — exported for the unit suite.
* @param {boolean|undefined|null} globeShow - `viewer.scene.globe.show`.
* @returns {'google-3d'|'terrain-globe'}
*/
export function surfaceRegimeKey(globeShow) {
return globeShow === false ? 'google-3d' : 'terrain-globe';
}
/**
* Normalizes a raw feed-type string to a canonical type (image, mjpeg, mp4, hls, webm).
* @param {string|*} value - Raw feed type from source config.
* @returns {string} Canonical feed type.
*/
function normalizeFeedType(value) {
const raw = String(value || '').trim().toLowerCase();
if (!raw) return 'image';
if (raw === 'mjpg') return 'mjpeg';
if (raw === 'jpeg') return 'image';
if (raw === 'jpg') return 'image';
if (raw === 'video') return 'mp4';
if (raw === 'stream') return 'hls';
if (raw === 'png') return 'image';
if (raw === 'gif') return 'image';
return raw;
}
/**
* Returns true if the feed type requires a <video> element rather than an <img>.
* @param {string} feedType
* @returns {boolean}
*/
function isVideoFeedType(feedType) {
return feedType === 'mp4' || feedType === 'hls' || feedType === 'webm';
}
/**
* Coerces a value to a finite number or returns the fallback.
* @param {*} value
* @param {number} [fallback=NaN]
* @returns {number}
*/
function safeNumber(value, fallback = NaN) {
const n = Number(value);
return Number.isFinite(n) ? n : fallback;
}
/**
* Derives a deterministic heading from a camera ID string via a simple hash.
* Produces one of 16 evenly-spaced headings (0, 22.5, 45, ..., 337.5).
* @param {string} id
* @returns {number} Heading in degrees [0, 360).
*/
function headingFromId(id) {
const text = String(id || '');
let acc = 0;
for (let i = 0; i < text.length; i++) {
acc = (acc * 33 + text.charCodeAt(i)) >>> 0;
}
return normalizeHeading((acc % 16) * 22.5);
}
/**
* Rounds a value to the nearest multiple of `step`.
* @param {number} value
* @param {number} [step=0.1]
* @returns {number}
*/
function quantize(value, step = 0.1) {
return Math.round(value / step) * step;
}
/**
* Sanitizes and clamps a calibration object to valid ranges.
* Missing or non-finite fields fall back to defaults.
* @param {Object} [value={}] - Raw calibration values.
* @returns {{ offsetNorthM: number, offsetEastM: number, headingDeg: number, pitchDeg: number, fovDeg: number, rangeScale: number, heightM: number }}
*/
function normalizeCalibration(value = {}) {
const raw = value && typeof value === 'object' ? value : {};
return {
offsetNorthM: quantize(clamp(safeNumber(raw.offsetNorthM, 0), -900, 900), 0.1),
offsetEastM: quantize(clamp(safeNumber(raw.offsetEastM, 0), -900, 900), 0.1),
headingDeg: quantize(clamp(safeNumber(raw.headingDeg, 0), -180, 180), 0.1),
pitchDeg: quantize(clamp(safeNumber(raw.pitchDeg, 0), -45, 45), 0.1),
fovDeg: quantize(clamp(safeNumber(raw.fovDeg, 0), -50, 50), 0.1),
rangeScale: quantize(clamp(safeNumber(raw.rangeScale, 1), 0.35, 3.0), 0.01),
heightM: quantize(clamp(safeNumber(raw.heightM, 0), -120, 240), 0.1),
};
}
/**
* Returns true if the given calibration is effectively the default (all offsets near zero).
* @param {Object} calibration
* @returns {boolean}
*/
function isDefaultCalibration(calibration) {
const probe = normalizeCalibration(calibration);
return Object.keys(DEFAULT_CAMERA_CALIBRATION).every((key) => Math.abs(probe[key] - DEFAULT_CAMERA_CALIBRATION[key]) < 0.0001);
}
/**
* Normalizes a coverage-mode request (viewshed design §3b). Accepts the three
* mode strings plus booleans for `setParams({showCoverage})` back-compat
* (true → 'on', false → 'off'); anything else keeps the current mode.
* @param {*} value - Requested mode ('off'|'on'|'viewshed') or boolean.
* @param {'off'|'on'|'viewshed'} current - Mode to keep when the request is invalid.
* @returns {'off'|'on'|'viewshed'}
*/
export function normalizeCoverageMode(value, current) {
if (value === true) return 'on';
if (value === false) return 'off';
if (value === 'off' || value === 'on' || value === 'viewshed') return value;
return current;
}
/**
* Converts north/east metre offsets to lat/lon degree deltas at a given latitude.
* Uses the equirectangular approximation (111320 m/deg).
* @param {number} latDeg - Reference latitude (degrees).
* @param {number} northMeters - Offset northward (metres).
* @param {number} eastMeters - Offset eastward (metres).
* @returns {{ latOffset: number, lonOffset: number }} Degree deltas.
*/
function offsetDegrees(latDeg, northMeters, eastMeters) {
const latOffset = northMeters / 111320;
const lonDivisor = Math.max(0.15, Math.cos(toRad(latDeg)));
const lonOffset = eastMeters / (111320 * lonDivisor);
return { latOffset, lonOffset };
}
/**
* Returns `window.localStorage` when it is safely accessible, else null.
* Split out so store IO can be exercised under plain node:test with an
* injected storage-like object (getItem/setItem/removeItem) instead.
* @returns {Storage|null}
*/
function safeWindowLocalStorage() {
if (typeof window === 'undefined') return null;
try {
// NB: the window.localStorage property ACCESS itself throws SecurityError
// under "block all cookies", so it has to live inside the try (M11).
return window.localStorage || null;
} catch {
return null;
}
}
/**
* Loads all persisted per-camera calibration overrides from the v2 store.
*
* v2 entries carry provenance: `{ values: <7-field offsets>, source: 'manual',
* savedAt: <epoch ms> }`. The v1 key (`CCTV_CALIBRATION_STORAGE_KEY_V1`) is
* NEVER read here — product rule #3 (§9.3): wipe clean, no legacy import.
*
* @param {{getItem:function}|null} [storage] - Injectable storage (defaults
* to `window.localStorage`); lets the unit suite test this pure of a DOM.
* @returns {Map<string, {values:Object, source:string, savedAt:number}>}
*/
export function readCalibrationStoreV2(storage = safeWindowLocalStorage()) {
const map = new Map();
if (!storage) return map;
try {
const raw = storage.getItem(CCTV_CALIBRATION_STORAGE_KEY_V2);
if (!raw) return map;
const parsed = JSON.parse(raw);
if (!parsed || typeof parsed !== 'object') return map;
for (const [cameraId, entry] of Object.entries(parsed)) {
if (!cameraId || !entry || typeof entry !== 'object') continue;
if (!entry.values || typeof entry.values !== 'object') continue;
// 'manual' is the only provenance v2 knows (§9.3 killed 'legacy'); a
// malformed/foreign source string still normalizes to 'manual' rather
// than surfacing an unrecognized value into the badge logic.
map.set(cameraId, {
values: normalizeCalibration(entry.values),
source: 'manual',
savedAt: safeNumber(entry.savedAt, 0),
});
}
return map;
} catch {
return map;
}
}
/**
* Persists a calibration map to the v2 store.
* @param {Map<string, {values:Object, source:string, savedAt:number}>} map
* @param {{setItem:function}|null} [storage] - Injectable storage (defaults
* to `window.localStorage`).
*/
export function writeCalibrationStoreV2(map, storage = safeWindowLocalStorage()) {
if (!storage) return;
try {
const payload = {};
for (const [cameraId, entry] of map.entries()) {
payload[cameraId] = {
values: normalizeCalibration(entry.values),
source: 'manual',
savedAt: safeNumber(entry.savedAt, Date.now()),
};
}
storage.setItem(CCTV_CALIBRATION_STORAGE_KEY_V2, JSON.stringify(payload));
} catch {
// storage unavailable
}
}
/**
* Loads the v2 calibration store. `_calibrationById` holds these entries
* directly (`{values, source:'manual', savedAt}`) — never bare offset values
* — so it round-trips straight back through `writeCalibrationStoreV2`.
* @returns {Map<string, {values:Object, source:string, savedAt:number}>}
*/
function loadCalibrationStore() {
return readCalibrationStoreV2();
}
/** Persists the in-memory calibration entries (values + provenance) to the v2 store. */
function saveCalibrationStore() {
writeCalibrationStoreV2(_calibrationById);
}
/**
* Derives the panel CAL badge state for a camera (design §3b, as amended by
* the LOCKED §9.2 — panel-only, no in-world tint).
*
* Three states:
* - 'calibrated' — a human explicitly saved a v2 calibration (`source:'manual'`).
* - 'curated' — no manual save, but the catalog entry was hand-authored
* (`poseSource:'curated'`, file/env sources only).
* - 'raw-prior' — everything else (all Austin Open Data today).
*
* Pure — no scoring math, no raycasts. `confidenceFromScore` and score-based
* quality seeding are retired; this replaces them.
* @param {{calSource?: string|null, poseSource?: string|null}} camera
* @returns {'calibrated'|'curated'|'raw-prior'}
*/
export function deriveCalBadge(camera) {
if (camera?.calSource === 'manual') return 'calibrated';
if (camera?.poseSource === 'curated') return 'curated';
return 'raw-prior';
}
/**
* Initializes or recomputes a camera's derived pose fields from its base pose
* and calibration offsets. Also sets intrinsics, extrinsics, and anchor.
*
* On first call for a camera, captures the raw values as `basePose`.
* Subsequent calls re-derive lat/lon/heading/pitch/fov/range by applying
* calibration deltas to the frozen base pose.
*
* Note: the old score-based quality system (`confidenceFromScore`, seeded
* `camera.quality.score`) is retired — panel trust signal is now the 3-state
* CAL badge (`deriveCalBadge`, driven by `calSource`/`poseSource`), not a
* fabricated confidence score.
*
* @param {Object} camera - Mutable camera record.
*/
function ensureCameraPose(camera) {
if (!camera) return;
if (!camera.basePose) {
camera.basePose = {
lat: safeNumber(camera.lat, 0),
lon: safeNumber(camera.lon, 0),
headingDeg: normalizeHeading(safeNumber(camera.headingDeg, 0)),
pitchDeg: clamp(safeNumber(camera.pitchDeg, -17), -70, 10),
fovDeg: clamp(safeNumber(camera.fovDeg, 74), 20, 130),
rangeM: clamp(safeNumber(camera.rangeM, 700), 120, 5000),
mountHeightM: clamp(safeNumber(camera.mountHeightM, 24), 2, 240),
};
}
const nextCalibration = normalizeCalibration(camera.calibration || DEFAULT_CAMERA_CALIBRATION);
camera.calibration = nextCalibration;
const base = camera.basePose;
const offsets = offsetDegrees(base.lat, nextCalibration.offsetNorthM, nextCalibration.offsetEastM);
camera.lat = base.lat + offsets.latOffset;
camera.lon = base.lon + offsets.lonOffset;
camera.headingDeg = normalizeHeading(base.headingDeg + nextCalibration.headingDeg);
camera.pitchDeg = clamp(base.pitchDeg + nextCalibration.pitchDeg, -70, 10);
camera.fovDeg = clamp(base.fovDeg + nextCalibration.fovDeg, 20, 130);
camera.rangeM = clamp(base.rangeM * nextCalibration.rangeScale, 120, 5000);
camera.mountHeightM = clamp(base.mountHeightM + nextCalibration.heightM, 2, 240);
camera.intrinsics = {
fovDeg: camera.fovDeg,
principalPoint: [0.5, 0.5],
};
camera.extrinsics = {
headingDeg: camera.headingDeg,
pitchDeg: camera.pitchDeg,
rollDeg: 0,
heightM: camera.mountHeightM,
};
camera.anchor = {
lat: camera.lat,
lon: camera.lon,
elevM: safeNumber(camera.groundElevationM, 0),
targetLatLon: camera.anchor?.targetLatLon || null,
};
}
/**
* Projects a point along a bearing from a given lat/lon by a distance.
* Uses the spherical-earth direct geodesic formula (R = 6371 km).
* @param {number} latDeg - Origin latitude (degrees).
* @param {number} lonDeg - Origin longitude (degrees).
* @param {number} bearingDeg - Azimuth from north (degrees).
* @param {number} distanceM - Distance in metres.
* @returns {{ lat: number, lon: number }} Destination in degrees.
*/
function projectPoint(latDeg, lonDeg, bearingDeg, distanceM) {
const angular = distanceM / 6371000;
const bearing = toRad(bearingDeg);
const lat1 = toRad(latDeg);
const lon1 = toRad(lonDeg);
const sinLat2 = Math.sin(lat1) * Math.cos(angular)
+ Math.cos(lat1) * Math.sin(angular) * Math.cos(bearing);
const lat2 = Math.asin(sinLat2);
const y = Math.sin(bearing) * Math.sin(angular) * Math.cos(lat1);
const x = Math.cos(angular) - Math.sin(lat1) * sinLat2;
const lon2 = lon1 + Math.atan2(y, x);
return {
lat: Cesium.Math.toDegrees(lat2),
lon: Cesium.Math.toDegrees(lon2),
};
}
/**
* V2 core geometry (design §2a): computes the pitched frustum pyramid — mount
* point, far-cap (monitor plane) center, and the 4 far-plane corners — purely
* from the calibrated pose + a caller-supplied ground altitude. ZERO scene
* queries: ground sampling happens in the caller (one-shot snap), and the
* obstruction probe passes its clamp in as `rangeOverrideM`.
*
* Math (spherical small-angle offsets; sub-centimetre at ≤2.2 km ranges):
* mountAlt = groundAltM + mountHeightM
* capCenter = projectPoint(heading, R·cos(pitch)) @ alt mountAlt + R·sin(pitch)
* halfW = R·tan(hFov/2)
* vFov = 2·atan(tan(hFov/2) / (16/9)) → halfH = R·tan(vFov/2)
* upOffset = cos(pitch)·halfH vertical + (−sin(pitch))·halfH along heading
* corners = (capCenter ∓ halfW toward heading∓90°) ± upOffset
* The cap CENTER altitude clamps to ≥ groundAltM + 2 m (§6 risk: fabricated
* pitch must never bury the plane's anchor); corners derive rigidly from the
* clamped center so the wireframe rays always terminate on the plane's
* corners — the bottom pair may dip below ground (tiles occlude it).
*
* @param {Object} camera - Pose: lat, lon, headingDeg, pitchDeg, fovDeg,
* rangeM, mountHeightM.
* @param {number} groundAltM - Ground altitude at the mount (metres).
* @param {number|null} [rangeOverrideM=null] - Obstruction-probe clamp: caps the
* effective range (never lengthens it).
* @returns {{ rangeM: number, vFovDeg: number, halfW: number, halfH: number,
* mount: {lat:number,lon:number,alt:number},
* capCenter: {lat:number,lon:number,alt:number},
* corners: { tl: Object, tr: Object, br: Object, bl: Object },
* topCenter: {lat:number,lon:number,alt:number}, groundAltM: number }}
*/
export function computeFrustumGeometry(camera, groundAltM, rangeOverrideM = null) {
const ground = safeNumber(groundAltM, 0);
const poseRange = Math.max(1, safeNumber(camera.rangeM, 700));
const override = safeNumber(rangeOverrideM, NaN);
const R = Number.isFinite(override) && override > 0 ? Math.min(poseRange, override) : poseRange;
const pitch = toRad(clamp(safeNumber(camera.pitchDeg, -17), -89, 89));
const hFov = toRad(clamp(safeNumber(camera.fovDeg, 74), 8, 160));
const heading = safeNumber(camera.headingDeg, 0);
const mountAlt = ground + safeNumber(camera.mountHeightM, 24);
const horiz = R * Math.cos(pitch);
const vert = R * Math.sin(pitch);
const capLL = projectPoint(camera.lat, camera.lon, heading, horiz);
const capAlt = mountAlt + vert;
const halfW = R * Math.tan(hFov / 2);
const vFovRad = 2 * Math.atan(Math.tan(hFov / 2) / PROJECTION_VERT_ASPECT);
const halfH = R * Math.tan(vFovRad / 2);
// In-plane "up" of the pitched cap, decomposed into a vertical part and a
// horizontal part along the heading (pitch < 0 tilts the cap's top forward).
const upVert = Math.cos(pitch) * halfH;
const upHoriz = -Math.sin(pitch) * halfH;
const capL = projectPoint(capLL.lat, capLL.lon, heading - 90, halfW);
const capR = projectPoint(capLL.lat, capLL.lon, heading + 90, halfW);
// Ground clamp (§6 risk): lift the CAP CENTER once so a fabricated pitch
// never buries the plane's anchor — then derive the corners RIGIDLY from the
// lifted center. Clamping each corner independently flattened the wireframe
// into a ground-hugging fan while the rigid plane kept its height (owner
// field test 2026-07-04): the corner rays must always terminate exactly on
// the monitor plane's corners. The bottom pair may dip below ground; the 3D
// tiles occlude that portion, exactly as they do for the plane itself.
const minAlt = ground + FRUSTUM_GROUND_CLEARANCE_M;
const capAltClamped = Math.max(minAlt, capAlt);
const corner = (base, sign) => {
const ll = projectPoint(base.lat, base.lon, heading, sign * upHoriz);
return { lat: ll.lat, lon: ll.lon, alt: capAltClamped + sign * upVert };
};
const topCenter = corner(capLL, 1);
return {
rangeM: R,
vFovDeg: Cesium.Math.toDegrees(vFovRad),
halfW,
halfH,
mount: { lat: camera.lat, lon: camera.lon, alt: mountAlt },
capCenter: { lat: capLL.lat, lon: capLL.lon, alt: capAltClamped },
corners: {
tl: corner(capL, 1),
tr: corner(capR, 1),
br: corner(capR, -1),
bl: corner(capL, -1),
},
topCenter,
groundAltM: ground,
};
}
/**
* Resolves the obstruction probe's effective-range clamp just short of a hit,
* with the field-derived 12 m floor used by the original H6 monitor.
* @param {number} rangeM Nominal camera range.
* @param {number} hitDistanceM Distance to the first obstruction.
* @returns {number|null} Clamp range, or null when the hit does not shorten it.
*/
export function activationProbeClampRange(rangeM, hitDistanceM) {
const nominalRange = Number(rangeM);
const hitDistance = Number(hitDistanceM);
if (!Number.isFinite(nominalRange) || nominalRange <= 0) return null;
if (!Number.isFinite(hitDistance) || hitDistance <= 0 || hitDistance >= nominalRange) return null;
return Math.max(PROBE_MIN_RANGE_M, hitDistance - PROBE_CLEARANCE_M);
}
/**
* Computes the great-circle distance between two points using the haversine formula.
* @param {number} lat1 - Latitude of point 1 (degrees).
* @param {number} lon1 - Longitude of point 1 (degrees).
* @param {number} lat2 - Latitude of point 2 (degrees).
* @param {number} lon2 - Longitude of point 2 (degrees).
* @returns {number} Distance in kilometres.
*/
function haversineKm(lat1, lon1, lat2, lon2) {
const dLat = toRad(lat2 - lat1);
const dLon = toRad(lon2 - lon1);
const a = Math.sin(dLat / 2) ** 2
+ Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
return 6371 * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
}
/**
* Computes the area of a circular sector (camera FOV wedge).
* @param {number} rangeM - Radius in metres.
* @param {number} fovDeg - Field of view in degrees.
* @returns {number} Area in km^2.
*/
function sectorAreaKm2(rangeM, fovDeg) {
const theta = toRad(clamp(fovDeg, 12, 170));
const areaM2 = 0.5 * rangeM * rangeM * theta;
return areaM2 / 1_000_000;
}
/**
* Returns a coarse grid key describing the viewer's current position and zoom
* level. Used to detect meaningful view changes for auto-hop camera switching.
* @returns {string} Grid key in the form "zoomBucket:latGrid:lonGrid".
*/
function currentViewContext() {
const carto = _viewer?.camera?.positionCartographic;
if (!carto) return 'none';
const lat = Cesium.Math.toDegrees(carto.latitude);
const lon = Cesium.Math.toDegrees(carto.longitude);
const alt = carto.height || 0;
const zoomBucket = alt < 1500 ? 'street'
: alt < 12000 ? 'city'
: alt < 75000 ? 'regional'
: 'global';
const grid = zoomBucket === 'street' ? 0.045
: zoomBucket === 'city' ? 0.24
: zoomBucket === 'regional' ? 1.0
: 4.5;
return `${zoomBucket}:${Math.floor(lat / grid)}:${Math.floor(lon / grid)}`;
}
/**
* Builds the initial camera catalog from CAMERA_SEEDS definitions.
* Each seed is resolved against its city's POI coordinates, offset, and
* passed through ensureCameraPose to populate derived fields.
* @returns {Object[]} Array of fully-initialized camera objects.
*/
function seedCatalog() {
const catalog = [];
for (const seed of CAMERA_SEEDS) {
const city = CITY_POIS[seed.cityId];
const poi = city?.pois?.[seed.poiIndex];
if (!city || !poi) continue;
const { latOffset, lonOffset } = offsetDegrees(
poi.lat,
seed.offsetNorthM || 0,
seed.offsetEastM || 0
);
const camera = {
id: seed.id,
name: seed.label,
cityId: seed.cityId,
city: city.name,
provider: 'OSM Camera Grid',
sourceKind: 'seed',
feedType: 'image',
feedConfigured: false,
headingConfidence: 'medium',
lat: poi.lat + latOffset,
lon: poi.lon + lonOffset,
headingDeg: normalizeHeading(seed.headingDeg ?? poi.heading ?? 0),
fovDeg: clamp(seed.fovDeg ?? 70, 20, 120),
rangeM: clamp(seed.rangeM ?? 700, 260, 1800),
mountHeightM: clamp(seed.elevationM ?? 22, 8, 80),
groundElevationM: Number(city.groundElevation) || 0,
absoluteHeightM: (Number(city.groundElevation) || 0) + clamp(seed.elevationM ?? 22, 8, 80),
pitchDeg: clamp(seed.pitchDeg ?? -17, -40, -4),
};
ensureCameraPose(camera);
catalog.push(camera);
}
return catalog;
}
/**
* Looks up a city ID from CITY_POIS by exact or partial name match.
* @param {string} cityName
* @returns {string|null} Matching city ID or null.
*/
function cityIdByName(cityName) {
const probe = String(cityName || '').trim().toLowerCase();
if (!probe) return null;
for (const [cityId, city] of Object.entries(CITY_POIS)) {
if (city.name.toLowerCase() === probe) return cityId;
}
for (const [cityId, city] of Object.entries(CITY_POIS)) {
if (city.name.toLowerCase().includes(probe) || probe.includes(city.name.toLowerCase())) return cityId;
}
return null;
}
/**
* Fetches configured camera sources from the backend.
* @returns {Promise<Object[]>} Array of raw source objects, or empty on failure.
*/
async function loadCameraSources() {
try {
const resp = await fetch(SOURCE_ENDPOINT, { cache: 'no-store' });
if (!resp.ok) return [];
const data = await resp.json();
if (!Array.isArray(data?.sources)) return [];
return data.sources;
} catch {
return [];
}
}
/**
* Merges raw backend sources with seed data to produce the final camera catalog.
* Seeds provide fallback values for heading, FOV, range, etc. when not specified
* by the source. Each camera is passed through ensureCameraPose.
* @param {Object[]} rawSources - Raw source objects from the backend.
* @returns {Object[]} Array of fully-initialized camera objects.
*/
function buildCatalogFromSources(rawSources) {
const sources = Array.isArray(rawSources) ? rawSources : [];
if (!sources.length) return [];
const seeded = seedCatalog();
const seedById = new Map(seeded.map((camera) => [camera.id, camera]));
const catalog = [];
for (const source of sources) {
if (!source || typeof source !== 'object') continue;
const id = String(source.id || '').trim();
if (!id) continue;
const seed = seedById.get(id);
const cityId = String(source.cityId || '').trim() || cityIdByName(source.city) || seed?.cityId || '';
const city = cityId && CITY_POIS[cityId] ? CITY_POIS[cityId] : null;
const lat = safeNumber(source.lat, seed?.lat ?? NaN);
const lon = safeNumber(source.lon, seed?.lon ?? NaN);
if (!Number.isFinite(lat) || !Number.isFinite(lon)) continue;
const sourceHeading = safeNumber(source.headingDeg, NaN);
const headingDeg = normalizeHeading(
Number.isFinite(sourceHeading)
? sourceHeading
: (seed?.headingDeg ?? headingFromId(id))
);
const fovDeg = clamp(safeNumber(source.fovDeg, seed?.fovDeg ?? 74), 20, 125);
const rangeM = clamp(safeNumber(source.rangeM, seed?.rangeM ?? 700), 220, 2200);
const mountHeightM = clamp(safeNumber(source.mountHeightM, seed?.mountHeightM ?? 24), 6, 120);
const pitchDeg = clamp(safeNumber(source.pitchDeg, seed?.pitchDeg ?? -17), -55, -2);
const groundElevationM = safeNumber(source.groundElevationM, city?.groundElevation ?? seed?.groundElevationM ?? 0);
const feedType = normalizeFeedType(source.feedType || source.type || 'image');
const headingConfidence = String(source.headingConfidence || (seed ? 'high' : 'low')).toLowerCase();
// CAL badge input (design §3b passthrough): hand-authored file/env source
// entries may carry poseSource:'curated'. Austin Open Data rows never set
// this — they stay RAW PRIOR until a human manually calibrates them.
const poseSource = source.poseSource === 'curated' ? 'curated' : (seed?.poseSource || null);
const camera = {
id,
name: String(source.name || seed?.name || id),
cityId,
city: String(source.city || city?.name || seed?.city || 'Global'),
provider: String(source.provider || seed?.provider || 'Configured CCTV Source'),
sourceKind: String(source.sourceKind || source.kind || (source.url ? 'configured' : 'seed')).toLowerCase(),
feedType,
feedConfigured: typeof source.url === 'string' && !!source.url.trim(),
lat,
lon,
headingDeg,
headingConfidence,
fovDeg,
rangeM,
mountHeightM,
groundElevationM,
absoluteHeightM: groundElevationM + mountHeightM,
pitchDeg,
license: String(source.license || source.licenseNote || ''),
poseSource,
};
ensureCameraPose(camera);
catalog.push(camera);
}
return catalog;
}
/**
* Reports whether the active Google Photorealistic 3D Tileset (if any) has
* finished loading the tiles in view. Shared mesh-floor sampling is gated on
* this so a one-shot cell never bakes in a miss from still-streaming tiles.
* Discovers + caches the tileset lazily from scene
* primitives (the CCTV module holds only a `_viewer` reference). When no
* tileset is present (OSM fallback) this returns true so ground sampling is
* not permanently blocked.
*
* Task 5 (spec correction, spec §2): a HIDDEN tileset (`show === false`,
* i.e. a globe stack is active) must NOT report ready — Cesium 1.138's
* the shared sampler can only inspect *visible* 3D tilesets, so a sample taken
* against the hidden Google tileset would silently miss.
*
* @returns {boolean} True when tiles are loaded AND visible (or no tileset
* exists to wait on).
*/
function projectionTilesReady() {
if (!_activeTileset || _activeTileset.isDestroyed?.()) {
_activeTileset = null;
const primitives = _viewer?.scene?.primitives;
if (primitives && typeof primitives.get === 'function') {
for (let i = 0; i < primitives.length; i++) {
const p = primitives.get(i);
if (p instanceof Cesium.Cesium3DTileset && !p.isDestroyed?.()) {
_activeTileset = p;
break;
}
}
}
}
if (!_activeTileset) return true;
if (_activeTileset.show === false) return false;
return _activeTileset.tilesLoaded === true;
}
/**
* Converts a computeFrustumGeometry result into the Cartesian3 positions the
* entities consume. Fresh objects per call (geometry updates are rare —
* slider/save/activation — and entities must never share scratch objects).
* @param {Object} geometry - Result of computeFrustumGeometry.
* @returns {{ mount: Cesium.Cartesian3, capCenter: Cesium.Cartesian3,
* tl: Cesium.Cartesian3, tr: Cesium.Cartesian3, br: Cesium.Cartesian3,
* bl: Cesium.Cartesian3, label: Cesium.Cartesian3 }}
*/
function frustumCartesians(geometry) {
const at = (p) => Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.alt);
return {
mount: at(geometry.mount),
capCenter: at(geometry.capCenter),
tl: at(geometry.corners.tl),
tr: at(geometry.corners.tr),
br: at(geometry.corners.br),
bl: at(geometry.corners.bl),
label: Cesium.Cartesian3.fromDegrees(
geometry.topCenter.lon,
geometry.topCenter.lat,
geometry.topCenter.alt + 1.2
),
};
}
/**
* Unit ECEF direction of the frustum view axis (heading/pitch) at a position.
* Used by the plane orientation and the activation obstruction probe — both
* need the UNCLAMPED axis, so it comes from the pose, not from clamped points.
* @param {Object} camera - Camera pose (headingDeg, pitchDeg).
* @param {Cesium.Cartesian3} atPos - ECEF position defining the local ENU frame.
* @returns {{ dir: Cesium.Cartesian3, up: Cesium.Cartesian3 }} View axis + the
* frame's in-plane "up" (both unit, mutually perpendicular).
*/
function frustumFrameEcef(camera, atPos) {
const h = toRad(camera.headingDeg);
const p = toRad(camera.pitchDeg);
const enu = Cesium.Transforms.eastNorthUpToFixedFrame(atPos);
const rot = Cesium.Matrix4.getMatrix3(enu, new Cesium.Matrix3());
// ENU components: view axis + the perpendicular "up" of the pitched cap.
const dirEnu = new Cesium.Cartesian3(
Math.sin(h) * Math.cos(p),
Math.cos(h) * Math.cos(p),
Math.sin(p)
);
const upEnu = new Cesium.Cartesian3(
-Math.sin(p) * Math.sin(h),
-Math.sin(p) * Math.cos(h),
Math.cos(p)
);
return {
dir: Cesium.Matrix3.multiplyByVector(rot, dirEnu, new Cesium.Cartesian3()),
up: Cesium.Matrix3.multiplyByVector(rot, upEnu, new Cesium.Cartesian3()),
};
}
/**
* Orientation quaternion for the monitor plane entity: local +Z is the plane
* normal, pointing BACK along the view axis toward the mount so the textured
* front face reads correctly from the natural viewpoint (focusCamera flies the
* viewer to look along the camera heading). Local +X = viewer-right, +Y =
* frame-up, so the 16:9 texture maps upright and unmirrored. Static geometry —
* computed only on slider/save/activation, never per frame (§2b).
* @param {Object} camera - Camera pose.
* @param {Cesium.Cartesian3} capCenterPos - Plane center in ECEF.
* @returns {Cesium.Quaternion}
*/
function planeOrientationFor(camera, capCenterPos) {
const frame = frustumFrameEcef(camera, capCenterPos);
const right = Cesium.Cartesian3.cross(frame.dir, frame.up, new Cesium.Cartesian3());
const normal = Cesium.Cartesian3.negate(frame.dir, new Cesium.Cartesian3());
const m = new Cesium.Matrix3(
right.x, frame.up.x, normal.x,
right.y, frame.up.y, normal.y,
right.z, frame.up.z, normal.z
);
return Cesium.Quaternion.fromRotationMatrix(m);
}
/**
* Task 5: the surface regime the scene is CURRENTLY rendering, derived live
* from `globe.show` (mapStackController's `_activatePhotoreal` /
* `_activateGlobeStack` flip exactly this flag). Reading scene state directly
* — rather than caching the map-stack id — means the regime is correct even
* for stack changes this module never got an event for.
* @returns {'google-3d'|'terrain-globe'}
*/
function currentSurfaceRegime() {
return surfaceRegimeKey(_viewer?.scene?.globe?.show);
}
/**
* Task 5: the record's ellipsoidal ground PRIOR (Re:Earth point-height batch,
* `record.groundPrior.ellipsoid`), falling back to the catalog's fabricated
* orthometric `groundElevationM` only when the prior batch hasn't landed yet.
* This is the value that replaces every previous
* `Number(camera.groundElevationM) || 0` ground fallback — it alone lifts
* London's cameras from the fabricated 15 m to ~52.7 m ellipsoidal in every
* regime, on first paint.
* @param {Object} record - Camera record.
* @returns {number} Ellipsoidal ground altitude in metres.
*/
function groundPriorAltFor(record) {
const prior = record?.groundPrior?.ellipsoid;
return Number.isFinite(prior) ? prior : (Number(record?.camera?.groundElevationM) || 0);
}
/**
* Task 5: whether the record's one-shot ground resolution has completed for
* the given regime (per-regime latch — replaces the old boolean
* `groundResolved`).
* @param {Object} record - Camera record.
* @param {string} [regime] - Defaults to the current surface regime.
* @returns {boolean}
*/
function isGroundResolved(record, regime = currentSurfaceRegime()) {
return record?.groundResolved?.[regime] === true;
}
/**
* Ground altitude used for pure geometry recomputes: the given regime's
* cached resolution (`record.groundSamples[regime]` — a shared mesh/DEM floor
* in google-3d, the DEM/prior in terrain-globe) when it exists, else the prior
* itself. Never queries the scene.
* @param {Object} record - Camera record.
* @param {string} [regime] - Defaults to the current surface regime.
* @returns {number} Ground altitude in metres.
*/
function groundAltFor(record, regime = currentSurfaceRegime()) {
const cached = record?.groundSamples?.[regime];
return Number.isFinite(cached) ? cached : groundPriorAltFor(record);
}
/**
* FNV-1a over the RGB channels of a downsampled frame. Pure (takes the raw
* pixel buffer, no DOM) so it is unit-testable.
*
* Alpha is skipped deliberately — CCTV stills are opaque, so hashing it would
* cost a third more work to mix in a constant.
*
* @param {Uint8ClampedArray|number[]} data - RGBA pixels, 4 bytes per pixel.
* @returns {number|null} Unsigned 32-bit signature, or null for empty input.
*/
export function frameSignatureFromPixels(data) {
if (!data || typeof data.length !== 'number' || data.length < 4) return null;
let hash = 0x811c9dc5;
for (let i = 0; i < data.length; i += 4) {
hash = Math.imul(hash ^ data[i], 0x01000193);
hash = Math.imul(hash ^ data[i + 1], 0x01000193);
hash = Math.imul(hash ^ data[i + 2], 0x01000193);
}
return hash >>> 0;
}
/**
* Signature of the runtime's freshly decoded frame, via a reused 64x36
* scratch canvas.
*
* @param {Object} runtime - Projection runtime holding the decoded `.image`.
* @returns {number|null} Signature, or null when it cannot be computed (the
* caller then treats the frame as changed — the pre-2026-07-30 behavior).
*/
function projectionFrameSignature(runtime) {
const image = runtime?.image;
if (!image) return null;
if (!runtime.signatureCtx) {
const canvas = document.createElement('canvas');
canvas.width = FRAME_SIGNATURE_W;
canvas.height = FRAME_SIGNATURE_H;
runtime.signatureCanvas = canvas;
runtime.signatureCtx = canvas.getContext('2d', { willReadFrequently: true });
}
const ctx = runtime.signatureCtx;
if (!ctx) return null;
try {
ctx.clearRect(0, 0, FRAME_SIGNATURE_W, FRAME_SIGNATURE_H);
ctx.drawImage(image, 0, 0, FRAME_SIGNATURE_W, FRAME_SIGNATURE_H);
return frameSignatureFromPixels(
ctx.getImageData(0, 0, FRAME_SIGNATURE_W, FRAME_SIGNATURE_H).data
);
} catch {
// Tainted canvas (a cross-origin source served without CORS) or a decode
// race. Returning null means "assume changed", so behavior degrades to
// the unconditional redraw this optimization replaced.
return null;
}
}
/**
* Blits the latest projection canvas into the next of two alternating
* offscreen buffer canvases and returns it (H5).
*
* Two buffers are required because Cesium's Material image path re-uploads a
* canvas texture only when the uniform receives a NEW object reference —
* redrawing the same canvas in place is invisible to the GPU. Alternating
* references forces a texture recreate, which at <=1Hz and 1080p is cheap.
*
* @param {Object} runtime - Projection runtime with `.canvas`.
* @returns {HTMLCanvasElement|null} The freshly painted buffer, or null.
*/
function paintNextProjectionBuffer(runtime) {
if (!runtime?.canvas) return null;
if (!runtime.buffers) {
runtime.buffers = [0, 1].map(() => {
const buffer = document.createElement('canvas');
buffer.width = PROJECTION_CANVAS_WIDTH;
buffer.height = PROJECTION_CANVAS_HEIGHT;
return buffer;
});
runtime.bufferIndex = 0;
}
runtime.bufferIndex = (runtime.bufferIndex + 1) % 2;
const buffer = runtime.buffers[runtime.bufferIndex];
const ctx = buffer.getContext('2d');
if (!ctx) return null;
ctx.clearRect(0, 0, buffer.width, buffer.height);
ctx.drawImage(runtime.canvas, 0, 0);
return buffer;
}
/**
* Pushes fresh pixels into the monitor plane material. Called every
* projection tick.
*
* Video feeds are skipped entirely — their HTMLVideoElement uniform is
* updated per-frame by Cesium natively (H5). Image/webcam-frame feeds swap
* the double-buffer canvas reference, throttled to PROJECTION_TEXTURE_SWAP_MS.
*
* @param {Object} record - Camera record with an initialized projection runtime.
*/
function refreshProjectionTextures(record) {
const runtime = record?.projection;
if (!runtime || runtime.mode === 'video') return;
const now = Date.now();
if (now - safeNumber(runtime.lastTextureSwapAt, 0) < PROJECTION_TEXTURE_SWAP_MS) return;
const planeShowing = !!(runtime.planeEntity?.show && runtime.planeMaterial);
if (!planeShowing) return;
// Only swap when the canvas content actually changed since the last swap.
// Frames land every ~10 s but this runs at 1 Hz — swapping an UNCHANGED
// canvas re-uploads the texture for nothing, and each material image
// reassignment is a flash opportunity on the live plane (field test
// 2026-07-04: intermittent white flashes on the monitor plane).
if (runtime.canvasStamp === runtime.lastSwappedCanvasStamp) return;
const buffer = paintNextProjectionBuffer(runtime);
if (!buffer) return;
runtime.lastTextureSwapAt = now;
runtime.lastSwappedCanvasStamp = runtime.canvasStamp;
runtime.planeMaterial.image = buffer;
}
/**
* Builds the URL for fetching a camera frame image from the backend.
* Includes a tick parameter to control cache invalidation cadence.
* @param {Object} camera - Camera object.
* @param {number} [refreshMs=ACTIVE_FRAME_REFRESH_MS] - Refresh interval used for tick bucketing.
* @returns {string} Frame URL.
*/
function frameUrlFor(camera, refreshMs = ACTIVE_FRAME_REFRESH_MS) {
const cadenceMs = Math.max(1000, safeNumber(refreshMs, ACTIVE_FRAME_REFRESH_MS));
const tick = Math.floor(Date.now() / cadenceMs);
const params = new URLSearchParams({
label: camera.name,
city: camera.city,
lat: camera.lat.toFixed(6),
lon: camera.lon.toFixed(6),
heading: String(Math.round(camera.headingDeg)),
fov: String(Math.round(camera.fovDeg)),
pitch: String(Math.round(camera.pitchDeg || -10)),
ts: String(tick),
});
return `${FRAME_ENDPOINT}/${encodeURIComponent(camera.id)}?${params.toString()}`;
}
/**
* Builds the URL for fetching a camera's video/media stream.
* @param {Object} camera - Camera object.
* @returns {string} Media URL.
*/
function mediaUrlFor(camera) {
return `${MEDIA_ENDPOINT}/${encodeURIComponent(camera.id)}?ts=${Math.floor(Date.now() / 15000)}`;
}
/**
* Paints a placeholder frame onto the projection canvas when no live feed
* image or video is available. Shows camera name, city, and status text
* over a dark gradient with tactical border lines.
* @param {CanvasRenderingContext2D} ctx - 2D context for the projection canvas.
* @param {Object} camera - Camera object for label info.
* @param {Object|null} [health=null] - Health state for status message.
*/
function paintProjectionPlaceholder(ctx, camera, health = null) {
if (!ctx) return;
const w = PROJECTION_CANVAS_WIDTH;
const h = PROJECTION_CANVAS_HEIGHT;
ctx.clearRect(0, 0, w, h);
const g = ctx.createLinearGradient(0, 0, w, h);
g.addColorStop(0, '#05111a');
g.addColorStop(1, '#01070c');
ctx.fillStyle = g;
ctx.fillRect(0, 0, w, h);
const label = String(camera?.name || 'CCTV');
const city = String(camera?.city || 'GLOBAL');
const status = String(health?.message || health?.status || camera?.feedType || 'NO FEED').toUpperCase();
ctx.strokeStyle = 'rgba(0, 220, 255, 0.24)';
ctx.lineWidth = 2;
ctx.strokeRect(18, 18, w - 36, h - 36);
ctx.strokeRect(36, 36, w - 72, h - 72);
ctx.fillStyle = 'rgba(170, 242, 255, 0.95)';
ctx.font = '600 32px "JetBrains Mono", monospace';
ctx.fillText(label.slice(0, 42), 46, 74);
ctx.fillStyle = 'rgba(127, 216, 231, 0.8)';
ctx.font = '500 24px "JetBrains Mono", monospace';
ctx.fillText(city.toUpperCase(), 46, 112);
ctx.font = '500 21px "JetBrains Mono", monospace';
ctx.fillText(status.slice(0, 58), 46, h - 42);
}
/**
* Re-derives the monitor plane entity's placement (position, orientation,
* dimensions) + label from the record's current frustum geometry, so the plane
* always caps the wireframe exactly (corner rays terminate on its corners).
* No-op when the record has no plane runtime (idle neighbors have no plane).
* @param {Object} record - Camera record.
*/
function updatePlanePlacement(record) {
const runtime = record?.projection;
if (!runtime?.planeEntity) return;
const geometry = record.frustumGeometry
|| computeFrustumGeometry(record.camera, groundAltFor(record), record.probeClampRangeM);
const positions = record.frustumPositions || frustumCartesians(geometry);
runtime.planeEntity.position = positions.capCenter;
runtime.planeEntity.orientation = planeOrientationFor(record.camera, positions.capCenter);
if (runtime.planeEntity.plane) {
runtime.planeEntity.plane.dimensions = new Cesium.Cartesian2(
geometry.halfW * 2,
geometry.halfH * 2
);
}
if (runtime.labelPosition) {
Cesium.Cartesian3.clone(positions.label, runtime.labelPosition);
}
}
/**
* Clear the active monitor-plane label source and ownership marker.
*/
function clearProjectionOverlay() {
_cctvOverlayHost.clearSource(CCTV_PROJECTION_OVERLAY_SOURCE_ID);
_cctvOverlayHost.setVisible(CCTV_PROJECTION_OVERLAY_SOURCE_ID, false);
_projectionOverlayOwnerId = null;
}
/**
* Shows/hides the monitor plane and its associated shared-host label.
* @param {Object} runtime - Projection runtime.
* @param {boolean} visible
*/
function setPlaneVisible(runtime, visible) {
if (!runtime) return;
if (runtime.planeEntity) runtime.planeEntity.show = !!visible;
if (visible && runtime.overlayEntry && runtime.cameraId) {
if (_projectionOverlayOwnerId !== runtime.cameraId) {
_cctvOverlayHost.setEntries(
CCTV_PROJECTION_OVERLAY_SOURCE_ID,
[runtime.overlayEntry],
CCTV_PROJECTION_OVERLAY_SOURCE_OPTIONS,
);
_cctvOverlayHost.setVisible(CCTV_PROJECTION_OVERLAY_SOURCE_ID, true);
_projectionOverlayOwnerId = runtime.cameraId;
}
} else if (_projectionOverlayOwnerId === runtime.cameraId) {
clearProjectionOverlay();
}
}
/** Create the native monitor plane plus its cached host-label presentation. */
function createProjectionPlane(record, runtime, geometry, positions) {
runtime.labelPosition ||= new Cesium.Cartesian3();
Cesium.Cartesian3.clone(positions.label, runtime.labelPosition);
runtime.cameraId = String(record.camera.id);
runtime.overlayEntry = createCctvProjectionOverlayEntry({
cameraId: runtime.cameraId,
name: record.camera.name,
position: () => runtime.labelPosition,
});
runtime.planeEntity = _viewer.entities.add({
id: `cctv-${record.camera.id}-plane`,
properties: { cctvCameraId: record.camera.id },
show: false,
position: positions.capCenter,
orientation: planeOrientationFor(record.camera, positions.capCenter),
plane: {
plane: new Cesium.Plane(Cesium.Cartesian3.UNIT_Z, 0.0),
dimensions: new Cesium.Cartesian2(geometry.halfW * 2, geometry.halfH * 2),
material: runtime.planeMaterial,
outline: true,
outlineColor: PLANE_OUTLINE_COLOR,
},
});
return runtime.planeEntity;
}
/**
* Create the production monitor-plane/host-label pair without media setup.
* @param {Object} viewer Cesium viewer seam.
* @param {Object} record CCTV runtime record.
* @returns {Object} Projection runtime.
*/
export function _createCctvProjectionPlaneForTest(viewer, record) {
_viewer = viewer;
const geometry = record.frustumGeometry
|| computeFrustumGeometry(record.camera, groundAltFor(record), record.probeClampRangeM);
const positions = record.frustumPositions || frustumCartesians(geometry);
record.frustumGeometry = geometry;
record.frustumPositions = positions;
const runtime = {
cameraId: String(record.camera.id),
planeEntity: null,
labelPosition: new Cesium.Cartesian3(),
overlayEntry: null,
planeMaterial: new Cesium.ColorMaterialProperty(Cesium.Color.WHITE),
};
createProjectionPlane(record, runtime, geometry, positions);
record.projection = runtime;
return runtime;
}
/**
* Exercise the production geometry-to-plane-and-label cache update.
* @param {Object} record CCTV runtime record.
*/
export function _updateCctvProjectionPlaneForTest(record) {
updatePlanePlacement(record);
}
/**
* Creates the projection runtime for a camera record: an offscreen canvas,
* the monitor plane plus associated host label, and either an
* <img> or <video> element depending on the feed type.
*
* The plane is the only projection representation (v2): the frustum's far cap,
* perpendicular to the view axis (§2b — never billboarded; a wall primitive
* can't pitch, the plane can). It is textured with the live frame: video
* element direct, canvas double-buffer otherwise.
*
* @param {Object} record - Camera record.
* @returns {Object|null} Projection runtime, or null if no viewer.
*/
function createProjectionRuntime(record) {
if (!_viewer) return null;
const canvas = document.createElement('canvas');
canvas.width = PROJECTION_CANVAS_WIDTH;
canvas.height = PROJECTION_CANVAS_HEIGHT;
const ctx = canvas.getContext('2d', { alpha: true });
const feedType = normalizeFeedType(record.camera.feedType);
const mode = isVideoFeedType(feedType) ? 'video' : 'image';
const runtime = {
mode,
canvas,
ctx,
image: null,
video: null,
planeEntity: null,
cameraId: String(record.camera.id),
labelPosition: new Cesium.Cartesian3(),
overlayEntry: null,
planeMaterial: null,
buffers: null,
bufferIndex: 0,
lastTextureSwapAt: 0,
lastImageRefreshAt: 0,
imageReady: false,
imageLoading: false,
imageStamp: 0,
drawnImageStamp: -1,
// Signature of the pixels currently ON the canvas, plus the reused 64x36
// scratch used to compute it. null = "nothing known", which always redraws.
lastFrameSignature: null,
signatureCanvas: null,
signatureCtx: null,
lastPlaceholderPaintAt: 0,
// canvasStamp increments on every canvas write (frame blit / placeholder
// paint); lastSwappedCanvasStamp trails it so refreshProjectionTextures
// only re-uploads the plane texture when there is genuinely new content.
canvasStamp: 1,
lastSwappedCanvasStamp: 0,
};
paintProjectionPlaceholder(ctx, record.camera);
if (mode === 'video') {
const video = document.createElement('video');
video.muted = true;
video.loop = true;
video.autoplay = true;
video.playsInline = true;
video.crossOrigin = 'anonymous';
video.preload = 'auto';
video.src = mediaUrlFor(record.camera);
video.addEventListener('canplay', () => {
video.play().catch(() => {});
});
runtime.video = video;
} else {
const img = new Image();
img.decoding = 'async';
img.crossOrigin = 'anonymous';
img.onload = () => {
runtime.imageLoading = false;
runtime.imageReady = true;
runtime.imageStamp = Date.now();
};
img.onerror = () => {
runtime.imageLoading = false;
runtime.imageReady = false;
};
runtime.image = img;
}
// Monitor plane = the frustum's far cap: video feeds bind the video element
// directly (Cesium updates video-backed entity materials per frame); image
// feeds start on the placeholder canvas and switch to double-buffer swaps
// at <=1Hz.
const geometry = record.frustumGeometry
|| computeFrustumGeometry(record.camera, groundAltFor(record), record.probeClampRangeM);
const positions = record.frustumPositions || frustumCartesians(geometry);
runtime.planeMaterial = new Cesium.ImageMaterialProperty({
image: (mode === 'video' && runtime.video) ? runtime.video : canvas,
transparent: true,
color: Cesium.Color.WHITE.withAlpha(0.95),
});
createProjectionPlane(record, runtime, geometry, positions);
return runtime;
}
/**
* Lazily initializes the projection runtime for a record if it doesn't exist yet.
* @param {Object} record - Camera record.
* @returns {Object|null} The record's projection runtime.
*/
function ensureProjectionRuntime(record) {
if (!record) return null;
if (record.projection) return record.projection;
const runtime = createProjectionRuntime(record);
record.projection = runtime;
if (runtime) {
_projectionEntities.push(runtime);
}
return runtime;
}
/**
* Tears down a projection runtime: stops video playback, removes the monitor
* plane, and clears its host label if it owns the active source.
* @param {Object} runtime - Projection runtime to destroy.
*/
function destroyProjectionRuntime(runtime) {
if (!runtime) return;
if (runtime.video) {
runtime.video.pause();
runtime.video.removeAttribute('src');
runtime.video.load();
}
if (runtime.planeEntity && _viewer) {
_viewer.entities.remove(runtime.planeEntity);
runtime.planeEntity = null;
}
if (_projectionOverlayOwnerId === runtime.cameraId) clearProjectionOverlay();
runtime.overlayEntry = null;
runtime.labelPosition = null;
runtime.planeMaterial = null;
}
/**
* Triggers a new frame fetch for an image-mode projection if the refresh
* interval has elapsed. Active cameras refresh more frequently than idle ones.
* @param {Object} record - Camera record.
* @param {boolean} [force=false] - Bypass the interval check.
*/
function refreshProjectionImage(record, force = false) {
const runtime = record?.projection;
if (!runtime || runtime.mode !== 'image' || !runtime.image) return;
// Hidden-state gate (perf wave 2): no new frame fetch/decode for a canvas
// nobody can see. The refresh interval re-fills naturally on return.
if (typeof document !== 'undefined' && document.hidden && !force) return;
// Do not replace an in-flight URL on the 10-second refresh boundary. Slow
// providers otherwise leave cancelled server requests behind and the plane
// can remain permanently pending. The proxy bounds each attempt; load/error
// clears this latch so the next normal tick can refresh.
if (runtime.imageLoading) return;
const now = Date.now();
const refreshMs = record.camera.id === _activeCameraId
? PROJECTION_ACTIVE_REFRESH_MS
: PROJECTION_IDLE_REFRESH_MS;
if (!force && now - runtime.lastImageRefreshAt < refreshMs) return;
runtime.lastImageRefreshAt = now;
const frameUrl = frameUrlFor(record.camera, refreshMs);
const sep = frameUrl.includes('?') ? '&' : '?';
runtime.imageLoading = true;
runtime.imageReady = false;
runtime.image.src = `${frameUrl}${sep}projTs=${Math.floor(now / refreshMs)}`;
}
/**
* Repaints the projection placeholder at most once per PLACEHOLDER_REPAINT_MS.
* The projection loop runs at RAF cadence — unthrottled, a pending feed would
* re-fill the 1080p canvas (gradient + text) on every single frame.
* @param {Object} record - Camera record.
* @param {Object} runtime - Projection runtime.
* @param {Object|null} health - Health state for status text.
*/
function paintPlaceholderThrottled(record, runtime, health) {
const now = Date.now();
if (now - safeNumber(runtime.lastPlaceholderPaintAt, 0) < PLACEHOLDER_REPAINT_MS) return;
runtime.lastPlaceholderPaintAt = now;
runtime.drawnImageStamp = -1;
// The placeholder overwrites the canvas, so the last real frame is no longer
// on it. Drop the signature or an identical frame returning after an outage
// would be skipped as "unchanged" and leave the placeholder on the plane.
runtime.lastFrameSignature = null;
runtime.canvasStamp = (runtime.canvasStamp || 0) + 1;
paintProjectionPlaceholder(runtime.ctx, record.camera, health);
}
/**
* Draws the current frame (video or image) onto the projection canvas.
* Falls back to the placeholder if the media source is not yet ready.
* Image feeds only repaint when a NEW image finished loading (stamp check):
* re-blitting an unchanged 1080p image every RAF tick is pure waste since
* texture uploads are already throttled to 1Hz buffer swaps.
* @param {Object} record - Camera record with an initialized projection runtime.
*/
function drawProjectionFrame(record) {
const runtime = record?.projection;
if (!runtime || !runtime.ctx) return;
const health = _healthById.get(record.camera.id) || null;
if (runtime.mode === 'video' && runtime.video) {
const video = runtime.video;
if (video.readyState >= 2 && video.videoWidth > 0 && video.videoHeight > 0) {
runtime.ctx.clearRect(0, 0, PROJECTION_CANVAS_WIDTH, PROJECTION_CANVAS_HEIGHT);
runtime.ctx.drawImage(video, 0, 0, PROJECTION_CANVAS_WIDTH, PROJECTION_CANVAS_HEIGHT);
runtime.canvasStamp = (runtime.canvasStamp || 0) + 1;
return;
}
paintPlaceholderThrottled(record, runtime, health);
return;
}
refreshProjectionImage(record);
if (runtime.image && runtime.imageReady) {
if (runtime.drawnImageStamp !== runtime.imageStamp) {
// The frame URL carries a 10s cache-buster tick, so a fresh Image
// DECODES every PROJECTION_ACTIVE_REFRESH_MS whether or not the provider
// actually published a new picture — measured 2026-07-30: a London
// camera republished once in 5 minutes, an Austin one not at all.
// Redrawing regardless bumped canvasStamp, which forced a buffer swap
// and a fresh 1920x1080 texture upload; the plane renders its white
// base color (planeMaterial color = WHITE, alpha .95) for the frame or
// two Cesium needs to rebind, which IS the periodic white flash from the
// field tests (2026-07-04 and 2026-07-30).
const signature = projectionFrameSignature(runtime);
runtime.drawnImageStamp = runtime.imageStamp;
if (signature !== null && signature === runtime.lastFrameSignature) {
// Identical pixels — leave the canvas, and therefore the bound
// texture, completely alone. No canvasStamp bump, no swap, no flash.
return;
}
runtime.lastFrameSignature = signature;
runtime.ctx.clearRect(0, 0, PROJECTION_CANVAS_WIDTH, PROJECTION_CANVAS_HEIGHT);
runtime.ctx.drawImage(runtime.image, 0, 0, PROJECTION_CANVAS_WIDTH, PROJECTION_CANVAS_HEIGHT);
runtime.canvasStamp = (runtime.canvasStamp || 0) + 1;
runtime.lastPlaceholderPaintAt = 0;
}
return;
}
// A refresh is in flight (imageReady=false): keep the last good frame on
// the canvas instead of flashing the placeholder. Placeholder only paints
// when nothing has ever been drawn for this camera.
if (runtime.drawnImageStamp === -1) {
paintPlaceholderThrottled(record, runtime, health);
}
}
/**
* Starts the requestAnimationFrame loop that drives projection canvas updates
* (frame draw + texture swap) for the active camera.
*/
/**
* The projection rAF has real work only while a camera is actively projected
* or a focus fade is in flight — otherwise it burned a wakeup + style poll
* every rendered frame for the whole enabled lifetime of the layer. The tick
* self-stops when idle; every state edge that creates work re-arms it
* (enable, setActiveCamera, showProjection, focus-target appearance).
* (perf wave 1)
* @returns {boolean} Whether the loop currently has work.
*/
function projectionLoopIsNeeded() {
if (!_enabled || !_viewer) return false;
if (_showProjection && getActiveRecord()) return true;
return focusPassIsNeeded(getFocusTarget(), _activeFocusStyleCount);
}
function startProjectionLoop() {
if (_projectionRaf) return;
if (!projectionLoopIsNeeded()) return;
// The armed projection loop uploads video textures / runs focus fades per
// frame — the scene must render continuously while it runs. Released when
// the tick self-stops. (perf wave 2)
holdContinuousRender('cctv-projection');
const tick = () => {
if (!_viewer || !projectionLoopIsNeeded()) {
_projectionRaf = 0;
releaseContinuousRender('cctv-projection');
return;
}
refreshCctvFocusStyles(performance.now());
const active = getActiveRecord();
if (_enabled && _showProjection && active) {
ensureProjectionRuntime(active);
if (active.projection?.video) {
active.projection.video.play().catch(() => {});
}
if (active.projection) {
drawProjectionFrame(active);
refreshProjectionTextures(active);
}
}
_projectionRaf = requestAnimationFrame(tick);
};
_projectionRaf = requestAnimationFrame(tick);
}
/**
* Focus modulation rides the layer's existing animation loop; no additional
* scene listener is installed. Only camera-icon alpha changes here — coverage
* geometry and monitor-plane styling retain their established cadence.
*/
function refreshCctvFocusStyles(nowMs) {
nowMs = focusNowMs(nowMs);
const target = getFocusTarget();
if (!_enabled || !_viewer || !focusPassIsNeeded(target, _activeFocusStyleCount)) return;
if (nowMs - _lastFocusStyleAt < 80) return;
_lastFocusStyleAt = nowMs;
const scene = _viewer.scene;
const camera = _viewer.camera;
const result = applyCctvFocusDeemphasis({
records: _records,
target,
previousActiveCount: _activeFocusStyleCount,
nowMs,
screenPositionFor: (position) => (
Cesium.SceneTransforms.worldToWindowCoordinates(scene, position, _scratchFocusScreen)
),
cameraDistanceFor: (position) => Cesium.Cartesian3.distance(camera.positionWC, position),
baseColorFor: (record) => (
record.camera.id === _activeCameraId ? ACTIVE_CAMERA_COLOR : IDLE_CAMERA_COLOR
),
});
_activeFocusStyleCount = result.activeCount;
}
/**
* Apply the gated CCTV focus pass through the production color path.
* @param {object} input
* @returns {{writes:number,transitioning:boolean,activeCount:number,ran:boolean}}
*/
export function applyCctvFocusDeemphasis({
records,
target,
previousActiveCount = 0,
nowMs,
screenPositionFor,
cameraDistanceFor,
baseColorFor,
params,
}) {
if (!focusPassIsNeeded(target, previousActiveCount)) {
return { writes: 0, transitioning: false, activeCount: 0, ran: false };
}
let writes = 0;
let transitioning = false;
let activeCount = 0;
for (const record of records || []) {
const bb = record.billboard;
if (!bb) continue;
const position = bb.position;
// CCTV never publishes a tracked focus target, so every icon is ambient.
const focus = advanceSpriteFocus(bb, {
// Keep hidden icons in the state/release pass so the active count cannot
// drop while a stale dim alpha remains waiting to reappear.
screenPosition: bb.show === false || !position ? null : screenPositionFor(position),
cameraDistance: position ? cameraDistanceFor(position) : Number.NaN,
nowMs,
target,
params,
spriteHalfWidthPx: (bb.width || 24) * (bb.scale || 1) * 0.5,
spriteHalfHeightPx: (bb.height || 24) * (bb.scale || 1) * 0.5,
});
transitioning ||= focus.transitioning;
if (focus.active) activeCount += 1;
const base = baseColorFor(record);
const alpha = base.alpha * focus.factor;
if (focusAlphaNeedsWrite(bb.color?.alpha, alpha, params)) {
// Order-independent narrow amendment to always-visible icons: CCTV
// contacts retain a non-zero floor while yielding near the tracked target.
bb.color = base.withAlpha(alpha);
writes += 1;
}
}
return { writes, transitioning, activeCount, ran: true };
}
/** Cancels the projection animation loop. */
function stopProjectionLoop() {
if (_projectionRaf) {
cancelAnimationFrame(_projectionRaf);
_projectionRaf = 0;
}
releaseContinuousRender('cctv-projection');
}
/**
* Recomputes the pure frustum geometry from the camera pose + the given ground
* altitude and writes it into the scene: billboard position, the 5 wireframe
* polylines (4 corner rays + closed far-plane rectangle), and the monitor
* plane placement. This is the ONLY place v2 geometry is written — called on
* slider input / save / activation / the one-shot ground snap, never per frame.
* @param {Object} record - Camera record.
* @param {number} groundAltM - Ground altitude at the mount (metres).
*/
function applyFrustumGeometry(record, groundAltM) {
const geometry = computeFrustumGeometry(record.camera, groundAltM, record.probeClampRangeM);
const positions = frustumCartesians(geometry);
record.frustumGeometry = geometry;
record.frustumPositions = positions;
record.position = positions.mount;
record.camera.absoluteHeightM = geometry.mount.alt;
if (record.billboard) {
record.billboard.position = positions.mount;
}
if (record.coverageEntities?.length >= 5) {
record.coverageEntities[0].polyline.positions = [positions.mount, positions.tl];
record.coverageEntities[1].polyline.positions = [positions.mount, positions.tr];
record.coverageEntities[2].polyline.positions = [positions.mount, positions.br];
record.coverageEntities[3].polyline.positions = [positions.mount, positions.bl];
record.coverageEntities[4].polyline.positions = [
positions.tl, positions.tr, positions.br, positions.bl, positions.tl,
];
}
// A live viewshed volume tracks its wireframe: rebuild from the SAME fresh
// positions (weld invariant). Only records currently showing a volume pay
// this (6 triangles, synchronous — trivial even during slider/gizmo drags).
// Tint derives from the live active id, not the cached viewshedActiveTint —
// during an activation switch this runs BEFORE refreshCoverageStyles, and
// the cache is stale for exactly that window.
if (record.viewshedPrimitive) {
rebuildViewshedVolume(record, record.camera.id === _activeCameraId);
}
updatePlanePlacement(record);
// Gizmo handles track the pose they manipulate: refresh when the ACTIVE
// camera's geometry rewrites (incl. during its own drag).
if (_gizmo?.isEnabled() && record.camera.id === _activeCameraId) {
_gizmo.refresh();
}
}
/**
* Refreshes a record's frustum geometry with a regime-aware, ONE-SHOT ground
* resolution (Task 5, spec §2). Per regime:
*
* - `terrain-globe` (any globe stack): `cachedGroundFloor` returns its DEM
* floor because mesh floors are regime-disabled. The exact Re:Earth prior
* remains the immediate fallback while that coarse cell warms.
* - `google-3d` (photoreal): the shared mesh-floor sampler may refine the
* DEM cell once, subject to its existing tiles-ready, distance,
* camera-height, and acceptance gates. Geometry reads only
* `cachedGroundFloor`, never a CCTV-owned point sample.
*
* v2 samples ONLY the mount — the far cap hangs in the air off mountAlt. No
* timer, no deadband: this function is called only from the staggered
* geometry queue (the enable-time drain + update()'s one-shot tiles-ready
* completion re-enqueue), from explicit pose-edit call sites, and from the
* map-stack regime-change handler.
* @param {Object} record - Camera record.
* @param {Object} [options={}]
* @param {boolean} [options.sampleGround=true] - When false, skip shared
* mesh-floor refinement and use the cached/prior ground instead.
*/
function updateRecordGeometry(record, options = {}) {
const sampleGround = options.sampleGround !== false;
const regime = currentSurfaceRegime();
const point = { lat: record.camera.lat, lon: record.camera.lon };
warmGroundFloor([point]);
if (regime === 'terrain-globe') {
const cachedFloor = cachedGroundFloor(point.lat, point.lon);
const ground = Number.isFinite(cachedFloor) ? cachedFloor : groundPriorAltFor(record);
record.groundSamples['terrain-globe'] = ground;
record.groundResolved['terrain-globe'] = true;
applyFrustumGeometry(record, ground);
return;
}
// Photoreal regime. Sampling is delegated to the shared coarse-cell
// sampler. It remains event-driven, one-shot per cell, and keeps its
// existing acceptance window; CCTV adds no rooftop rejection policy.
if (sampleGround && projectionTilesReady()) {
record.groundMeshSampleRequestCount = (record.groundMeshSampleRequestCount || 0) + 1;
const viewerCarto = _viewer?.camera?.positionCartographic;
const excludeObjects = [...(record.coverageEntities || [])];
if (record.billboard) excludeObjects.push(record.billboard);
if (record.projection?.planeEntity) excludeObjects.push(record.projection.planeEntity);
sampleMeshFloorCells(_viewer?.scene, [point], {
excludeObjects: excludeObjects.filter(Boolean),
viewerLat: viewerCarto ? Cesium.Math.toDegrees(viewerCarto.latitude) : undefined,
viewerLon: viewerCarto ? Cesium.Math.toDegrees(viewerCarto.longitude) : undefined,
});
}
const cachedFloor = cachedGroundFloor(point.lat, point.lon);
const ground = Number.isFinite(cachedFloor)
? cachedFloor
: groundAltFor(record, 'google-3d');
applyFrustumGeometry(record, ground);
record.groundResolved['google-3d'] = Number.isFinite(cachedFloor);
if (Number.isFinite(cachedFloor)) {
record.groundSamples['google-3d'] = ground;
}
}
/**
* Re-arms a record for a fresh one-shot ground resolution after a GENUINE
* pose change (an explicit user select/move or manual calibration edit).
* Clears the CURRENT regime's resolved latch so the next real pass in
* updateRecordGeometry always applies, then the record re-freezes. Never
* called on a timer.
*
* The cached `groundSamples` entries are deliberately KEPT (only the latch is
* cleared). They are the record's "has ever resolved" memory: the B9c
* fallback guard in updateRecordGeometry reads the google-3d entry so a
* rearmed camera whose tiles are mid-stream (e.g. select → flyTo →
* tilesLoaded false) is not yanked back to prior/catalog heights before its
* fresh shared floor lands. In the terrain-globe regime the re-arm is
* effectively free: the next pass re-latches from the DEM/prior with zero
* scene queries.
* @param {Object} record - Camera record.
*/
function rearmGroundResolution(record) {
if (!record) return;
record.groundResolved[currentSurfaceRegime()] = false;
}
/**
* Resolves a user-moved ground anchor exactly once at commit. The synchronous
* pass uses a warm shared floor immediately, or preserves the pre-drag floor
* while the new cell is cold. A revision and coordinate check prevent an
* older asynchronous release from rewriting a newer edit.
* @param {Object} record - Camera record whose lat/lon just committed.
*/
function resolveCommittedGroundAnchor(record) {
if (!record?.camera) return;
record.calibrationGroundResolveCount = (record.calibrationGroundResolveCount || 0) + 1;
const revision = (record.calibrationGroundRevision || 0) + 1;
record.calibrationGroundRevision = revision;
const point = { lat: record.camera.lat, lon: record.camera.lon };
rearmGroundResolution(record);
updateRecordGeometry(record);
if (isGroundResolved(record)) return;
resolveGroundFloorCells([point]).then(() => {
if (_recordById.get(record.camera.id) !== record) return;
if (record.calibrationGroundRevision !== revision) return;
if (record.camera.lat !== point.lat || record.camera.lon !== point.lon) return;
rearmGroundResolution(record);
updateRecordGeometry(record);
refreshCoverageStyles();
notifyListeners();
});
}
/**
* Task 5: batches every catalog camera's coords through the Re:Earth
* ellipsoidal ground resolver (`/api/terrain/heights` proxy — network-cached,
* chunked, geoid fallback; NOT a scene query). The catalog's orthometric
* `groundElevationM` rides along as `sourceOrthometricM` so the geoid
* fallback chain is meaningful where the catalog value is real (Caltrans).
* Never rejects — a total failure resolves null and geometry stays on
* catalog fallbacks (no worse than pre-Task-5).
* @param {Object[]} catalog - Camera objects (post-ensureCameraPose).
* @returns {Promise<Array<{ellipsoid:number, source:string}>|null>}
*/
async function resolveGroundPriors(catalog) {
try {
const coords = catalog.map((camera) => {
const ortho = Number(camera.groundElevationM);
return {
lat: camera.lat,
lon: camera.lon,
...(Number.isFinite(ortho) ? { sourceOrthometricM: ortho } : {}),
};
});
return await resolveEllipsoidalGround(coords);
} catch (error) {
console.warn('[Data:CCTV] ground-prior batch failed (keeping catalog fallbacks):', error?.message || error);
return null;
}
}
/**
* Task 5: applies a LATE-arriving ground-prior batch (init's bounded race
* lost — cold proxy cache / slow upstream). Pure recomputes only, no scene
* queries:
* - terrain-globe regime: the prior IS the resolution → re-run the
* resolution (updateRecordGeometry latches it) for every record.
* - google-3d regime: records still awaiting a shared floor move from the
* catalog fallback onto the exact prior; records already holding a shared
* mesh/DEM floor keep it untouched.
* Guarded per record against a torn-down/re-inited layer (records are only
* touched while they are still the live catalog entries).
* @param {Object[]} records - The record array captured at init time.
* @param {Array<{ellipsoid:number, source:string}>} priors - Aligned by index.
*/
function applyLateGroundPriors(records, priors) {
if (!Array.isArray(records) || !Array.isArray(priors)) return;
let applied = 0;
for (let i = 0; i < records.length && i < priors.length; i++) {
const record = records[i];
const prior = priors[i];
if (!record || !prior || !Number.isFinite(prior.ellipsoid)) continue;
// Stale-record guard: init() may have re-run (destroy/init cycle) while
// the batch was in flight — only touch records still live in the map.
if (_recordById.get(record.camera.id) !== record) continue;
record.groundPrior = prior;
// Keep the cheap pre-enable altitude consistent for records whose
// geometry hasn't been applied yet (applyFrustumGeometry overwrites it).
if (!record.frustumPositions) {
record.camera.absoluteHeightM = prior.ellipsoid + record.camera.mountHeightM;
}
const regime = currentSurfaceRegime();
if (regime === 'terrain-globe') {
// Prior IS the resolution — re-latch onto the fresh value.
updateRecordGeometry(record, { sampleGround: false });
applied += 1;
} else if (!Number.isFinite(record.groundSamples['google-3d'])) {
// Still awaiting the shared floor: snap interim geometry onto the exact
// prior (pure recompute; the shared cell may refine later).
applyFrustumGeometry(record, prior.ellipsoid);
applied += 1;
}
}
if (applied) notifyListeners();
}
/**
* Task 5: surface-regime change handler ('gev:map-stack-changed'
* CustomEvent, dispatched by main.js from MapStackController.onChange). The
* surface HEIGHT at a camera differs between regimes (a photogrammetric
* deck/building-top in google-3d vs bare Re:Earth DEM on globe stacks), so
* on a REGIME change (photoreal ↔ globe; bing→osm stays 'terrain-globe' and
* no-ops):
* 1. every record's geometry recomputes IMMEDIATELY from the new regime's
* resolution — cached sample if that regime has one, else the Re:Earth
* prior (never blank, zero scene queries);
* 2. entering google-3d re-arms the one-shot tiles-ready completion latch so
* update()'s existing event-driven machinery refines records that never
* took their sample, through the same staggered queue.
* Event-driven only — never called on a timer.
*/
function handleMapStackChanged() {
if (!_viewer || !_records.length) return;
const regime = currentSurfaceRegime();
if (regime === _lastAppliedRegime) return;
_lastAppliedRegime = regime;
for (const record of _records) {
if (regime === 'terrain-globe') {
// Prior IS the resolution — latch it (zero scene queries).
record.groundSamples['terrain-globe'] = groundPriorAltFor(record);
record.groundResolved['terrain-globe'] = true;
}
const ground = groundAltFor(record, regime);
// Skip the entity rewrite when the applied ground already matches (e.g.
// entering google-3d before any sample: prior → prior is a no-op).
if (record.frustumGeometry && Math.abs(record.frustumGeometry.groundAltM - ground) < 0.001) {
continue;
}
applyFrustumGeometry(record, ground);
}
if (regime === 'google-3d') {
// Fresh google-3d session: let update()'s ONE-SHOT completion pass
// re-enqueue records without an accepted sample once the (re-shown)
// tileset reports tilesLoaded. Records already sampled in a previous
// google-3d session keep their cached resolution — 0 new samples, well
// under the ≤1-per-(camera, session) ceiling.
_tilesReadyReenqueued = false;
}
notifyListeners();
}
/**
* Stops the staggered geometry-load queue and optionally clears progress
* counters (kept when pausing mid-flight is not needed — we always clear).
* @param {boolean} [clearProgress=true]
*/
function stopGeometryLoadQueue(clearProgress = true) {
if (_geoQueueTimer) {
clearTimeout(_geoQueueTimer);
_geoQueueTimer = 0;
}
_geoQueue = [];
_geoProgressNotifier = null;
if (clearProgress) {
_geoLoading = false;
_geoLoadTotal = 0;
_geoLoadDone = 0;
}
}
/**
* Creates the notification coalescer used by a staggered geometry drain.
* Progress emits after roughly 300 ms or ten batches, whichever comes first;
* finish always emits once even when the last progress tick just fired.
*
* @param {Function} notify Notification callback.
* @param {Object} [options={}] Testable timing options.
* @param {() => number} [options.now] Monotonic clock returning milliseconds.
* @param {number} [options.intervalMs] Maximum progress-notification cadence.
* @param {number} [options.batchLimit] Maximum batches between progress ticks.
* @returns {{ progress: () => boolean, finish: () => void }} Drain notifier.
*/
export function createGeometryProgressNotifier(notify, options = {}) {
const now = typeof options.now === 'function' ? options.now : Date.now;
const intervalMs = Number.isFinite(options.intervalMs)
? Math.max(0, options.intervalMs)
: GEO_PROGRESS_NOTIFY_INTERVAL_MS;
const batchLimit = Number.isFinite(options.batchLimit)
? Math.max(1, Math.floor(options.batchLimit))
: GEO_PROGRESS_NOTIFY_BATCH_LIMIT;
let lastNotifyAt = now();
let batchesSinceNotify = 0;
return {
progress() {
batchesSinceNotify += 1;
const current = now();
if (current - lastNotifyAt < intervalMs && batchesSinceNotify < batchLimit) {
return false;
}
batchesSinceNotify = 0;
lastNotifyAt = current;
notify?.();
return true;
},
finish() {
batchesSinceNotify = 0;
lastNotifyAt = now();
notify?.();
},
};
}
/**
* Processes one geometry-queue batch and routes progress/completion through
* the callbacks shared by production and the unit drain harness.
*
* @param {Object} options Batch inputs.
* @param {Object[]} options.queue Mutable record queue.
* @param {number} options.batchSize Maximum records to visit.
* @param {(record: Object) => void} options.visit Per-record geometry work.
* @param {() => void} options.progress Coalesced progress publication.
* @param {() => void} options.complete Unconditional completion publication.
* @returns {boolean} True when more records remain.
*/
export function processCctvGeometryQueueBatch({
queue,
batchSize,
visit,
progress,
complete,
}) {
const safeQueue = Array.isArray(queue) ? queue : [];
const take = Number.isFinite(batchSize) ? Math.max(1, Math.floor(batchSize)) : 1;
const batch = safeQueue.splice(0, take);
for (const record of batch) visit?.(record);
if (safeQueue.length) {
progress?.();
return true;
}
complete?.();
return false;
}
/**
* Selects per-batch geometry-drain pacing from current camera ownership.
* Called for every batch so releasing tracking immediately restores normal
* throughput without restarting the queue.
*
* @param {Object} [ownership={}] Current camera-ownership state.
* @param {*} [ownership.trackedEntity] Cesium tracked entity, if any.
* @param {boolean} [ownership.cockpitActive] Whether cockpit owns the camera.
* @returns {{ batchSize: number, delayMs: number }} Drain pacing.
*/
export function cctvGeometryDrainPacing({ trackedEntity = null, cockpitActive = false } = {}) {
if (trackedEntity || cockpitActive) {
return { batchSize: GEO_TRACKING_BATCH_SIZE, delayMs: GEO_TRACKING_BATCH_DELAY_MS };
}
return { batchSize: GEO_LOAD_BATCH_SIZE, delayMs: GEO_LOAD_BATCH_DELAY_MS };
}
/**
* Processes one tracking-aware geometry-drain batch. Ownership is read inside
* every call so a mid-drain tracking/cockpit transition changes the very next
* batch's size and delay.
*
* @param {Object} options Batch inputs.
* @param {Object[]} options.queue Mutable record queue.
* @param {() => Object} [options.readOwnership] Current camera ownership.
* @param {(record: Object) => void} options.visit Per-record geometry work.
* @param {() => void} options.progress Coalesced progress publication.
* @param {() => void} options.complete Unconditional completion publication.
* @returns {{ hasMore: boolean, batchSize: number, delayMs: number }} Batch result and pacing.
*/
export function processCctvGeometryDrainBatch({
queue,
readOwnership,
visit,
progress,
complete,
}) {
const pacing = cctvGeometryDrainPacing(readOwnership?.() || {});
const hasMore = processCctvGeometryQueueBatch({
queue,
batchSize: pacing.batchSize,
visit,
progress,
complete,
});
return { hasMore, ...pacing };
}
/**
* Moves the current active record to the front of a live drain queue.
* @param {Object[]} queue Mutable geometry queue.
* @param {Object|null} activeRecord Current active CCTV record.
* @returns {boolean} Whether the queue order changed.
*/
export function prioritizeActiveCctvGeometryRecord(queue, activeRecord) {
if (!Array.isArray(queue) || !activeRecord) return false;
const index = queue.indexOf(activeRecord);
if (index <= 0) return false;
queue.splice(index, 1);
queue.unshift(activeRecord);
return true;
}
/**
* Processes one batch (GEO_LOAD_BATCH_SIZE records) of the geometry queue:
* full ground-sampled coverage geometry per record, then yields back to the
* event loop before the next batch so tile rendering never stalls. When the
* initial-load pass completes it clears the loading flag and refreshes styles.
*/
export function processGeometryBatch() {
_geoQueueTimer = 0;
if (!_viewer) {
stopGeometryLoadQueue();
return;
}
// Active-camera-first is re-established every batch because the operator
// can select a new camera while a long catalog drain is in flight.
prioritizeActiveCctvGeometryRecord(_geoQueue, getActiveRecord());
const batchResult = processCctvGeometryDrainBatch({
queue: _geoQueue,
readOwnership: () => ({
trackedEntity: _viewer.trackedEntity,
cockpitActive: typeof document !== 'undefined'
&& document.body?.classList.contains('cockpit-mode'),
}),
visit: (record) => {
try {
updateRecordGeometry(record);
} catch (err) {
console.warn('[Data:CCTV] geometry refresh error:', err?.message || err);
}
if (_geoLoading && _geoLoadDone < _geoLoadTotal) {
_geoLoadDone += 1;
}
},
progress: () => _geoProgressNotifier?.progress(),
complete: () => {
const wasInitialLoad = _geoLoading;
_geoLoading = false;
if (wasInitialLoad) {
_geoLoadDone = _geoLoadTotal;
if (_enabled) {
refreshCoverageStyles();
// Geometry refinement may have replaced record.position objects — the
// one-shot drain completion re-anchors the card entries (event-driven,
// not a per-frame or timer pass).
refreshAmbientCards();
}
}
// Completion is never coalesced: subscribers must observe the final
// loading state even if the last progress tick just happened.
_geoProgressNotifier?.finish();
_geoProgressNotifier = null;
},
});
if (batchResult.hasMore) {
_geoQueueTimer = setTimeout(processGeometryBatch, batchResult.delayMs);
return;
}
}
/**
* Appends records to the geometry queue (no progress tracking) and starts
* the batch timer if idle. Used by update()'s ONE-SHOT tiles-ready completion
* pass (records left `!groundResolved` by an enable-time drain that ran while
* tiles were still streaming) so it shares the same stagger machinery as the
* initial load. Fires at most once per enable — never on a recurring timer.
* @param {Object[]} records - Camera records needing geometry refresh.
*/
function enqueueGeometryRefresh(records) {
for (const record of records) {
if (!_geoQueue.includes(record)) {
_geoQueue.push(record);
}
}
if (!_geoQueueTimer && _geoQueue.length) {
_geoProgressNotifier = createGeometryProgressNotifier(notifyListeners);
_geoQueueTimer = setTimeout(processGeometryBatch, 0);
}
}
/**
* Starts the initial staggered load: orders all records active-camera-first,
* then by distance from the current viewer position (nearest first, so
* cameras likely in view refine before off-screen ones), and exposes
* loaded/total progress through uiState()/getStats() while running.
*/
function startGeometryLoadQueue() {
stopGeometryLoadQueue();
// Fresh drain → fresh one-shot completion pass: re-arm the tiles-ready
// latch so update() can complete any records this drain leaves unresolved.
_tilesReadyReenqueued = false;
if (!_records.length) return;
const active = getActiveRecord();
const carto = _viewer?.camera?.positionCartographic;
const refLat = carto ? Cesium.Math.toDegrees(carto.latitude) : (active?.camera.lat ?? 0);
const refLon = carto ? Cesium.Math.toDegrees(carto.longitude) : (active?.camera.lon ?? 0);
const pending = _records
.filter((record) => record !== active)
.map((record) => ({
record,
distKm: haversineKm(refLat, refLon, record.camera.lat, record.camera.lon),
}))
.sort((a, b) => a.distKm - b.distKm)
.map((entry) => entry.record);
_geoQueue = active ? [active, ...pending] : pending;
_geoLoadTotal = _geoQueue.length;
_geoLoadDone = 0;
_geoLoading = true;
_geoProgressNotifier = createGeometryProgressNotifier(notifyListeners);
_geoQueueTimer = setTimeout(processGeometryBatch, 0);
}
/**
* Returns the camera record for the currently active camera. A stale ID falls
* back to the first record, but an intentional null remains an honest
* deselected state.
* @returns {Object|null} Active camera record, or null when none is active.
*/
function getActiveRecord() {
if (!_activeCameraId) return null;
if (_recordById.has(_activeCameraId)) {
return _recordById.get(_activeCameraId);
}
// Sync _activeCameraId when falling back to first record to prevent ID mismatch
const fallback = _records[0] || null;
if (fallback && fallback.camera?.id) {
_activeCameraId = fallback.camera.id;
}
return fallback;
}
/**
* Pauses video playback on all non-active camera projections and resumes
* the active one (if projection is enabled).
* @param {string|null} activeId - ID of the currently active camera.
*/
function pauseInactiveProjectionFeeds(activeId) {
for (const record of _records) {
if (!record.projection?.video) continue;
if (record.camera.id === activeId && _enabled && _showProjection) {
record.projection.video.play().catch(() => {});
} else {
record.projection.video.pause();
}
}
}
/**
* Determines which camera coverage overlays should be visible based on
* proximity to the active camera. Limits visibility to
* COVERAGE_NEIGHBOR_LIMIT cameras within COVERAGE_NEIGHBOR_RADIUS_KM.
* @param {Object|null} activeRecord - The active camera record.
* @returns {Set<string>} Set of visible camera IDs.
*/
function buildCoverageVisibleSet(activeRecord) {
if (!_records.length) return new Set();
// Coverage emphasis is relative to a selected camera. Without one, do not
// invent an arbitrary catalog-order cohort.
if (!activeRecord) return new Set();
const ranked = _records.map((record) => {
if (record === activeRecord) {
return { record, distKm: -1 };
}
return {
record,
distKm: haversineKm(
activeRecord.camera.lat,
activeRecord.camera.lon,
record.camera.lat,
record.camera.lon
),
};
});
ranked.sort((a, b) => a.distKm - b.distKm);
const primary = ranked.filter((entry) => entry.distKm <= COVERAGE_NEIGHBOR_RADIUS_KM || entry.distKm === -1);
const fallback = ranked;
const chosen = (primary.length >= COVERAGE_NEIGHBOR_LIMIT ? primary : fallback)
.slice(0, COVERAGE_NEIGHBOR_LIMIT)
.map((entry) => entry.record.camera.id);
return new Set(chosen);
}
/**
* Removes (and destroys) a record's viewshed volume primitive, if any.
* @param {Object} record - Camera record.
*/
function destroyViewshedVolume(record) {
if (!record) return;
if (record.viewshedPrimitive && _viewer) {
_viewer.scene.primitives.remove(record.viewshedPrimitive);
}
record.viewshedPrimitive = null;
}
/**
* (Re)builds a record's translucent viewshed volume from its CURRENT
* frustumPositions — the same 5 Cartesians the wireframe draws, so the volume
* is welded to the cone by construction. Called only where the wireframe
* already rewrites (style refresh on mode/visible-set/active changes,
* applyFrustumGeometry on pose edits) — no new update cadence, zero scene
* queries (viewshed design §3b).
* @param {Object} record - Camera record.
* @param {boolean} isActive - Active camera gets the brighter fill.
*/
function rebuildViewshedVolume(record, isActive) {
destroyViewshedVolume(record);
if (!_viewer || !record?.frustumPositions || !record.viewshedColors) return;
const color = isActive ? record.viewshedColors.fillActive : record.viewshedColors.fill;
const primitive = createFrustumVolumePrimitive(record.frustumPositions, color);
// QA tag: the harness counts viewshed volumes by this marker.
primitive._gevViewshed = record.camera.id;
record.viewshedPrimitive = _viewer.scene.primitives.add(primitive);
record.viewshedActiveTint = !!isActive;
}
/**
* Updates visual styles (colors, widths, visibility) for all camera billboards,
* coverage polylines, viewshed volumes, and projection entities based on which
* camera is active, whether the layer is enabled, and the current
* coverage-mode/projection toggle states.
*/
/**
* Field-test fix (2026-07-06): horizon-culls camera billboards, mirroring the
* flights layer's EllipsoidalOccluder pass. With the Cesium globe hidden
* (Google-3D regime) nothing writes far-side depth, and the billboards are now
* always-on-top (`disableDepthTestDistance: INFINITY` — the far-zoom submerge
* fix), so without this pass London's cluster would shine through the planet
* from a US viewpoint. Pure math over ≤ catalog-size points; runs on
* camera.moveEnd + init only (event-driven — no steady-state work).
*/
function refreshHorizonCulling() {
if (!_viewer || _viewer.isDestroyed() || !_records.length) return;
const occluder = horizonOccluder(_viewer.camera);
for (const record of _records) {
const bb = record.billboard;
if (!bb) continue;
const visible = occluder.isPointVisible(bb.position);
if (bb.show !== visible) bb.show = visible;
}
}
// ---------------------------------------------------------------------------
// Ambient card tier (2026-07-29 design — spec:
// docs/CURRENT-STATE.md)
// ---------------------------------------------------------------------------
/** Returns (creating on demand) the stable frame slot for a camera id. */
function ensureCardFrameSlot(cameraId) {
let slot = _cardFrameSlots.get(cameraId);
if (!slot) {
slot = createFrameSlot();
_cardFrameSlots.set(cameraId, slot);
}
return slot;
}
/**
* Rebuilds the ambient card selection: horizon + in-view projection of the
* catalog (pure math — no scene queries), the zoom-budgeted nearest-first
* LOD pick, greedy screen-space declutter, and the eviction-grace pass that
* keeps budget-edge cards alive across small camera moves (zero-flicker).
* Runs on camera.moveEnd, enable, activation change, and the one-shot
* geometry-drain completion — NEVER per frame. The active camera is excluded
* from the ambient selection/quota. By default its monitor plane is the sole
* active representation; the optional protected-card path is applied only by
* `pushAmbientCardEntries`. Camera icons are never touched here (cards
* annotate markers, they don't replace them).
*/
function refreshAmbientCards() {
if (!_enabled || !_viewer || _viewer.isDestroyed() || !_records.length) {
_cctvOverlayHost.setEntries(CCTV_OVERLAY_SOURCE_ID, [], CCTV_OVERLAY_SOURCE_OPTIONS);
return;
}
const scene = _viewer.scene;
const carto = _viewer.camera.positionCartographic;
const viewerLat = carto ? Cesium.Math.toDegrees(carto.latitude) : 0;
const viewerLon = carto ? Cesium.Math.toDegrees(carto.longitude) : 0;
// The active camera is excluded from ambient selection ALWAYS (not just
// after its async activation settles). It is published separately in the
// protected lane below, and grace never applies to it.
const activeId = _activeCameraId;
const occluder = horizonOccluder(_viewer.camera);
const width = scene.canvas.clientWidth || scene.canvas.width || 0;
const height = scene.canvas.clientHeight || scene.canvas.height || 0;
const marginX = width * CARD_VIEW_MARGIN;
const marginY = height * CARD_VIEW_MARGIN;
const candidates = [];
const screenById = new Map();
for (const record of _records) {
const id = record.camera.id;
if (id === activeId || !record.position) continue;
let inView = false;
let sx = NaN;
let sy = NaN;
if (occluder.isPointVisible(record.position)) {
const screen = scene.cartesianToCanvasCoordinates(record.position);
if (screen && Number.isFinite(screen.x) && Number.isFinite(screen.y)
&& screen.x >= -marginX && screen.x <= width + marginX
&& screen.y >= -marginY && screen.y <= height + marginY) {
inView = true;
sx = screen.x;
sy = screen.y;
screenById.set(id, { sx, sy });
}
}
candidates.push({
id,
distanceKm: haversineKm(viewerLat, viewerLon, record.camera.lat, record.camera.lon),
inView,
isVideo: isVideoFeedType(normalizeFeedType(record.camera.feedType)),
sx,
sy,
});
}
// Field finding 4: current card holders rank with the 20% incumbency
// distance discount, so a small camera move never batch-swaps the ring.
// Item C: passing the viewport dims + per-candidate screen anchors routes
// the budget fill through the screen-distribution grid, so periphery
// cells hold cards instead of everything clustering at screen center.
const { cardIds, budgets } = selectCctvLod(candidates, {
cameraHeightM: carto?.height,
incumbentIds: _cardIds,
viewW: width,
viewH: height,
});
// Like the cold-fill burst, card density yields to the staggered geometry
// drain: painting the raised 20/28/40 budget per frame starves the
// frame-paced mesh-floor queue on weak GPUs (qa-cctv-v2 N=800 drain-budget
// regression). During the initial load the budget holds at the low tier;
// full density arrives the moment the drain completes (which triggers its
// own refreshAmbientCards pass).
const cardLimit = _geoLoading
? Math.min(budgets.cardLimit, CCTV_AMBIENT_CARD_DRAIN_CAP)
: budgets.cardLimit;
const decluttered = declutterCctvCards(
cardIds
.filter((id) => screenById.has(id))
.slice(0, cardLimit)
.map((id, index) => ({
id,
...screenById.get(id),
// Priority carrier, not kilometers: declutter sorts ascending on
// this field, and the selection's order (distribution + incumbency)
// must survive — a periphery cell-winner must not be re-outranked
// by central proximity when two anchors contest the min separation.
distanceKm: index,
})),
{ limit: cardLimit }
);
// Field finding 2: grace must never apply to the active camera — drop any
// lingering grace entry and keep it out of the retained-card baseline.
if (activeId) {
_cardIds.delete(activeId);
_cardGraceState.delete(activeId);
}
const retention = applyEvictionGrace({
selectedIds: decluttered,
builtIds: [..._cardIds],
graceState: _cardGraceState,
nowMs: Date.now(),
cardLimit: budgets.cardLimit,
});
_cardIds = new Set(retention.keepIds);
_cardGraceState = retention.graceState;
// Bounded thumbnail LRU: live cards (grace included) never lose their
// persisted frame — that persistence IS the no-flicker guarantee. The
// hover card's slot is protected too while the gesture lasts.
const keepFrames = new Set(_cardIds);
if (_hoverCardId) keepFrames.add(_hoverCardId);
if (_activeCameraCardEnabled && _activeCameraId) keepFrames.add(_activeCameraId);
const drops = planFrameCachePrune(
[..._cardFrameSlots].map(([id, slot]) => ({ id, stamp: slot.stamp })),
keepFrames
);
for (const id of drops) _cardFrameSlots.delete(id);
pushAmbientCardEntries();
}
/**
* Builds and publishes the card entry list from the current kept set and the
* hover-summoned pin. The hover entry is budget-exempt and high-priority. The
* active camera is absent by default; `activeCameraCardEnabled` retains the
* migrated protected-publication path as an explicit product option. If the
* LOD selection adopts the hovered camera it remains a normal budgeted entry
* that keeps the pin while the gesture lasts.
*/
function pushAmbientCardEntries() {
const entries = [];
let rank = 0;
const push = (id, { pinned = false, active = false } = {}) => {
const record = _recordById.get(id);
if (!record?.position) return;
entries.push(createCctvThumbnailOverlayEntry({
id,
position: record.position,
gapPx: CARD_GAP_PX,
title: record.camera.name,
frameSlot: ensureCardFrameSlot(id),
rank: rank++,
pinned,
active,
}));
};
for (const id of _cardIds) push(id, { pinned: id === _hoverCardId });
if (_hoverCardId && !_cardIds.has(_hoverCardId) && _hoverCardId !== _activeCameraId) {
push(_hoverCardId, { pinned: true });
}
if (_activeCameraCardEnabled && _activeCameraId) {
push(_activeCameraId, { active: true });
}
_cctvOverlayHost.setEntries(
CCTV_OVERLAY_SOURCE_ID,
entries,
CCTV_OVERLAY_SOURCE_OPTIONS,
);
}
/**
* Throttled MOUSE_MOVE hover pass (follow-up round 2, item B): pointing at a
* camera icon that has no card summons its card immediately. This is
* EVENT-DRIVEN picking on a user gesture, not steady-state work — the
* ≥120 ms throttle caps it at ~8 scene.pick calls/s while the pointer is
* actually moving (a still pointer costs nothing), so it can never approach
* per-frame cost. Skipped while the camera is in motion, while ADJUST mode
* owns the pointer (gizmo drags), and while the layer is disabled.
* @param {Cesium.Cartesian2} position - Pointer position (CSS px).
*/
function handleHoverMove(position) {
if (!_enabled || _cameraMoving || _calibrationMode || !position) return;
if (!_viewer || _viewer.isDestroyed()) return;
const now = Date.now();
if (now - _hoverLastPickAt < HOVER_PICK_THROTTLE_MS) return;
_hoverLastPickAt = now;
let picked = null;
try {
picked = _viewer.scene.pick(position);
} catch {
picked = null;
}
const cameraId = extractPickedCameraId(picked);
if (cameraId && cameraId === _hoverCardId) {
// Still on the hovered camera — keep the card alive.
cancelHoverRelease();
return;
}
const record = cameraId ? _recordById.get(cameraId) : null;
// Hovering the active camera or a camera that already has a card is a
// no-op; video feeds stay icon-only until activated (ambient tier is
// stills-only — same rule as the LOD selection).
const eligible = !!record
&& cameraId !== _activeCameraId
&& !_cardIds.has(cameraId)
&& !isVideoFeedType(normalizeFeedType(record.camera.feedType));
if (eligible) {
cancelHoverRelease();
_hoverCardId = cameraId;
// Immediacy: the pinned entry publishes now — chrome may paint before
// the first frame arrives (documented exception in cctvCards.js).
pushAmbientCardEntries();
hoverFetchCardFrame(record);
} else if (_hoverCardId) {
// Pointer left the hovered icon: linger ~1 s, then release.
scheduleHoverRelease();
}
}
/** Cancels a pending hover-card release. */
function cancelHoverRelease() {
if (_hoverReleaseTimer) {
clearTimeout(_hoverReleaseTimer);
_hoverReleaseTimer = 0;
}
}
/**
* Schedules the hover card's release ~1 s after unhover. On release the pin
* drops; the card stays only if the LOD selection has adopted the camera
* (it is then a normal budgeted entry in `_cardIds`).
*/
function scheduleHoverRelease() {
if (_hoverReleaseTimer) return;
_hoverReleaseTimer = setTimeout(() => {
_hoverReleaseTimer = 0;
_hoverCardId = null;
pushAmbientCardEntries();
}, HOVER_RELEASE_MS);
}
/** Clears the hover-card state (teardown / activation of the hovered camera). */
function clearHoverCard() {
cancelHoverRelease();
_hoverCardId = null;
_hoverLastPickAt = 0;
}
/**
* Fast-tracked frame fetch for the hover-summoned card: launches
* immediately, bypassing the pacer's launch-spacing gate (a single
* user-gesture fetch is fine even during the geometry drain), but still
* respecting the per-camera failure backoff / freshness check
* (frameFetchDue), the no-double-fetch pending set, and the burst in-flight
* cap of 4.
* @param {Object} record - The hovered camera's record.
*/
function hoverFetchCardFrame(record) {
const cameraId = record.camera.id;
if (_cardFetchPendingIds.has(cameraId)) return;
if (_cardFetchInFlightCount >= CCTV_CARD_FETCH_BURST_LIMIT) return;
const slot = ensureCardFrameSlot(cameraId);
const refreshMs = staticFrameRefreshMs(record.camera);
if (!frameFetchDue(slot, refreshMs, Date.now())) return;
fetchCardFrame(record, slot, refreshMs, { userGesture: true });
}
/**
* Card-frame pacer tick (field finding 3): launches AT MOST one fetch per
* tick, with cardFetchPolicy deciding whether a launch is allowed. Cold fill
* — any selected card still missing its FIRST frame — bursts up to 4
* in-flight fetches at 250 ms spacing so arriving in a new area populates
* in a few seconds instead of 16-32 s; once every selected card has a first
* frame the layer drops back to the salvaged steady-state gate (single
* flight, one request per second). Priority: frameless cards first in ring
* order (nearest-first — they're what makes a card appear at all), then the
* stalest refresh-overdue card by its source cadence (staticFrameRefreshMs).
* Failures back off per camera (frameFetchDue) instead of hammering a dead
* source, so a dead upstream never eats the burst slots.
*/
function cardFrameTick() {
if (!_enabled || (!_cardIds.size && !(_activeCameraCardEnabled && _activeCameraId))) return;
const now = Date.now();
let frameless = null;
let stalest = null;
let coldFill = false;
const consider = (id) => {
const record = _recordById.get(id);
if (!record) return;
const slot = ensureCardFrameSlot(id);
if (_cardFetchPendingIds.has(id)) {
// An in-flight first-frame fetch keeps cold-fill mode active without
// being re-launchable.
if (!(slot.stamp > 0)) coldFill = true;
return;
}
const refreshMs = staticFrameRefreshMs(record.camera);
if (!frameFetchDue(slot, refreshMs, now)) return;
if (!(slot.stamp > 0)) {
coldFill = true;
if (!frameless) frameless = { record, slot, refreshMs };
return;
}
if (!stalest || slot.stamp < stalest.slot.stamp) {
stalest = { record, slot, refreshMs };
}
};
// The optional protected active card stays outside the 40-card ambient
// quota and uses the same source-owned pacing/retry/cache lifecycle.
if (_activeCameraCardEnabled && _activeCameraId) consider(_activeCameraId);
for (const id of _cardIds) consider(id);
const policy = cardFetchPolicy({
// The cold-fill burst yields to the staggered geometry drain: 4 concurrent
// image fetch+decodes mid-drain starve the mesh-floor queue on weak GPUs
// (qa-cctv-v2 drain-budget regression). Steady 1/s trickle still runs;
// the burst fires the moment the drain completes.
coldFill: coldFill && !_geoLoading,
inFlight: _cardFetchInFlightCount,
sinceLastLaunchMs: _cardLastFetchAt > 0 ? now - _cardLastFetchAt : Infinity,
});
_cardFetchMode = policy.mode;
if (!policy.launch) return;
const pick = frameless || stalest;
if (pick) fetchCardFrame(pick.record, pick.slot, pick.refreshMs);
}
/**
* Fetches one paced static frame and settles it into the stable slot via the
* pure persistence rule (applyFrameResult): success replaces the thumbnail,
* failure leaves the drawn frame untouched. The frame is downscaled once
* into a 2x-thumb offscreen canvas; the renderer reads the slot live.
* @param {Object} record - Camera record.
* @param {Object} slot - The camera's stable frame slot.
* @param {number} refreshMs - Source cadence (also keys the frame-URL tick).
* @param {Object} [options]
* @param {boolean} [options.userGesture] - Hover fast-track (item B): the
* launch bypasses the pacer gate, so its spacing sample would pollute the
* pacing telemetry — skip the min-spacing sample only. The launch still
* stamps `_cardLastFetchAt`, so the pacer waits a full interval after it.
*/
function fetchCardFrame(record, slot, refreshMs, { userGesture = false } = {}) {
if (typeof document !== 'undefined' && document.hidden && !userGesture) return;
const now = Date.now();
const cameraId = record.camera.id;
_cardFetchInFlightCount += 1;
_cardFetchPendingIds.add(cameraId);
if (_cardLastFetchAt > 0 && !userGesture) {
const spacing = now - _cardLastFetchAt;
// NOTE: cold-fill bursts legitimately push this to ~250 ms — read it
// together with the ambientCards.fetchMode telemetry.
_cardMinFetchSpacingMs = _cardMinFetchSpacingMs == null
? spacing
: Math.min(_cardMinFetchSpacingMs, spacing);
}
_cardLastFetchAt = now;
_cardFetchCount += 1;
const image = new Image();
_cardFetchImages.add(image);
const settle = (ok) => {
image.onload = null;
image.onerror = null;
if (_cardFetchImages.delete(image)) {
_cardFetchInFlightCount = Math.max(0, _cardFetchInFlightCount - 1);
_cardFetchPendingIds.delete(cameraId);
}
let frame = null;
if (ok) {
try {
const canvas = document.createElement('canvas');
canvas.width = CCTV_FRAME_CANVAS_W;
canvas.height = CCTV_FRAME_CANVAS_H;
canvas.getContext('2d').drawImage(image, 0, 0, canvas.width, canvas.height);
frame = canvas;
} catch {
frame = null;
}
}
Object.assign(slot, applyFrameResult(slot, { ok: !!frame, frame }, Date.now()));
_viewer?.scene?.requestRender?.();
};
image.onload = () => settle(true);
image.onerror = () => settle(false);
image.src = frameUrlFor(record.camera, refreshMs);
}
/** Starts the card-frame pacer (idempotent; policy-gated per tick). */
function startCardFrameLoop() {
if (_cardFetchTimer) return;
_cardFetchTimer = setInterval(cardFrameTick, CARD_FETCH_TICK_MS);
}
/**
* Hidden-state gate (perf wave 2): detach in-flight card frame decodes when
* the document hides — a hidden canvas has no reader, and image decode is
* the expensive half. New fetches are gated at fetchCardFrame; the steady
* pacer refills naturally on return. Installed once at module scope.
*/
if (typeof document !== 'undefined') {
document.addEventListener('visibilitychange', () => {
if (!document.hidden) return;
for (const image of _cardFetchImages) {
image.onload = null;
image.onerror = null;
image.removeAttribute('src');
}
_cardFetchImages.clear();
_cardFetchPendingIds.clear();
_cardFetchInFlightCount = 0;
});
}
/** Stops the pacer and detaches all in-flight fetch handlers. */
function stopCardFrameLoop() {
if (_cardFetchTimer) {
clearInterval(_cardFetchTimer);
_cardFetchTimer = 0;
}
for (const image of _cardFetchImages) {
image.onload = null;
image.onerror = null;
image.removeAttribute('src');
}
_cardFetchImages.clear();
_cardFetchPendingIds.clear();
_cardFetchInFlightCount = 0;
_cardFetchMode = 'steady';
}
/**
* Complete ambient-tier teardown (layer disable/destroy): pacer + in-flight
* handlers, shared-host source entries, card set, grace state, thumbnail
* cache, and fetch telemetry. Nothing leaks across a toggle.
*/
function teardownAmbientCards() {
stopCardFrameLoop();
_cctvOverlayHost.clearSource(CCTV_OVERLAY_SOURCE_ID);
_cctvOverlayHost.setVisible(CCTV_OVERLAY_SOURCE_ID, false);
clearHoverCard();
_cameraMoving = false;
_cardIds = new Set();
_cardGraceState = new Map();
_cardFrameSlots = new Map();
_cardFetchCount = 0;
_cardLastFetchAt = 0;
_cardMinFetchSpacingMs = null;
}
/**
* Hides every per-record CCTV visual without recomputing coverage membership or
* styles. Disabling makes every visibility branch false, so a direct sweep is
* sufficient; live viewshed primitives still require explicit destruction.
*
* @param {Object[]} records CCTV runtime records.
* @param {(record: Object) => void} destroyVolume Viewshed teardown callback.
* @param {string|null} [activeCameraId=null] Active camera whose activation probe must be re-armed.
*/
export function hideCctvRecordVisuals(records, destroyVolume, activeCameraId = null) {
for (const record of Array.isArray(records) ? records : []) {
if (record) {
record.probeClampRangeM = null;
if (record.camera?.id === activeCameraId) record.activationDone = false;
}
for (const entity of record?.coverageEntities || []) entity.show = false;
if (record?.viewshedPrimitive) destroyVolume?.(record);
if (record?.projection?.planeEntity) record.projection.planeEntity.show = false;
}
}
function hideCctvVisuals() {
hideCctvRecordVisuals(_records, destroyViewshedVolume, _activeCameraId);
clearProjectionOverlay();
if (_billboards) _billboards.show = false;
pauseInactiveProjectionFeeds(null);
}
/** Applies coverage visibility/style state and lazily builds eligible sets. */
export function refreshCoverageStyles() {
const activeRecord = getActiveRecord();
ensureActiveCoverageEntities(activeRecord);
const activeId = activeRecord?.camera.id || null;
const coverageVisible = buildCoverageVisibleSet(activeRecord);
const coverageOn = _coverageMode !== 'off';
const viewshedOn = _coverageMode === 'viewshed';
if (coverageOn) {
ensureVisibleCoverageEntities(_records, coverageVisible);
}
for (const record of _records) {
const isActive = record.camera.id === activeId;
if (record.billboard) {
record.billboard.color = isActive ? ACTIVE_CAMERA_COLOR : IDLE_CAMERA_COLOR;
record.billboard.scale = isActive ? 1.25 : 1.0;
// disableDepthTestDistance stays POSITIVE_INFINITY for every billboard
// (set at creation) — see the field-test far-zoom submerge fix there.
}
if (_enabled && _showProjection && isActive) {
ensureProjectionRuntime(record);
}
// One live plane in the world at a time (§2c): only the active camera's
// far cap carries the monitor plane; idle neighbors get the faint
// wireframe only.
const planeShowing = !!(_enabled && _showProjection && isActive);
const inVisibleSet = coverageVisible.has(record.camera.id);
for (const entity of record.coverageEntities || []) {
// The frustum wireframe is part of the projection representation —
// force it on for the active camera and let it read through geometry
// via depthFailMaterial (polylines have no disableDepthTestDistance).
entity.show = !!(_enabled && ((coverageOn && inVisibleSet) || planeShowing));
if (!entity.polyline) continue;
// Viewshed mode swaps the cyan/green scheme for the camera's own hue so
// adjacent cones read as distinct coverage claims (design §3b); the
// active camera keeps its width/alpha emphasis in both schemes.
const hue = viewshedOn ? record.viewshedColors : null;
if (entity._coverageRole === 'cap') {
entity.polyline.material = hue
? (isActive ? hue.lineActive : hue.line)
: (isActive ? ACTIVE_COVERAGE_CENTER : IDLE_COVERAGE_CENTER_MUTED);
entity.polyline.width = isActive ? 2.2 : 1.0;
entity.polyline.depthFailMaterial = planeShowing
? (hue ? hue.line.withAlpha(0.26) : ACTIVE_COVERAGE_CENTER_DEPTHFAIL)
: undefined;
} else {
entity.polyline.material = hue
? (isActive ? hue.lineActive : hue.line.withAlpha(0.6))
: (isActive ? ACTIVE_COVERAGE_EDGE : IDLE_COVERAGE_EDGE_MUTED);
entity.polyline.width = isActive ? 1.8 : 0.9;
entity.polyline.depthFailMaterial = planeShowing
? (hue ? hue.line.withAlpha(0.18) : ACTIVE_COVERAGE_EDGE_DEPTHFAIL)
: undefined;
}
}
// Viewshed volume lifecycle: exists iff enabled + viewshed mode + in the
// visible set. Rebuild on active-tint flips (rare); otherwise leave the
// primitive alone so idle refreshes never churn geometry.
const wantVolume = !!(_enabled && viewshedOn && inVisibleSet && record.frustumPositions);
if (wantVolume) {
if (!record.viewshedPrimitive || record.viewshedActiveTint !== isActive) {
rebuildViewshedVolume(record, isActive);
}
} else if (record.viewshedPrimitive) {
destroyViewshedVolume(record);
}
if (record.projection) {
setPlaneVisible(record.projection, planeShowing);
}
}
if (_billboards) _billboards.show = !!_enabled;
pauseInactiveProjectionFeeds(activeId);
}
/**
* Finds the camera closest to the Cesium viewer's current position.
* @returns {string|null} Camera ID of the nearest camera, or null.
*/
function nearestCameraIdToViewer() {
const carto = _viewer?.camera?.positionCartographic;
if (!carto || !_records.length) return null;
const lat = Cesium.Math.toDegrees(carto.latitude);
const lon = Cesium.Math.toDegrees(carto.longitude);
let best = null;
for (const record of _records) {
const distKm = haversineKm(lat, lon, record.camera.lat, record.camera.lon);
if (!best || distKm < best.distKm) {
best = { id: record.camera.id, distKm };
}
}
return best?.id || null;
}
/**
* Counts how many other cameras have overlapping coverage with the target.
* Overlap is approximated by comparing inter-camera distance against the
* combined range of both cameras (scaled by 0.92).
* @param {Object} targetRecord - Camera record to check.
* @returns {number} Number of overlapping neighbors.
*/
function coverageNeighborCount(targetRecord) {
if (!targetRecord) return 0;
let count = 0;
for (const record of _records) {
if (record === targetRecord) continue;
const dKm = haversineKm(
targetRecord.camera.lat,
targetRecord.camera.lon,
record.camera.lat,
record.camera.lon
);
const overlapKm = (targetRecord.camera.rangeM + record.camera.rangeM) / 1000 * 0.92;
if (dKm <= overlapKm) count++;
}
return count;
}
/**
* Builds a single-line summary string for the active camera, including city,
* heading, FOV, coverage area, overlap count, projection mode, alignment
* confidence, source type, and view context.
* @returns {string} Summary text separated by mid-dots.
*/
function buildSummaryText() {
const active = getActiveRecord();
if (!active) {
return _records.length
? `${_records.length} CAMERAS STANDING BY · NO CAMERA SELECTED · CLICK A CAMERA TO ACTIVATE`
: 'No cameras available in catalog.';
}
const area = sectorAreaKm2(active.camera.rangeM, active.camera.fovDeg);
const overlapCount = coverageNeighborCount(active);
const viewKey = currentViewContext();
const viewBand = viewKey.split(':')[0] || 'global';
const health = _healthById.get(active.camera.id) || null;
const calBadge = deriveCalBadge(active.camera);
return [
`${active.camera.city.toUpperCase()} CCTV`,
`${active.camera.name.toUpperCase()}`,
`HDG ${Math.round(active.camera.headingDeg)}°`,
`FOV ${Math.round(active.camera.fovDeg)}°`,
`COVERAGE ${area.toFixed(2)}km²`,
overlapCount > 0 ? `OVERLAP ${overlapCount} cams` : 'ISOLATED VIEW',
`PROJ ${_showProjection ? 'MONITOR' : 'OFF'}`,
_coverageMode === 'viewshed' ? 'VIEWSHED' : null,
`CAL ${calBadge.replace('-', ' ').toUpperCase()}`,
health?.sourceKind ? `SRC ${String(health.sourceKind).toUpperCase()}` : `SRC ${String(active.camera.feedType || 'image').toUpperCase()}`,
`${viewBand.toUpperCase()} CONTEXT`,
].filter(Boolean).join(' · ');
}
/**
* Builds a public-facing camera state object for UI consumption.
* Includes all pose, calibration, CAL badge, projection, and feed metadata.
* @param {Object} record - Camera record.
* @param {string|null} [activeId=null] - Active camera ID for the `active` flag.
* @returns {Object} Public camera state.
*/
function getPublicCameraState(record, activeId = null) {
const resolvedActiveId = activeId || getActiveRecord()?.camera.id || null;
const camera = record.camera;
const health = _healthById.get(camera.id) || null;
const isActive = camera.id === resolvedActiveId;
const refreshMs = isActive ? ACTIVE_FRAME_REFRESH_MS : IDLE_FRAME_REFRESH_MS;
return {
id: camera.id,
name: camera.name,
city: camera.city,
provider: camera.provider,
lat: camera.lat,
lon: camera.lon,
headingDeg: camera.headingDeg,
pitchDeg: camera.pitchDeg,
fovDeg: camera.fovDeg,
rangeM: camera.rangeM,
elevationM: camera.absoluteHeightM,
mountHeightM: camera.mountHeightM,
active: isActive,
feedType: camera.feedType,
sourceKind: health?.sourceKind || camera.sourceKind || (camera.feedConfigured ? 'configured' : 'seed'),
sourceStatus: health?.status || 'unknown',
sourceMessage: health?.message || '',
sourceLabel: health?.label || camera.provider || '',
calibration: { ...normalizeCalibration(camera.calibration) },
// Save-gated persistence (design §3e): true while the live pose carries
// edits that have not been SAVEd (or RESET). Drives the CAL · EDITED chip.
calDirty: !!record.calDirty,
// Deterministic QA seam: counts commit-grade anchor resolutions (E/N drag
// release, numeric E/N edit, or reset), never transient gizmo moves.
groundResolveCount: record.calibrationGroundResolveCount || 0,
// Per-record QA seam for proving transient gizmo moves never enter the
// shared mesh-floor sampler while unrelated catalog cells finish.
groundMeshSampleRequestCount: record.groundMeshSampleRequestCount || 0,
// Datum QA seam: expose the immutable Re:Earth ellipsoidal prior
// separately from the currently applied frustum ground. Google-3D may
// legitimately refine the latter to the rendered mesh, so callers must
// not infer the prior by subtracting mount height from live geometry.
groundPriorM: Number.isFinite(record.groundPrior?.ellipsoid)
? record.groundPrior.ellipsoid
: null,
intrinsics: camera.intrinsics ? { ...camera.intrinsics } : null,
extrinsics: camera.extrinsics ? { ...camera.extrinsics } : null,
anchor: camera.anchor ? { ...camera.anchor } : null,
// Panel-only trust signal (design §3b, amended by LOCKED §9.2/§9.3): no
// in-world rendering reads this, no score-based quality math backs it.
calBadge: deriveCalBadge(camera),
poseSource: camera.poseSource || null,
basePose: camera.basePose ? { ...camera.basePose } : null,
frameUrl: frameUrlFor(camera, refreshMs),
mediaUrl: mediaUrlFor(camera),
};
}
/**
* Assembles the full UI state payload containing layer toggles, camera list,
* active camera details, summary text, and error state.
* @returns {Object} Complete UI state for subscribers.
*/
function uiState() {
const active = getActiveRecord();
const activeId = active?.camera.id || null;
const payload = {
enabled: _enabled,
// Compat boolean + the full tri-state (viewshed design §3b).
showCoverage: _coverageMode !== 'off',
coverageMode: _coverageMode,
showProjection: _showProjection,
calibrationMode: _calibrationMode,
autoHop: _autoHop,
autoHopSuspended: _autoHopSuspended,
autoHopSec: _autoHopSec,
count: _count,
lastUpdate: _lastUpdate,
error: _lastError,
loading: {
active: _geoLoading,
loaded: Math.min(_geoLoadDone, _geoLoadTotal),
total: _geoLoadTotal,
},
// Ambient card tier telemetry (QA harnesses assert the fetch pacing —
// minFrameFetchSpacingMs reads together with fetchMode: cold-fill bursts
// legitimately reach ~250 ms, steady state stays >=1000 ms).
ambientCards: {
count: _cardIds.size,
limit: CCTV_AMBIENT_CARD_MAX,
frameFetches: _cardFetchCount,
minFrameFetchSpacingMs: _cardMinFetchSpacingMs,
fetchMode: _cardFetchMode,
fetchesInFlight: _cardFetchInFlightCount,
// Item B QA seam: the hover-summoned pinned card, if any.
hoverId: _hoverCardId,
},
activeCameraId: activeId,
activeCamera: active ? getPublicCameraState(active, activeId) : null,
cameras: _records.map((record) => getPublicCameraState(record, activeId)),
summary: buildSummaryText(),
};
return payload;
}
/** Dispatches the current UI state to all registered subscriber callbacks. */
function notifyListeners() {
const payload = uiState();
for (const callback of _listeners) {
try {
callback(payload);
} catch (error) {
console.warn('[Data:CCTV] listener error:', error);
}
}
}
/**
* Throttled notifyListeners for transient (mid-drag) calibration patches —
* the panel re-render is DOM-heavy, so live gizmo drags publish state at
* ≤10 Hz while the in-world geometry still tracks every processed move.
*/
function notifyListenersThrottled() {
const now = Date.now();
if (now - _lastTransientNotifyAt < 100) return;
_lastTransientNotifyAt = now;
notifyListeners();
}
/**
* Applies a calibration patch to a record's IN-MEMORY pose (save-gated
* persistence, design §3e: no localStorage write here — only the explicit
* `calibration.save` action persists).
*
* Transient grade (gizmo mid-drag): recompute pose + frustum geometry only
* (the cheap v2 path) with throttled notify — no ground re-arm, no frame
* re-fetch, no store touch.
* Commit grade (drag end, numeric entry, voice): only an E/N anchor move
* resolves a new shared floor; all other edits keep the frozen reference.
*
* @param {Object} record - Camera record.
* @param {Object} patch - Partial 7-field calibration (absolute offset values).
* @param {{transient?: boolean}} [options]
* @returns {boolean} True when the patch applied.
*/
function applyCalibrationPatch(record, patch, options = {}) {
if (!record || !patch || typeof patch !== 'object') return false;
record.camera.calibration = normalizeCalibration({
...record.camera.calibration,
...patch,
});
ensureCameraPose(record.camera);
// §9.1: touching range takes manual control — clear the activation clamp.
if ('rangeScale' in patch) {
record.probeClampRangeM = null;
}
const anchorMoved = calibrationPatchMovesAnchor(patch);
if (options.transient === true && anchorMoved) {
record.calibrationAnchorDirty = true;
}
record.calDirty = true;
if (options.transient === true) {
applyFrustumGeometry(record, groundAltFor(record));
notifyListenersThrottled();
return true;
}
if (anchorMoved) {
resolveCommittedGroundAnchor(record);
} else {
applyFrustumGeometry(record, groundAltFor(record));
}
refreshProjectionImage(record, true);
return true;
}
/**
* Lazily creates the calibration gizmo controller. The gizmo sees the layer
* only through these callbacks: it attaches to the active record while the
* layer is enabled AND ADJUST mode is on, funnels drags through
* applyCalibrationPatch (transient), and runs the commit tail on release.
*/
function ensureGizmo() {
if (_gizmo || !_viewer) return;
// Both patch callbacks receive the gizmo's PINNED drag record — never
// re-resolve the active camera here: a mid-drag voice select or auto-hop
// would route the captured offsets onto a camera with a different basePose.
const liveRecord = (record) => (
record && _recordById.get(record.camera?.id) === record ? record : null
);
_gizmo = createCalibrationGizmo({
viewer: _viewer,
getActiveRecord: () => (_enabled && _calibrationMode ? getActiveRecord() : null),
applyPatch: (patch, draggedRecord) => {
const record = _enabled && _calibrationMode ? liveRecord(draggedRecord) : null;
if (record) applyCalibrationPatch(record, patch, { transient: true });
},
endPatch: (draggedRecord) => {
const record = liveRecord(draggedRecord);
if (!record) return;
if (record.calibrationAnchorDirty) {
record.calibrationAnchorDirty = false;
resolveCommittedGroundAnchor(record);
} else {
applyFrustumGeometry(record, groundAltFor(record));
}
refreshProjectionImage(record, true);
refreshCoverageStyles();
notifyListeners();
},
});
}
/**
* §9.1 activation obstruction probe (LOCKED product rule): on camera
* ACTIVATION only, fire ONE scene.pickFromRay along the frustum axis
* (mount → cap-center direction). If it hits the tiles closer than the pose
* range, clamp the plane's effective range just short of the first hit so the
* "big and dramatic" true end cap never clips into downtown buildings.
*
* This is the ONLY raycast in the whole CCTV subsystem — once per activation,
* never per-frame (the zero-raycast invariant applies to steady state). The
* per-camera range slider overrides the clamp: a user-set rangeScale skips the
* probe entirely. Probe failure/miss keeps the unclamped range.
* @param {Object} record - Camera record being activated.
*/
function runActivationObstructionProbe(record) {
record.probeClampRangeM = null;
const scene = _viewer?.scene;
if (!scene || typeof scene.pickFromRay !== 'function') return;
const camera = record.camera;
const rangeScale = normalizeCalibration(camera.calibration).rangeScale;
if (Math.abs(rangeScale - 1) > 0.0001) return; // slider overrides the clamp
try {
const mountAlt = groundAltFor(record) + camera.mountHeightM;
const mountPos = Cesium.Cartesian3.fromDegrees(camera.lon, camera.lat, mountAlt);
const { dir } = frustumFrameEcef(camera, mountPos);
// Exclude everything the layer itself draws so the probe can only hit the
// world (3D tiles), not our own billboards/polylines/planes.
const exclude = [_billboards, ..._coverageEntities];
for (const runtime of _projectionEntities) {
if (runtime?.planeEntity) exclude.push(runtime.planeEntity);
}
const hit = scene.pickFromRay(new Cesium.Ray(mountPos, dir), exclude);
if (!hit?.position) return;
const dist = Cesium.Cartesian3.distance(mountPos, hit.position);
record.probeClampRangeM = activationProbeClampRange(camera.rangeM, dist);
} catch {
// probe failure → keep the unclamped range
}
}
/**
* Clears a deactivated camera's temporary obstruction clamp and rewrites its
* geometry through the normal single-range path.
* @param {Object|null} record Camera runtime record being deactivated.
* @param {(record: Object) => void} rewriteGeometry Nominal geometry rewrite.
* @returns {boolean} Whether a clamp was cleared.
*/
export function clearProbeClampOnDeactivation(record, rewriteGeometry) {
if (!record || !Number.isFinite(record.probeClampRangeM)) return false;
record.probeClampRangeM = null;
rewriteGeometry?.(record);
return true;
}
/**
* Reports whether selecting a record must run the full activation path.
* Disable re-arms the still-active record so its obstruction probe runs again
* on its next real activation after the temporary clamp is cleared.
* @param {string} cameraId Requested camera ID.
* @param {string|null} activeCameraId Current active camera ID.
* @param {Object|null} record Requested camera runtime record.
* @returns {boolean} Whether activation work must run.
*/
export function cctvRecordNeedsActivation(cameraId, activeCameraId, record) {
return cameraId !== activeCameraId || record?.activationDone !== true;
}
/**
* Bind CCTV activation to clean taps while preserving the layer's hover-move
* callback on the shared Cesium handler. Drag-like and long-press gestures do
* not reach camera activation or focus dispatch.
* @param {Cesium.ScreenSpaceEventHandler|Object} handler - Input handler.
* @param {(click: Object) => void} onClick - Accepted CCTV click callback.
* @param {Object} [options] - Gesture test seams and optional onMouseMove hook.
* @returns {void}
*/
export function bindCctvWorldClickGesture(handler, onClick, options = {}) {
bindTrackingClickGesture(handler, (click, gesture) => {
if (!isTrackingClickGesture(gesture)) return;
onClick(click);
}, options);
}
/**
* Sets the active camera by ID, initializes its projection runtime, refreshes
* its frame, and updates styles.
* @param {string} cameraId - ID of the camera to activate.
* @returns {'activated'|'unchanged'|'not-found'} Discriminated activation result.
*/
export function setActiveCamera(cameraId) {
if (!cameraId || !_recordById.has(cameraId)) return CCTV_ACTIVATION_RESULT.NOT_FOUND;
const record = _recordById.get(cameraId);
const previousActiveRecord = getActiveRecord();
// Re-selecting the already-active camera is a no-op: re-running the
// activation path re-probes and rewrites the plane entity's geometry, and
// that async primitive rebuild visibly flashes the monitor plane (owner
// field test 2026-07-04 — every click ON the plane picks its own camera).
// `activationDone` distinguishes a real activation from the enable()-time
// default `_activeCameraId` assignment, which never ran this path.
if (!cctvRecordNeedsActivation(cameraId, _activeCameraId, record)) {
return CCTV_ACTIVATION_RESULT.UNCHANGED;
}
_activeCameraId = cameraId;
_autoHopSuspended = false;
// A real activation creates projection work — wake the self-stopping loop.
startProjectionLoop();
if (previousActiveRecord && previousActiveRecord !== record) {
clearProbeClampOnDeactivation(previousActiveRecord, (previous) => {
applyFrustumGeometry(previous, groundAltFor(previous));
});
}
// The clicked camera leaves the ambient quota immediately (never graced).
// Shipped behavior publishes no card for it because the monitor plane is
// now the active representation; the opt-in protected-card path republishes
// it synchronously through refreshAmbientCards() below.
_cardIds.delete(cameraId);
_cardGraceState.delete(cameraId);
// Activating the hovered camera consumes the transient pin; the active
// monitor plane replaces it from this moment.
if (_hoverCardId === cameraId) clearHoverCard();
// If the record's geometry refinement is still queued, jump it to the front
// so the newly active camera resolves before idle neighbors.
const queueIdx = _geoQueue.indexOf(record);
if (queueIdx > 0) {
_geoQueue.splice(queueIdx, 1);
_geoQueue.unshift(record);
}
// §9.1: one obstruction probe per activation, BEFORE the geometry pass so
// the range clamp lands in the same rewrite. A FIRST-EVER activation (no
// real ground sample yet) probes from the catalog-prior altitude — if that
// prior is off, the clamp is measured from a shifted origin, but a
// re-activation after the one-shot snap lands re-probes from real ground,
// so it self-corrects.
runActivationObstructionProbe(record);
// Coverage is activation-lazy even while the mode is OFF: the active
// camera's projection representation must be ready without materializing
// any idle neighbor. The following geometry rewrite welds these entities to
// the current sampled positions.
ensureActiveCoverageEntities(record);
ensureProjectionRuntime(record);
refreshProjectionImage(record, true);
// FIX B9b: an explicit user (re)select re-arms one real ground sample for the
// newly-active camera, then freezes. Idle neighbors keep their resolved state.
// FIX B9c: if tiles are ready this real pass applies + re-resolves
// immediately; if tiles are still streaming, updateRecordGeometry's fallback
// guard recomputes purely from the cached real ground (the pose + the probe
// clamp above still land — no scene queries) and the record stays unresolved
// until update()'s one-shot tiles-ready completion pass re-grounds it.
rearmGroundResolution(record);
updateRecordGeometry(record);
record.activationDone = true;
refreshCoverageStyles();
// The newly active camera leaves the ambient ring (its monitor plane takes
// over); the freed slot re-fills on this same pass.
refreshAmbientCards();
// ADJUST mode follows the active camera.
_gizmo?.refresh();
notifyListeners();
return CCTV_ACTIVATION_RESULT.ACTIVATED;
}
/**
* Clears the active CCTV camera in place without moving the viewer or
* disabling the layer. The normal selection-refresh path releases the active
* projection, emphasis, and probe state while ambient cards remain available.
* @returns {boolean} True when a camera was deactivated.
*/
export function deactivateActiveCamera() {
const record = _activeCameraId ? _recordById.get(_activeCameraId) : null;
if (!record) return false;
_activeCameraId = null;
_autoHopSuspended = true;
record.activationDone = false;
clearProbeClampOnDeactivation(record, (previous) => {
applyFrustumGeometry(previous, groundAltFor(previous));
});
refreshCoverageStyles();
refreshAmbientCards();
_gizmo?.refresh();
notifyListeners();
return true;
}
/**
* True only for a clean click that is empty from CCTV's perspective: an
* active camera exists, ADJUST does not own the pointer, and the scene pick
* carries no canonical object ID. Any identified scene object is non-empty,
* including selectable siblings that do not participate in the pick registry.
* @param {Object|null} picked - `scene.pick()` result.
* @param {Object} [context]
* @param {string|null} [context.activeCameraId]
* @param {boolean} [context.calibrationMode]
* @returns {boolean}
*/
export function cctvEmptyClickDeselects(picked, {
activeCameraId = null,
calibrationMode = false,
} = {}) {
if (!activeCameraId || calibrationMode) return false;
return resolvePickId(picked) === null;
}
/**
* Creates the five Cesium polyline entities that visualize a camera's pitched
* frustum: 4 corner rays (mount → far-plane corner) + the closed far-plane
* rectangle. Entity ids stay in the `cctv-<id>-<role>` scheme (pick-owner
* regex depends on it): roles ray-tl / ray-tr / ray-br / ray-bl / cap.
* @param {Object} record - Camera record.
* @returns {Cesium.Entity[]} Array of five coverage entities.
*/
function buildCoverageEntities(record) {
const { camera } = record;
// Prefer the record's already-refined geometry. Lazy creation commonly
// happens after the staggered ground pass; recomputing from the catalog
// prior here would regress the camera to its pre-sampled datum.
let geometry = record.frustumGeometry;
let positions = record.frustumPositions;
if (!geometry || !positions) {
geometry = computeFrustumGeometry(
camera,
groundPriorAltFor(record),
record.probeClampRangeM
);
positions = frustumCartesians(geometry);
record.frustumGeometry = geometry;
record.frustumPositions = positions;
record.position = positions.mount;
}
const addPolyline = (role, linePositions) => _viewer.entities.add({
id: `cctv-${camera.id}-${role}`,
properties: { cctvCameraId: camera.id },
polyline: {
positions: linePositions,
width: 1.2,
material: IDLE_COVERAGE_COLOR,
},
});
const entities = [
addPolyline('ray-tl', [positions.mount, positions.tl]),
addPolyline('ray-tr', [positions.mount, positions.tr]),
addPolyline('ray-br', [positions.mount, positions.br]),
addPolyline('ray-bl', [positions.mount, positions.bl]),
addPolyline('cap', [positions.tl, positions.tr, positions.br, positions.bl, positions.tl]),
];
entities[0]._coverageRole = 'edge';
entities[1]._coverageRole = 'edge';
entities[2]._coverageRole = 'edge';
entities[3]._coverageRole = 'edge';
entities[4]._coverageRole = 'cap';
return entities;
}
/**
* Materializes coverage entities for eligible records exactly once.
* The helper is dependency-injected so unit tests can prove the enable policy
* without constructing Cesium entities.
*
* @param {Object[]} records CCTV runtime records.
* @param {(record: Object) => boolean} [isEligible] Eligibility predicate.
* @param {(record: Object) => Object[]} buildEntities Coverage builder.
* @returns {Object[]} Newly created entities across all eligible records.
*/
export function materializeCctvCoverageEntities(
records,
isEligible = () => true,
buildEntities,
) {
const created = [];
if (typeof buildEntities !== 'function') return created;
for (const record of Array.isArray(records) ? records : []) {
if (!record || record.coverageEntities?.length || !isEligible(record)) continue;
const entities = buildEntities(record);
record.coverageEntities = Array.isArray(entities) ? entities.filter(Boolean) : [];
created.push(...record.coverageEntities);
}
return created;
}
/** Materializes one active camera's coverage set. */
export function materializeCctvActiveCoverageEntities(record, buildEntities) {
return materializeCctvCoverageEntities([record], () => true, buildEntities);
}
/** Materializes only records in the current coverage-visible ID set. */
export function materializeCctvVisibleCoverageEntities(records, visibleIds, buildEntities) {
const eligibleIds = visibleIds instanceof Set ? visibleIds : new Set(visibleIds || []);
return materializeCctvCoverageEntities(
records,
(record) => eligibleIds.has(record.camera?.id),
buildEntities,
);
}
/** Registers newly built coverage entities with the layer-global collection. */
function registerCoverageEntities(created) {
_coverageEntities.push(...created);
return created;
}
function ensureActiveCoverageEntities(record) {
return registerCoverageEntities(
materializeCctvActiveCoverageEntities(record, buildCoverageEntities),
);
}
function ensureVisibleCoverageEntities(records, visibleIds) {
return registerCoverageEntities(
materializeCctvVisibleCoverageEntities(records, visibleIds, buildCoverageEntities),
);
}
/**
* Extracts a camera ID from a Cesium pick result by checking billboard IDs,
* primitive IDs, and entity cctvCameraId properties.
* @param {Object|null} picked - Result from scene.pick().
* @returns {string|null} Camera ID, or null if the pick is not a CCTV entity.
*/
function extractPickedCameraId(picked) {
if (!picked) return null;
const entity = picked.id?.properties ? picked.id : picked.primitive?.id?.properties ? picked.primitive.id : null;
const maybeProp = entity?.properties?.cctvCameraId;
if (maybeProp) {
const value = typeof maybeProp.getValue === 'function'
? maybeProp.getValue(Cesium.JulianDate.now())
: maybeProp;
const record = typeof value === 'string' ? _recordById.get(value) : null;
const ownsCoverageEntity = Boolean(record?.coverageEntities?.includes(entity));
const ownsProjectionEntity = record?.projection?.planeEntity === entity
|| _projectionEntities.some((runtime) => (
runtime?.cameraId === value && runtime.planeEntity === entity
));
if (record && (ownsCoverageEntity || ownsProjectionEntity)) return value;
}
// Camera billboard IDs are intentionally the upstream camera ID, so a
// sibling may legitimately use the same string. A bare ID match is not
// ownership proof: require this layer's billboard collection or the exact
// billboard stored on the record.
const directId = typeof picked.id === 'string'
? picked.id
: typeof picked.primitive?.id === 'string' ? picked.primitive.id : null;
const record = directId === null ? null : _recordById.get(directId);
if (!record) return null;
return picked.primitive === _billboards || picked.primitive === record.billboard
? directId
: null;
}
/** Test-only seam for the CCTV ownership proof used by the world-click route. */
export function _extractPickedCameraIdForTest(picked) {
return extractPickedCameraId(picked);
}
/**
* Removes all coverage entities and projection runtimes from the scene.
*/
function destroyCoverageEntities() {
if (!_viewer) return;
for (const entity of _coverageEntities) {
_viewer.entities.remove(entity);
}
_coverageEntities = [];
for (const record of _records) {
destroyViewshedVolume(record);
}
for (const runtime of _projectionEntities) {
destroyProjectionRuntime(runtime);
}
_projectionEntities = [];
}
/** Resets all module-scoped runtime state to initial values. */
function clearRuntimeState() {
stopGeometryLoadQueue();
// Idempotent — also covers a re-init without a prior destroy().
teardownAmbientCards();
clearProjectionOverlay();
_records = [];
_recordById = new Map();
_healthById = new Map();
_count = 0;
_lastUpdate = null;
_lastHealthSyncAt = 0;
_lastError = null;
_lastFocusStyleAt = 0;
_activeFocusStyleCount = 0;
// FIX ①/③: the discovered tileset handle is scene-scoped — drop it so a fresh
// init re-discovers against the current scene primitives.
_activeTileset = null;
// Task 5: the applied-regime tracker is record-set-scoped — a fresh init
// recomputes it against the then-current scene.
_lastAppliedRegime = null;
}
/**
* Primes the minimum module state needed to exercise the production coverage
* refresh path in unit tests.
* @param {Object} [options={}] Test state values.
* @param {Object|null} [options.viewer] Viewer-like entity owner.
* @param {Object[]} [options.records] Seeded CCTV records.
* @param {string|null} [options.activeCameraId] Active record id.
* @param {boolean} [options.enabled=true] Layer enabled state.
* @param {'off'|'on'|'viewshed'} [options.coverageMode='on'] Coverage mode.
* @param {boolean} [options.showProjection=false] Projection visibility.
* @returns {void}
*/
export function _setCctvCoverageStateForTest({
viewer = null,
records = [],
activeCameraId = null,
enabled = true,
coverageMode = 'on',
showProjection = false,
} = {}) {
_viewer = viewer;
_records = Array.isArray(records) ? records : [];
_recordById = new Map(
_records
.filter((record) => record?.camera?.id)
.map((record) => [record.camera.id, record]),
);
_coverageEntities = [];
_projectionEntities = [];
_billboards = null;
_activeCameraId = activeCameraId;
_autoHopSuspended = false;
_enabled = !!enabled;
_coverageMode = normalizeCoverageMode(coverageMode, 'on');
_showProjection = !!showProjection;
}
/**
* Flies the Cesium viewer camera to frame the specified CCTV camera,
* looking along its heading from above.
* @param {Cesium.Viewer|null} viewer Cesium viewer that owns the camera.
* @param {Object|null} record CCTV camera runtime record.
* @param {number} [duration=2.2] - Flight duration in seconds.
* @returns {'focused'|'no-active-camera'|'tracking-holds-view'|'cockpit-active'} Focus result.
*/
export function focusCctvRecord(viewer, record, duration = 2.2) {
if (!viewer || !record) return CCTV_FOCUS_RESULT.NO_ACTIVE_CAMERA;
if (typeof document !== 'undefined'
&& document.body?.classList.contains('cockpit-mode')) {
console.debug('[Data:CCTV] focus ignored while cockpit owns the camera');
return CCTV_FOCUS_RESULT.COCKPIT_ACTIVE;
}
if (viewer.trackedEntity) {
console.debug('[Data:CCTV] focus ignored while a tracked entity owns the camera');
return CCTV_FOCUS_RESULT.TRACKING_HOLDS_VIEW;
}
const { camera } = record;
const range = Math.max(280, camera.rangeM * 1.18);
viewer.camera.flyToBoundingSphere(
new Cesium.BoundingSphere(record.position, Math.max(40, camera.rangeM * 0.36)),
{
offset: new Cesium.HeadingPitchRange(
toRad(camera.headingDeg),
toRad(-22),
range
),
duration: Math.max(0.2, duration || 0),
easingFunction: Cesium.EasingFunction.CUBIC_IN_OUT,
}
);
return CCTV_FOCUS_RESULT.FOCUSED;
}
function focusCamera(cameraId, duration = 2.2) {
return focusCctvRecord(_viewer, _recordById.get(cameraId), duration);
}
/**
* Advances to the next camera if auto-hop is enabled and the hop interval
* has elapsed. If the viewer has panned to a new region since the last hop,
* snaps to the nearest camera instead of cycling sequentially.
* @param {number} nowMs - Current timestamp in milliseconds.
*/
export function maybeAutoHop(nowMs) {
if (!_autoHop || _autoHopSuspended || !_enabled || _records.length < 2) return;
if (nowMs - _lastHopAt < _autoHopSec * 1000) return;
const viewKey = currentViewContext();
const viewChanged = viewKey !== _lastViewContext;
_lastViewContext = viewKey;
if (viewChanged) {
const nearest = nearestCameraIdToViewer();
if (nearest && nearest !== _activeCameraId) {
// Use setActiveCamera so the full activation path runs (obstruction
// probe, projection runtime, geometry rewrite) — previously bypassed
// with a bare assignment
setActiveCamera(nearest);
_lastHopAt = nowMs;
return;
}
}
const nextIdx = cctvCycleIndex(
_records.findIndex((record) => record.camera.id === _activeCameraId),
1,
_records.length,
);
setActiveCamera(_records[nextIdx].camera.id);
_lastHopAt = nowMs;
}
/**
* Resolves a catalog cycle target, including the explicit no-selection state.
* NEXT from null selects the first record; PREV selects the last.
* @param {number} currentIdx
* @param {number} step
* @param {number} count
* @returns {number}
*/
export function cctvCycleIndex(currentIdx, step, count) {
const total = Number.isFinite(count) ? Math.floor(count) : 0;
if (total <= 0) return -1;
const delta = Number.isFinite(step) ? Math.trunc(step) : 1;
if (!Number.isFinite(currentIdx) || currentIdx < 0) {
return delta < 0 ? total - 1 : 0;
}
return (((Math.floor(currentIdx) + delta) % total) + total) % total;
}
/**
* Fetches per-camera health status from the backend and updates _healthById.
* Rate-limited to HEALTH_SYNC_INTERVAL_MS unless forced.
* @param {boolean} [force=false] - Bypass the interval check.
*/
async function syncHealthState(force = false) {
const now = Date.now();
if (!force && now - _lastHealthSyncAt < HEALTH_SYNC_INTERVAL_MS) return;
_lastHealthSyncAt = now;
try {
const resp = await fetch(HEALTH_ENDPOINT, { cache: 'no-store' });
if (!resp.ok) return;
const data = await resp.json();
const rows = Array.isArray(data?.cameras) ? data.cameras : [];
const next = new Map();
for (const row of rows) {
const id = String(row?.id || '').trim();
if (!id) continue;
next.set(id, {
status: String(row.status || '').toLowerCase() || 'unknown',
sourceKind: String(row.sourceKind || row.feedType || '').toLowerCase(),
label: String(row.label || row.provider || ''),
message: String(row.message || ''),
updatedAt: safeNumber(row.updatedAt, now),
});
}
_healthById = next;
} catch {
// keep previous health map
}
}
// ---------------------------------------------------------------------------
// Exported layer object — standard layer interface + CCTV-specific methods
// ---------------------------------------------------------------------------
/**
* CCTV data layer implementing the standard layer interface.
* Manages camera catalog, coverage visualization, the far-cap projection
* plane, health sync, calibration, and auto-hop.
*/
const cctvLayer = {
id: 'cctv',
name: 'CCTV',
icon: '📹',
source: 'CCTV + Street View fallback',
updateInterval: DEFAULT_UPDATE_INTERVAL_MS,
/**
* Initializes the CCTV layer: loads camera sources, builds the catalog,
* restores calibration from localStorage, creates billboards, sets up click
* handling, and performs initial health sync. Coverage entities stay lazy.
* @param {Cesium.Viewer} viewer - The Cesium viewer instance.
*/
async init(viewer) {
_viewer = viewer;
clearRuntimeState();
_enabled = false;
_activeCameraId = null;
_autoHopSuspended = false;
_lastHopAt = 0;
_lastViewContext = '';
_calibrationById = loadCalibrationStore();
_billboards = new Cesium.BillboardCollection();
_viewer.scene.primitives.add(_billboards);
registerSpriteCollection('cctv', _billboards);
const sources = await loadCameraSources();
const catalogFromSources = buildCatalogFromSources(sources);
const catalog = catalogFromSources.length ? catalogFromSources : seedCatalog();
// Viewshed color identity (design §3a): golden-angle hue over the
// id-SORTED catalog index — deterministic across sessions for a stable
// catalog, maximally separated for neighboring cameras.
const hueIndexById = new Map(
catalog.map((camera) => camera.id).sort().map((id, index) => [id, index])
);
for (const camera of catalog) {
const savedEntry = _calibrationById.get(camera.id);
if (savedEntry) {
camera.calibration = normalizeCalibration(savedEntry.values);
camera.calSource = savedEntry.source;
}
ensureCameraPose(camera);
}
// Task 5 (height-datum fix): batch ALL camera coords through the Re:Earth
// ellipsoidal ground-prior resolver (network-cached — NOT a scene query;
// the catalog's orthometric groundElevationM feeds the geoid fallback
// chain). Bounded wait: a warm proxy cache resolves in milliseconds, so
// records are normally built WITH their prior (correct first paint in
// every regime); a cold/slow upstream loses the race and the batch
// applies post-hoc via applyLateGroundPriors instead of hanging init.
const priorsPromise = resolveGroundPriors(catalog);
const priors = await Promise.race([
priorsPromise,
new Promise((resolve) => setTimeout(() => resolve(null), GROUND_PRIOR_INIT_WAIT_MS)),
]);
for (let i = 0; i < catalog.length; i++) {
const camera = catalog[i];
// Ellipsoidal ground prior (or null while the batch is still in
// flight). Geometry falls back to the catalog value only until the
// batch lands.
const groundPrior = priors?.[i] || null;
// Cheap first-pass altitude from the ellipsoidal prior (catalog value
// only as the pre-prior fallback) — the staggered geometry queue
// refines with sampled tile heights after enable so the init path
// never raycasts the scene once per camera.
const priorGround = Number.isFinite(groundPrior?.ellipsoid)
? groundPrior.ellipsoid
: (Number(camera.groundElevationM) || 0);
camera.absoluteHeightM = priorGround + camera.mountHeightM;
const position = Cesium.Cartesian3.fromDegrees(camera.lon, camera.lat, camera.absoluteHeightM);
const billboard = _billboards.add({
id: camera.id,
image: CAMERA_ICON,
position,
color: IDLE_CAMERA_COLOR,
width: 24,
height: 24,
// Field-test fix (2026-07-06): always-on-top. The old finite value
// (1800 m) re-engaged the depth test at far zoom, where the COARSE
// far-LOD Google-3D mesh sits above the true ground and swallowed
// ground-anchored icons ("submerged" pills over SF). Far-side-of-globe
// icons are handled by refreshHorizonCulling() (the flights-layer
// EllipsoidalOccluder pattern), not by the depth test.
disableDepthTestDistance: Number.POSITIVE_INFINITY,
scaleByDistance: new Cesium.NearFarScalar(350, 1.25, 4_000_000, 0.42),
});
const record = {
camera,
position,
billboard,
coverageEntities: [],
projection: null,
// Task 5 (height-datum fix): regime-aware ground resolution state.
// groundPrior — { ellipsoid, source } from the Re:Earth batch
// (null until a late batch lands). The prior applies in EVERY
// regime and is the terrain-globe resolution outright.
// groundResolved — PER-REGIME one-shot latch (regime key →
// boolean): true once this record's resolution completed for that
// regime; such records are excluded from the completion pass so
// their geometry freezes. Re-armed only on a genuine pose change,
// explicit user select/move, or a surface-regime change — never
// on the 10s timer.
// groundSamples — PER-REGIME resolved ground (regime key →
// metres): the accepted one-shot scene sample in google-3d, the
// mirrored prior in terrain-globe. Kept across re-arms as the
// "has ever resolved" memory for the B9c mid-stream guard.
// frustumPositions — cached Cartesians for pure recomputes (so
// plane placement never re-derives geometry it already has).
groundPrior,
groundResolved: {},
groundSamples: {},
frustumGeometry: null,
frustumPositions: null,
// §9.1 activation obstruction probe result: effective-range clamp so
// the far-cap plane never clips into the tiles. Null = unclamped.
// Reset + re-probed on every activation; cleared when the user takes
// the range slider (slider overrides the clamp).
probeClampRangeM: null,
// Viewshed (design §3a/§3b): per-camera color identity + the volume
// primitive handle (exists only in viewshed mode for the visible set).
viewshedColors: viewshedColors(cameraHue(hueIndexById.get(camera.id) ?? 0)),
viewshedPrimitive: null,
viewshedActiveTint: false,
};
_records.push(record);
_recordById.set(camera.id, record);
}
_count = _records.length;
if (_records.length > 0) {
// Projection runtime + first frame fetch are deferred to enable() so
// initializing the catalog stays render-cheap.
_activeCameraId = _records[0].camera.id;
}
// Task 5: if the prior batch lost init's bounded race, apply it post-hoc
// when it lands (pure recomputes — applyLateGroundPriors guards against
// a torn-down/re-inited catalog).
if (!priors) {
const initRecords = _records.slice();
priorsPromise.then((late) => {
if (late) applyLateGroundPriors(initRecords, late);
}).catch(() => {});
}
// Task 5: track the surface regime the initial geometry was computed for
// and listen for map-stack changes (main.js re-dispatches
// MapStackController.onChange as this CustomEvent). The handler compares
// regimes itself, so 'switching'/'error' emissions and same-regime stack
// swaps (bing→osm) no-op.
_lastAppliedRegime = currentSurfaceRegime();
if (!_mapStackListener && typeof window !== 'undefined') {
_mapStackListener = () => handleMapStackChanged();
window.addEventListener('gev:map-stack-changed', _mapStackListener);
}
// Field-test fix (2026-07-06): horizon-cull on camera settle (pairs with
// the billboards' always-on-top depth setting) + one initial pass so the
// first paint is already culled.
if (!_horizonCullListener) {
// Ambient cards piggyback the same settle event: moveEnd-driven
// reselection only, never per frame (refreshAmbientCards no-ops while
// the layer is disabled).
_horizonCullListener = () => {
_cameraMoving = false;
refreshHorizonCulling();
refreshAmbientCards();
};
_viewer.camera.moveEnd.addEventListener(_horizonCullListener);
}
if (!_moveStartListener) {
// Item B: hover picking pauses while the camera is in motion.
_moveStartListener = () => {
_cameraMoving = true;
};
_viewer.camera.moveStart.addEventListener(_moveStartListener);
}
refreshHorizonCulling();
_clickHandler = new Cesium.ScreenSpaceEventHandler(_viewer.scene.canvas);
bindCctvWorldClickGesture(_clickHandler, (click) => {
if (!_enabled) return;
const picked = _viewer.scene.pick(click.position);
const cameraId = extractPickedCameraId(picked);
if (cameraId) {
activateCctvCameraFromWorldClick(cameraId, setActiveCamera);
return;
}
// Any identified scene object owns this click even if its layer does not
// register a shared pick predicate. This keeps selectable siblings ahead
// of an overlapping CCTV card while ID-less globe/terrain/tile surfaces
// remain eligible for true empty-space deselection.
const pickedId = resolvePickId(picked);
if (pickedId !== null) return;
// Item A (follow-up round 2): the scene pick found no camera — try the
// painted ambient cards. The cards canvas is pointer-events:none (this
// handler owns the events), so a click landing on a card's rect selects
// its camera exactly like a click on the icon. Cesium click positions
// and the recorded rects are both CSS px — direct comparison.
const cardId = _cctvOverlayHost.hitTest(
click.position.x,
click.position.y,
{ sourceId: CCTV_OVERLAY_SOURCE_ID },
)?.entryId;
if (cardId && _recordById.has(cardId)) {
activateCctvCameraFromWorldClick(cardId, setActiveCamera);
return;
}
if (cctvEmptyClickDeselects(picked, {
activeCameraId: _activeCameraId,
calibrationMode: _calibrationMode,
})) {
deactivateActiveCamera();
}
}, {
// Item B: hover summons a card on a cardless camera icon. The gesture
// classifier owns MOUSE_MOVE too, so chain hover work through its seam
// instead of replacing the travel accumulator's handler.
onMouseMove: (movement) => handleHoverMove(movement?.endPosition),
});
await syncHealthState(true);
refreshCoverageStyles();
notifyListeners();
restoreSpriteOrder(_viewer);
console.log('[Data:CCTV] Initialized with', _count, 'cameras');
},
/**
* Enables the layer: shows entities, starts the projection loop, and kicks
* the staggered geometry-load queue. Heavy work (per-camera ground
* sampling) is deferred/batched so the frame budget never collapses at
* enable time.
*/
enable() {
_enabled = true;
_lastUpdate = Date.now();
// Pick-ownership (H2): camera billboards use the camera id directly;
// coverage polyline entities use `cctv-<cameraId>-<role>` entity ids.
registerPickOwner('cctv', (pickedId) => {
if (_recordById.has(pickedId)) return true;
if (typeof pickedId === 'string' && pickedId.startsWith(GIZMO_ID_PREFIX)) return true;
const coverage = /^cctv-(.+)-(?:ray-tl|ray-tr|ray-br|ray-bl|cap|plane|plane-label)$/.exec(pickedId);
return Boolean(coverage && _recordById.has(coverage[1]));
});
if (!_activeCameraId && _records.length) {
_activeCameraId = _records[0].camera.id;
_autoHopSuspended = false;
}
const activeRecord = getActiveRecord();
if (activeRecord) {
ensureProjectionRuntime(activeRecord);
refreshProjectionImage(activeRecord, true);
}
startGeometryLoadQueue();
refreshCoverageStyles();
startProjectionLoop();
// The projection loop self-stops when idle; a focus target appearing
// (user starts tracking a contact) is the one edge it can't see while
// stopped, so re-arm on it. Removed on disable.
_removeFocusAppearListener?.();
_removeFocusAppearListener = onFocusTargetAppear(() => startProjectionLoop());
// Ambient card tier: shared host source + policy-gated frame pacer + the
// initial selection pass (moveEnd drives every later reselection).
_cctvOverlayHost.setVisible(CCTV_OVERLAY_SOURCE_ID, true);
startCardFrameLoop();
refreshAmbientCards();
notifyListeners();
restoreSpriteOrder(_viewer);
},
/** Disables the layer: hides entities, stops the projection loop and load queue. */
disable() {
_enabled = false;
unregisterPickOwner('cctv');
// ADJUST mode does not survive a layer toggle — predictable re-entry.
_calibrationMode = false;
releaseContinuousRender('cctv-adjust');
_gizmo?.setEnabled(false);
_removeFocusAppearListener?.();
_removeFocusAppearListener = null;
stopProjectionLoop();
stopGeometryLoadQueue();
// Ambient cards tear down COMPLETELY on disable (product design point 6):
// source entries, pacer timer, in-flight handlers, and caches.
teardownAmbientCards();
hideCctvVisuals();
notifyListeners();
},
/**
* Periodic update tick: syncs health state and runs auto-hop logic. Ground
* geometry is NOT resampled here — v2 grounds each camera once via the
* staggered load queue (see startGeometryLoadQueue/updateRecordGeometry)
* and never resamples on a timer. The ONE exception is a one-shot
* completion pass: the enable-time drain can run while 3D tiles are still
* streaming (each such pass keeps the fabricated catalog height and leaves
* the record `!groundResolved`), so the FIRST tick that sees
* projectionTilesReady() re-enqueues those records once — each then takes
* its single real sample and freezes (design §4). Guarded by a boolean
* latch (`_tilesReadyReenqueued`), NOT a timer loop: after it fires, no
* tick ever samples anything again.
*/
async update() {
if (!_enabled) return;
const now = Date.now();
_lastUpdate = now;
if (!_tilesReadyReenqueued && projectionTilesReady()) {
_tilesReadyReenqueued = true;
// Per-regime resolution (Task 5): only records unresolved for the
// CURRENT surface regime need the completion pass. On globe stacks
// projectionTilesReady() is false while a (hidden) Google tileset
// exists, so this latch effectively fires for the google-3d regime —
// terrain-globe records resolve from the prior in their drain pass.
const unresolved = _records.filter((record) => !isGroundResolved(record));
if (unresolved.length) enqueueGeometryRefresh(unresolved);
}
await syncHealthState();
maybeAutoHop(now);
notifyListeners();
},
/**
* Tears down the layer: destroys click handler, projection loop, coverage
* entities, billboards, and clears all runtime state and subscribers.
* @param {Cesium.Viewer} [viewer] - Viewer instance (falls back to stored ref).
*/
destroy(viewer) {
unregisterPickOwner('cctv');
if (_mapStackListener && typeof window !== 'undefined') {
window.removeEventListener('gev:map-stack-changed', _mapStackListener);
_mapStackListener = null;
}
const teardownViewer = viewer || _viewer;
if (_horizonCullListener && teardownViewer?.camera?.moveEnd) {
teardownViewer.camera.moveEnd.removeEventListener(_horizonCullListener);
_horizonCullListener = null;
}
if (_moveStartListener && teardownViewer?.camera?.moveStart) {
teardownViewer.camera.moveStart.removeEventListener(_moveStartListener);
_moveStartListener = null;
}
if (_gizmo) {
_gizmo.destroy();
_gizmo = null;
}
_calibrationMode = false;
releaseContinuousRender('cctv-adjust');
if (_clickHandler) {
_clickHandler.destroy();
_clickHandler = null;
}
if (teardownViewer?.scene?.screenSpaceCameraController) {
teardownViewer.scene.screenSpaceCameraController.enableInputs = true;
}
stopProjectionLoop();
stopGeometryLoadQueue();
teardownAmbientCards();
destroyCoverageEntities();
if (_billboards && teardownViewer) {
teardownViewer.scene.primitives.remove(_billboards);
_billboards = null;
}
clearRuntimeState();
_viewer = null;
_enabled = false;
_activeCameraId = null;
_autoHopSuspended = false;
// Clear existing subscribers rather than replacing the Set —
// replacing would silently orphan any unsubscribe() closures
_listeners.clear();
},
/**
* Applies runtime parameter changes: coverage/projection toggles, auto-hop
* settings, camera selection, and calibration patches/resets.
* @param {Object} [params={}] - Parameter object.
* @param {boolean} [params.showCoverage] - Back-compat coverage toggle (true→'on', false→'off').
* @param {'off'|'on'|'viewshed'} [params.coverageMode] - Full coverage-mode API.
* @param {boolean} [params.showProjection] - Toggle projection overlay visibility.
* @param {boolean} [params.autoHop] - Enable/disable auto-hop.
* @param {number} [params.autoHopSec] - Auto-hop interval in seconds.
* @param {string} [params.selectedCameraId] - Camera ID to activate.
* @param {Object} [params.calibration] - Calibration config: `patch` edits
* the live pose (save-gated — no persistence), `save` persists the current
* calibration as manual, `reset` restores the base prior.
* @param {boolean} [params.calibrationMode] - Toggle the ADJUST gizmo.
* @param {boolean} [params.focusSelected] - Fly to the active camera.
* @param {number} [params.focusDurationSec] - Fly-to duration.
*/
setParams(params = {}) {
if (typeof params.showCoverage === 'boolean') {
_coverageMode = normalizeCoverageMode(params.showCoverage, _coverageMode);
}
if (typeof params.coverageMode === 'string') {
_coverageMode = normalizeCoverageMode(params.coverageMode, _coverageMode);
}
if (typeof params.showProjection === 'boolean') {
_showProjection = params.showProjection;
if (_showProjection) {
const active = getActiveRecord();
if (active) ensureProjectionRuntime(active);
startProjectionLoop();
}
}
if (typeof params.autoHop === 'boolean') {
_autoHop = params.autoHop;
if (params.autoHop) _autoHopSuspended = false;
}
if (typeof params.autoHopSec === 'number' && Number.isFinite(params.autoHopSec)) {
_autoHopSec = clamp(Math.round(params.autoHopSec), MIN_AUTO_HOP_SEC, MAX_AUTO_HOP_SEC);
}
if (typeof params.selectedCameraId === 'string' && _recordById.has(params.selectedCameraId)) {
setActiveCamera(params.selectedCameraId);
}
if (params.calibration && typeof params.calibration === 'object') {
const calibrationCfg = params.calibration;
const targetCameraId = typeof calibrationCfg.cameraId === 'string' && calibrationCfg.cameraId
? calibrationCfg.cameraId
: _activeCameraId;
const targetRecord = targetCameraId ? _recordById.get(targetCameraId) : null;
if (targetRecord) {
if (calibrationCfg.reset) {
// RESET: back to the base prior, delete the persisted entry, clear
// the dirty flag (semantics unchanged from v2).
targetRecord.camera.calibration = normalizeCalibration(DEFAULT_CAMERA_CALIBRATION);
targetRecord.camera.calSource = null;
targetRecord.calDirty = false;
ensureCameraPose(targetRecord.camera);
_calibrationById.delete(targetCameraId);
saveCalibrationStore();
// Reset returns to the base lat/lon, so resolve that anchor once.
resolveCommittedGroundAnchor(targetRecord);
refreshProjectionImage(targetRecord, true);
}
if (calibrationCfg.patch && typeof calibrationCfg.patch === 'object') {
// Save-gated persistence (design §3e): a patch edits the LIVE pose
// only. The store — and the CALIBRATED badge's `calSource` — move
// exclusively on the explicit `save` action below. (§9.1 range-slider
// clamp override + B9b re-ground live inside applyCalibrationPatch.)
applyCalibrationPatch(targetRecord, calibrationCfg.patch);
}
if (calibrationCfg.save) {
// SAVE CAL: persist the current in-memory calibration with manual
// provenance. Saving an all-default calibration clears the entry
// (a no-op calibration is not a calibration).
if (isDefaultCalibration(targetRecord.camera.calibration)) {
targetRecord.camera.calSource = null;
_calibrationById.delete(targetCameraId);
} else {
targetRecord.camera.calSource = 'manual';
_calibrationById.set(targetCameraId, {
values: { ...targetRecord.camera.calibration },
source: 'manual',
savedAt: Date.now(),
});
}
targetRecord.calDirty = false;
saveCalibrationStore();
}
}
}
if (typeof params.calibrationMode === 'boolean') {
_calibrationMode = params.calibrationMode;
if (_calibrationMode) {
ensureGizmo();
_gizmo?.setEnabled(true);
// ADJUST mode: gizmo drags mutate entity geometry from pointer events,
// which don't trigger renders in requestRenderMode. (perf wave 2)
holdContinuousRender('cctv-adjust');
} else {
releaseContinuousRender('cctv-adjust');
_gizmo?.setEnabled(false);
}
}
if (params.focusSelected && _activeCameraId) {
focusCamera(_activeCameraId, Number(params.focusDurationSec) || 1.8);
}
refreshCoverageStyles();
notifyListeners();
},
/**
* Returns the current runtime parameters including toggle states,
* active camera, and calibration values.
* @returns {Object}
*/
getParams() {
const active = getActiveRecord();
return {
showCoverage: _coverageMode !== 'off',
coverageMode: _coverageMode,
showProjection: _showProjection,
calibrationMode: _calibrationMode,
autoHop: _autoHop,
autoHopSec: _autoHopSec,
selectedCameraId: active?.camera.id || null,
calibration: active?.camera ? {
cameraId: active.camera.id,
values: { ...normalizeCalibration(active.camera.calibration) },
} : null,
};
},
/**
* Returns a sampled list of camera positions for the detection overlay system.
* @param {Object} [options={}]
* @param {number} [options.maxCount] - Maximum number of objects to return.
* @param {number} [options.seed] - Offset seed for deterministic stride sampling.
* @returns {{ position: Cesium.Cartesian3, id: string, type: string }[]}
*/
getDetectableObjects(options = {}) {
if (!_enabled || _records.length === 0) return [];
const maxCount = Number.isFinite(options.maxCount)
? Math.max(1, Math.floor(options.maxCount))
: _records.length;
const seed = Number.isFinite(options.seed) ? Math.floor(options.seed) : 0;
const stride = Math.max(1, Math.ceil(_records.length / maxCount));
const start = seed % stride;
const objects = [];
for (let i = start; i < _records.length; i += stride) {
const camera = _records[i].camera;
objects.push({
position: _records[i].position,
sourceId: camera.id,
id: `CAM-${camera.id}`,
type: 'CAM',
});
if (objects.length >= maxCount) break;
}
return objects;
},
/**
* Returns basic layer statistics, including initial-load progress while
* the staggered geometry queue is draining.
* @returns {{ count: number, lastUpdate: number|null, error: string|null, loading: boolean, loadingLoaded: number, loadingTotal: number }}
*/
getStats() {
return {
count: _count,
lastUpdate: _lastUpdate,
error: _lastError,
loading: _geoLoading,
loadingLoaded: Math.min(_geoLoadDone, _geoLoadTotal),
loadingTotal: _geoLoadTotal,
};
},
/**
* Registers a callback that receives the full UI state on every change.
* The callback is invoked immediately with the current state.
* @param {Function} callback - Listener function receiving the UI state object.
* @returns {Function} Unsubscribe function.
*/
subscribe(callback) {
if (typeof callback !== 'function') return () => {};
_listeners.add(callback);
callback(uiState());
return () => {
_listeners.delete(callback);
};
},
/**
* Returns the current UI state snapshot without subscribing.
* @returns {Object}
*/
getUIState() {
return uiState();
},
/**
* Opts the active camera into or out of protected thumbnail publication.
* The default is false: the monitor plane remains the sole active-camera
* representation while ambient and hover-pinned cards continue unchanged.
* @param {Object} [options]
* @param {boolean} [options.activeCameraCardEnabled=false]
* @returns {{activeCameraCardEnabled:boolean}}
*/
setCardPresentationOptions(options = {}) {
return setCctvCardPresentationOptions(options);
},
/**
* Selects a camera by ID and optionally flies to it.
* @param {string} cameraId - Camera ID to select.
* @param {Object} [options={}]
* @param {boolean} [options.focus] - If true, fly the viewer to the camera.
* @param {number} [options.durationSec] - Fly-to duration in seconds.
* @returns {boolean} True if the camera was found and selected.
*/
selectCamera(cameraId, options = {}) {
const result = setActiveCamera(cameraId);
if (result === CCTV_ACTIVATION_RESULT.NOT_FOUND) return false;
if (options.focus) {
focusCamera(cameraId, options.durationSec || 1.8);
}
return true;
},
/**
* Flies the viewer to a specific camera.
* @param {string} cameraId - Camera ID to focus on.
* @param {number} [durationSec=2.2] - Flight duration in seconds.
* @returns {'focused'|'no-active-camera'|'tracking-holds-view'|'cockpit-active'} Focus result.
*/
focusCamera(cameraId, durationSec = 2.2) {
return focusCamera(cameraId, durationSec);
},
/**
* Cycles the active camera forward or backward by `step` positions in the catalog.
* @param {number} [step=1] - Number of positions to advance (negative to go back).
* @param {Object} [options={}]
* @param {boolean} [options.focus] - If true, fly to the new camera.
* @param {number} [options.durationSec] - Fly-to duration in seconds.
* @returns {string|null} The newly active camera ID, or null if catalog is empty.
*/
cycleCamera(step = 1, options = {}) {
if (!_records.length) return null;
const current = getActiveRecord();
const nextIdx = cctvCycleIndex(
_records.findIndex((record) => record === current),
step,
_records.length,
);
const nextId = _records[nextIdx].camera.id;
setActiveCamera(nextId);
if (options.focus) {
focusCamera(nextId, options.durationSec || 1.8);
}
return nextId;
},
/**
* Selects and flies to the camera nearest the current viewer position.
* @param {Object} [options={}]
* @param {boolean} [options.focus=true] Whether to fly after selection.
* @param {number} [options.durationSec] - Fly-to duration in seconds.
* @returns {string|null} The nearest camera ID, or null if none found.
*/
focusNearest(options = {}) {
const nearest = nearestCameraIdToViewer();
if (!nearest) return null;
setActiveCamera(nearest);
if (options.focus !== false) {
focusCamera(nearest, options.durationSec || 1.8);
}
return nearest;
},
};
export default cctvLayer;