mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
refactor(cctv): separate camera source and scene components
This commit is contained in:
1 parent
ca5f5fff93
commit
519bc6c362
32 files changed
+6873
-4835
No files matched your search
@@ -0,0 +1,404 @@
|
||||
import {
|
||||
createFrameSlot,
|
||||
CCTV_OVERLAY_SOURCE_ID,
|
||||
declutterCctvCards,
|
||||
planFrameCachePrune,
|
||||
createCctvThumbnailOverlayEntry,
|
||||
CCTV_FRAME_CANVAS_W,
|
||||
CCTV_FRAME_CANVAS_H,
|
||||
applyFrameResult,
|
||||
} from '../../data/cctvCards.js';
|
||||
import * as Cesium from 'cesium';
|
||||
import { horizonOccluder } from '../../data/iconOrientation.js';
|
||||
import { selectCctvLod, applyEvictionGrace } from '../../data/cctvLod.js';
|
||||
import {
|
||||
CCTV_OVERLAY_SOURCE_OPTIONS,
|
||||
CARD_VIEW_MARGIN,
|
||||
CCTV_AMBIENT_CARD_DRAIN_CAP,
|
||||
CARD_GAP_PX,
|
||||
CARD_FETCH_TICK_MS,
|
||||
} from './policy.js';
|
||||
|
||||
export function createCards({ state: layerState, services, parts, source }) {
|
||||
/**
|
||||
* 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}}
|
||||
*/
|
||||
|
||||
function setCctvCardPresentationOptions({
|
||||
activeCameraCardEnabled = false,
|
||||
} = {}) {
|
||||
layerState._activeCameraCardEnabled = activeCameraCardEnabled === true;
|
||||
if (layerState._enabled) pushAmbientCardEntries();
|
||||
layerState._viewer?.scene?.requestRender?.();
|
||||
|
||||
return { activeCameraCardEnabled: layerState._activeCameraCardEnabled };
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Ambient card tier (2026-07-29 design — spec:
|
||||
// docs/superpowers/specs/2026-07-29-cctv-ambient-cards-design.md)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/** Returns (creating on demand) the stable frame slot for a camera id. */
|
||||
|
||||
function ensureCardFrameSlot(cameraId) {
|
||||
let slot = layerState._cardFrameSlots.get(cameraId);
|
||||
if (!slot) {
|
||||
slot = createFrameSlot();
|
||||
layerState._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 (
|
||||
!layerState._enabled ||
|
||||
!layerState._viewer ||
|
||||
layerState._viewer.isDestroyed() ||
|
||||
!layerState._records.length
|
||||
) {
|
||||
layerState._cctvOverlayHost.setEntries(
|
||||
CCTV_OVERLAY_SOURCE_ID,
|
||||
[],
|
||||
CCTV_OVERLAY_SOURCE_OPTIONS,
|
||||
);
|
||||
return;
|
||||
}
|
||||
const scene = layerState._viewer.scene;
|
||||
const carto = layerState._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 = layerState._activeCameraId;
|
||||
const occluder = horizonOccluder(layerState._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 layerState._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: parts.model.haversineKm(
|
||||
viewerLat,
|
||||
viewerLon,
|
||||
record.camera.lat,
|
||||
record.camera.lon,
|
||||
),
|
||||
inView,
|
||||
isVideo: parts.model.isVideoFeedType(
|
||||
parts.model.normalizeFeedType(record.camera.feedType),
|
||||
),
|
||||
sx,
|
||||
sy,
|
||||
});
|
||||
}
|
||||
|
||||
// Owner 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: layerState._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 = layerState._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 },
|
||||
);
|
||||
// Owner 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) {
|
||||
layerState._cardIds.delete(activeId);
|
||||
layerState._cardGraceState.delete(activeId);
|
||||
}
|
||||
const retention = applyEvictionGrace({
|
||||
selectedIds: decluttered,
|
||||
builtIds: [...layerState._cardIds],
|
||||
graceState: layerState._cardGraceState,
|
||||
nowMs: Date.now(),
|
||||
cardLimit: budgets.cardLimit,
|
||||
});
|
||||
layerState._cardIds = new Set(retention.keepIds);
|
||||
layerState._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(layerState._cardIds);
|
||||
if (layerState._hoverCardId) keepFrames.add(layerState._hoverCardId);
|
||||
if (layerState._activeCameraCardEnabled && layerState._activeCameraId)
|
||||
keepFrames.add(layerState._activeCameraId);
|
||||
const drops = planFrameCachePrune(
|
||||
[...layerState._cardFrameSlots].map(([id, slot]) => ({
|
||||
id,
|
||||
stamp: slot.stamp,
|
||||
})),
|
||||
keepFrames,
|
||||
);
|
||||
for (const id of drops) layerState._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 = layerState._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 layerState._cardIds)
|
||||
push(id, { pinned: id === layerState._hoverCardId });
|
||||
if (
|
||||
layerState._hoverCardId &&
|
||||
!layerState._cardIds.has(layerState._hoverCardId) &&
|
||||
layerState._hoverCardId !== layerState._activeCameraId
|
||||
) {
|
||||
push(layerState._hoverCardId, { pinned: true });
|
||||
}
|
||||
if (layerState._activeCameraCardEnabled && layerState._activeCameraId) {
|
||||
push(layerState._activeCameraId, { active: true });
|
||||
}
|
||||
layerState._cctvOverlayHost.setEntries(
|
||||
CCTV_OVERLAY_SOURCE_ID,
|
||||
entries,
|
||||
CCTV_OVERLAY_SOURCE_OPTIONS,
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* 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;
|
||||
layerState._cardFetchInFlightCount += 1;
|
||||
layerState._cardFetchPendingIds.add(cameraId);
|
||||
if (layerState._cardLastFetchAt > 0 && !userGesture) {
|
||||
const spacing = now - layerState._cardLastFetchAt;
|
||||
// NOTE: cold-fill bursts legitimately push this to ~250 ms — read it
|
||||
// together with the ambientCards.fetchMode telemetry.
|
||||
layerState._cardMinFetchSpacingMs =
|
||||
layerState._cardMinFetchSpacingMs == null
|
||||
? spacing
|
||||
: Math.min(layerState._cardMinFetchSpacingMs, spacing);
|
||||
}
|
||||
layerState._cardLastFetchAt = now;
|
||||
layerState._cardFetchCount += 1;
|
||||
|
||||
const image = new Image();
|
||||
layerState._cardFetchImages.add(image);
|
||||
const settle = (ok) => {
|
||||
image.onload = null;
|
||||
image.onerror = null;
|
||||
if (layerState._cardFetchImages.delete(image)) {
|
||||
layerState._cardFetchInFlightCount = Math.max(
|
||||
0,
|
||||
layerState._cardFetchInFlightCount - 1,
|
||||
);
|
||||
layerState._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()),
|
||||
);
|
||||
layerState._viewer?.scene?.requestRender?.();
|
||||
};
|
||||
image.onload = () => settle(true);
|
||||
image.onerror = () => settle(false);
|
||||
image.src = parts.frames.frameUrlFor(record.camera, refreshMs);
|
||||
}
|
||||
|
||||
/** Starts the card-frame pacer (idempotent; policy-gated per tick). */
|
||||
|
||||
function startCardFrameLoop() {
|
||||
if (layerState._cardFetchTimer) return;
|
||||
layerState._cardFetchTimer = setInterval(
|
||||
parts.model.cardFrameTick,
|
||||
CARD_FETCH_TICK_MS,
|
||||
);
|
||||
}
|
||||
|
||||
/** Stops the pacer and detaches all in-flight fetch handlers. */
|
||||
|
||||
function stopCardFrameLoop() {
|
||||
if (layerState._cardFetchTimer) {
|
||||
clearInterval(layerState._cardFetchTimer);
|
||||
layerState._cardFetchTimer = 0;
|
||||
}
|
||||
for (const image of layerState._cardFetchImages) {
|
||||
image.onload = null;
|
||||
image.onerror = null;
|
||||
image.removeAttribute('src');
|
||||
}
|
||||
layerState._cardFetchImages.clear();
|
||||
layerState._cardFetchPendingIds.clear();
|
||||
layerState._cardFetchInFlightCount = 0;
|
||||
layerState._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();
|
||||
layerState._cctvOverlayHost.clearSource(CCTV_OVERLAY_SOURCE_ID);
|
||||
layerState._cctvOverlayHost.setVisible(CCTV_OVERLAY_SOURCE_ID, false);
|
||||
parts.hover.clearHoverCard();
|
||||
layerState._cameraMoving = false;
|
||||
layerState._cardIds = new Set();
|
||||
layerState._cardGraceState = new Map();
|
||||
layerState._cardFrameSlots = new Map();
|
||||
layerState._cardFetchCount = 0;
|
||||
layerState._cardLastFetchAt = 0;
|
||||
layerState._cardMinFetchSpacingMs = null;
|
||||
}
|
||||
function handleVisibilityChange() {
|
||||
if (!document.hidden) return;
|
||||
for (const image of layerState._cardFetchImages) {
|
||||
image.onload = null;
|
||||
image.onerror = null;
|
||||
image.removeAttribute('src');
|
||||
}
|
||||
layerState._cardFetchImages.clear();
|
||||
layerState._cardFetchPendingIds.clear();
|
||||
layerState._cardFetchInFlightCount = 0;
|
||||
}
|
||||
return {
|
||||
handleVisibilityChange,
|
||||
setCctvCardPresentationOptions,
|
||||
ensureCardFrameSlot,
|
||||
refreshAmbientCards,
|
||||
pushAmbientCardEntries,
|
||||
fetchCardFrame,
|
||||
startCardFrameLoop,
|
||||
stopCardFrameLoop,
|
||||
teardownAmbientCards,
|
||||
};
|
||||
}
|
||||
Reference in new issue
Block a user