mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-20 18:22:25 +00:00
Zoomed out, the layer keeps one camera per ground cell and drew it as an ordinary icon, so nothing showed that dozens or hundreds of other cameras sat behind it. A cell with two or more cameras is now one round marker with the count inside, at the centre of its cameras. Single cameras and the active camera keep their icons. The count covers the whole cell, so it does not change while the cell crosses the screen edge. Markers that would overlap on screen merge into one carrying their sum. Counts above 999 use the compact form of the UI language and widen the marker into a pill. Clicking a marker zooms to its group and does not choose a camera. Ambient cards and coverage attach only to cameras drawn as icons; the camera picker keeps one representative per visible cell as before.
410 lines
15 KiB
JavaScript
410 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,
|
|
// Québec's browser-only sources have no registered frame endpoint;
|
|
// keep them out of still-card fill just like video feeds.
|
|
isVideo:
|
|
parts.model.isVideoFeedCamera(record.camera) ||
|
|
parts.model.isBrowserOverlayCamera(record.camera),
|
|
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 || (!active && record.viewGrouped)) 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,
|
|
};
|
|
}
|