Files
gods-eye-view/src/layers/cctv/controls.js
T
Sameh Khamis 93942d0dbe Show only the CCTV cameras in view, thinned to one per ground cell when zoomed out
The CCTV layer kept every loaded camera live: each view change touched every
icon, every notification rebuilt every camera's state, and the picker listed
the whole catalog. With the default 4,000 cameras, a continental drag ran at
152-179 fps with 18-24 frames over 30 ms (worst 112 ms). It now runs at
235 fps with none. The layer now:

- shows icons only on or near the screen, and when zoomed out keeps one camera
  per world-anchored cell (healthy feeds first), so panning keeps the same
  cameras;
- grounds and draws coverage only for the cameras in view, the active camera
  and its coverage neighbours, retrying a camera at most twice per view regime;
- reruns the view pass while the camera moves, paced by its own cost, and
  projects with one matrix per pass instead of a Cesium call per camera;
- keeps the billboard buffer-usage hint fixed, so showing or hiding a few
  icons no longer rewrites the vertex data of every billboard;
- lists the cameras in view (active camera first) in the picker, closing with
  the count of cameras outside the view, and builds the full camera list in
  the UI state only when it is read.
2026-10-29 21:31:59 -07:00

358 lines
14 KiB
JavaScript

import {
DEFAULT_UPDATE_INTERVAL_MS,
MIN_AUTO_HOP_SEC,
MAX_AUTO_HOP_SEC,
DEFAULT_CAMERA_CALIBRATION,
CALIBRATION_RANGE_FLOOR_M,
} from './policy.js';
export function createControls({ state: layerState, services, parts, source }) {
const { holdContinuousRender, releaseContinuousRender } = services.render;
const { CCTV_ACTIVATION_RESULT } = services.activation;
const methods = {
id: 'cctv',
name: 'CCTV',
icon: '📹',
source: 'CCTV + Street View fallback',
updateInterval: DEFAULT_UPDATE_INTERVAL_MS,
/**
* 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') {
layerState._coverageMode = parts.model.normalizeCoverageMode(
params.showCoverage,
layerState._coverageMode,
);
}
if (typeof params.coverageMode === 'string') {
layerState._coverageMode = parts.model.normalizeCoverageMode(
params.coverageMode,
layerState._coverageMode,
);
}
if (typeof params.showProjection === 'boolean') {
layerState._showProjection = params.showProjection;
if (layerState._showProjection) {
const active = parts.selection.getActiveRecord();
if (active) parts.projection.ensureProjectionRuntime(active);
parts.projection.startProjectionLoop();
}
}
if (typeof params.autoHop === 'boolean') {
layerState._autoHop = params.autoHop;
if (params.autoHop) layerState._autoHopSuspended = false;
}
if (
typeof params.autoHopSec === 'number' &&
Number.isFinite(params.autoHopSec)
) {
layerState._autoHopSec = parts.model.clamp(
Math.round(params.autoHopSec),
MIN_AUTO_HOP_SEC,
MAX_AUTO_HOP_SEC,
);
}
if (
typeof params.selectedCameraId === 'string' &&
layerState._recordById.has(params.selectedCameraId)
) {
parts.selection.setActiveCamera(params.selectedCameraId);
}
if (params.calibration && typeof params.calibration === 'object') {
const calibrationCfg = params.calibration;
const targetCameraId =
typeof calibrationCfg.cameraId === 'string' && calibrationCfg.cameraId
? calibrationCfg.cameraId
: layerState._activeCameraId;
const targetRecord = targetCameraId
? layerState._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 =
parts.calibration.normalizeCalibration(
DEFAULT_CAMERA_CALIBRATION,
);
targetRecord.camera.calSource = null;
targetRecord.calDirty = false;
parts.model.ensureCameraPose(targetRecord.camera);
layerState._calibrationById.delete(targetCameraId);
parts.calibration.saveCalibrationStore();
// Reset returns to the base lat/lon, so resolve that anchor once,
// and the footprint under the restored pose.
parts.ground.resolveCommittedGroundAnchor(targetRecord);
void parts.ground.resolveFootprintGround(targetRecord);
parts.frames.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.)
parts.calibration.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 (
parts.calibration.isDefaultCalibration(
targetRecord.camera.calibration,
)
) {
targetRecord.camera.calSource = null;
layerState._calibrationById.delete(targetCameraId);
} else {
targetRecord.camera.calSource = 'manual';
layerState._calibrationById.set(targetCameraId, {
values: { ...targetRecord.camera.calibration },
source: 'manual',
savedAt: Date.now(),
// Authored against the current range floor: never migrated.
rangeFloorM: CALIBRATION_RANGE_FLOOR_M,
});
}
targetRecord.calDirty = false;
parts.calibration.saveCalibrationStore();
}
}
}
if (typeof params.calibrationMode === 'boolean') {
layerState._calibrationMode = params.calibrationMode;
if (layerState._calibrationMode) {
parts.calibration.ensureGizmo();
layerState._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');
layerState._gizmo?.setEnabled(false);
}
}
if (params.focusSelected && layerState._activeCameraId) {
parts.navigation.focusCamera(
layerState._activeCameraId,
Number(params.focusDurationSec) || 1.8,
);
}
parts.rendering.refreshCoverageStyles();
parts.presentation.notifyListeners();
},
/**
* Returns the current runtime parameters including toggle states,
* active camera, and calibration values.
* @returns {Object}
*/
getParams() {
const active = parts.selection.getActiveRecord();
return {
showCoverage: layerState._coverageMode !== 'off',
coverageMode: layerState._coverageMode,
showProjection: layerState._showProjection,
calibrationMode: layerState._calibrationMode,
autoHop: layerState._autoHop,
autoHopSec: layerState._autoHopSec,
selectedCameraId: active?.camera.id || null,
calibration: active?.camera
? {
cameraId: active.camera.id,
values: {
...parts.calibration.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 = {}) {
// The cameras the view pass shows, not icons it has hidden.
const records = layerState._viewRecords;
if (!layerState._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,
// Short semantic code where the id is opaque (see cameraDisplayCode).
id: `CAM-${camera.code || 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: layerState._count,
lastUpdate: layerState._lastUpdate,
error: layerState._lastError,
loading: layerState._geoLoading,
loadingLoaded: Math.min(
layerState._geoLoadDone,
layerState._geoLoadTotal,
),
loadingTotal: layerState._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 () => {};
layerState._listeners.add(callback);
callback(parts.presentation.uiState());
return () => {
layerState._listeners.delete(callback);
};
},
/**
* Returns the current UI state snapshot without subscribing.
* @returns {Object}
*/
getUIState() {
return parts.presentation.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 parts.cards.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 = parts.selection.setActiveCamera(cameraId);
if (result === CCTV_ACTIVATION_RESULT.NOT_FOUND) return false;
if (options.focus) {
parts.navigation.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 parts.navigation.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 (!layerState._records.length) return null;
const current = parts.selection.getActiveRecord();
const nextIdx = parts.navigation.cctvCycleIndex(
layerState._records.findIndex((record) => record === current),
step,
layerState._records.length,
);
const nextId = layerState._records[nextIdx].camera.id;
parts.selection.setActiveCamera(nextId);
if (options.focus) {
parts.navigation.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 = parts.navigation.nearestCameraIdToViewer();
if (!nearest) return null;
parts.selection.setActiveCamera(nearest);
if (options.focus !== false) {
parts.navigation.focusCamera(nearest, options.durationSec || 1.8);
}
return nearest;
},
};
return { methods };
}