mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
The camera layer's lifecycle, cards, geometry, hover and selection parts had left the Cesium allow-list but still drove the scene: Cesium camera move events, scene picks and pick objects, entity removal, the activation ray probe and the cards' canvas projection. The move events now come from the camera port and card render requests go through the frame port; the rest moves into the rendering part, which stays listed. The move listeners are attached and released in one place, with a test.
408 lines
15 KiB
JavaScript
408 lines
15 KiB
JavaScript
import { findFrame } from '../../render/rendererOf.js';
|
|
import {
|
|
createFrameSlot,
|
|
CCTV_OVERLAY_SOURCE_ID,
|
|
declutterCctvCards,
|
|
planFrameCachePrune,
|
|
createCctvThumbnailOverlayEntry,
|
|
CCTV_FRAME_CANVAS_W,
|
|
CCTV_FRAME_CANVAS_H,
|
|
applyFrameResult,
|
|
} from '../../data/cctvCards.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();
|
|
findFrame(layerState._viewer)?.requestRender('cctv-cards');
|
|
|
|
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;
|
|
}
|
|
// An eye with no geographic position (the earth's centre) measures from 0, 0.
|
|
const pose = parts.model.eyePose();
|
|
const viewerLat = pose ? pose.lat : 0;
|
|
const viewerLon = pose ? pose.lon : 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 view = parts.rendering.cardView();
|
|
const { width, height } = view;
|
|
const marginX = width * CARD_VIEW_MARGIN;
|
|
const marginY = height * CARD_VIEW_MARGIN;
|
|
|
|
const candidates = [];
|
|
const screenById = new Map();
|
|
// Cards go only on the icons the view pass shows (refreshHorizonCulling).
|
|
for (const record of layerState._viewRecords) {
|
|
const id = record.camera.id;
|
|
if (id === activeId || !record.position) continue;
|
|
let inView = false;
|
|
let sx = NaN;
|
|
let sy = NaN;
|
|
const screen = view.screenOf(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: pose?.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,
|
|
});
|
|
// Grace keeps a card briefly after it loses selection, but never on a
|
|
// camera whose icon the view pass has hidden.
|
|
const shownIds = new Set(
|
|
layerState._viewRecords.map((record) => record.camera.id),
|
|
);
|
|
layerState._cardIds = new Set(
|
|
retention.keepIds.filter((id) => shownIds.has(id)),
|
|
);
|
|
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()),
|
|
);
|
|
findFrame(layerState._viewer)?.requestRender('cctv-card-frame');
|
|
};
|
|
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._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,
|
|
};
|
|
}
|