refactor(cctv): separate camera source and scene components

This commit is contained in:
Sameh Khamis committed 2026-09-13 15:02:32 -07:00
1 parent ca5f5fff93
commit 519bc6c362
32 files changed
+6873 -4835

No files matched your search

+352
View File
@@ -0,0 +1,352 @@
import {
DEFAULT_UPDATE_INTERVAL_MS,
MIN_AUTO_HOP_SEC,
MAX_AUTO_HOP_SEC,
DEFAULT_CAMERA_CALIBRATION,
} 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.
parts.ground.resolveCommittedGroundAnchor(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(),
});
}
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 = {}) {
if (!layerState._enabled || layerState._records.length === 0) return [];
const maxCount = Number.isFinite(options.maxCount)
? Math.max(1, Math.floor(options.maxCount))
: layerState._records.length;
const seed = Number.isFinite(options.seed) ? Math.floor(options.seed) : 0;
const stride = Math.max(
1,
Math.ceil(layerState._records.length / maxCount),
);
const start = seed % stride;
const objects = [];
for (let i = start; i < layerState._records.length; i += stride) {
const camera = layerState._records[i].camera;
objects.push({
position: layerState._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: 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 };
}