From 3bda877a8a6adf20f43e9e314109875bba2a9f51 Mon Sep 17 00:00:00 2001 From: Byrd-IT <189950726+Byrd-IT@users.noreply.github.com> Date: Wed, 4 Nov 2026 03:34:37 -0600 Subject: [PATCH 01/14] perf(cctv): fetch the active camera's pictures only while they can be seen --- docs/CURRENT-STATE.md | 10 +++ src/layers/cctv/frames.js | 53 +++++++++++ src/layers/cctv/frames.test.mjs | 154 ++++++++++++++++++++++++++++++++ src/ui/cctvPanel.test.mjs | 57 ++++++++++++ src/ui/cctvPresentation.js | 12 ++- 5 files changed, 282 insertions(+), 4 deletions(-) diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 7292252ac1..3c217960c8 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1976,6 +1976,16 @@ The view pass reruns while the camera moves, paced by its own cost. The camera picker lists the cameras in view, active camera first, and closes with the count of cameras outside the view. +The active camera's pictures follow what can be seen. The monitor plane on the +globe stops fetching its still every 10 s while the sphere around the camera +mount and the plane is outside the view, or all of its points are below the +horizon (a 2D or Columbus scene always counts as visible), and fetches again +on the first refresh tick after it returns; activating or calibrating a camera +always fetches. The panel's still preview is requested only while the tab is +visible and the panel is expanded, and the panel asks for the current picture +when it is shown again. This matches the panel's live video, which already +played only in a visible tab and an expanded panel. + Traffic owns its rendered-surface observer only while enabled, removes it on disable/destroy, and rebuilds no cached heights on frames where the surface identity is unchanged. Its dots and heat-lines are two renderer draw sets, it animates on the frame port's preRender, and it follows the camera through the camera port at its own 5% threshold rather than the shared `percentageChanged` ledger. The surface identity is the globe port's `surfaceVersion()` and tile readiness its `isSettled('surface')`, so the layer no longer reaches Cesium. Heat-lines are always asked for draped: where the Cesium renderer cannot drape (no depth textures) its draw port draws them (and every other draped line) over the surface, in their colour where the surface hides them and hidden past the horizon, recolouring a line in place when only its colour changes, rather than the layer dropping them. Traffic and bikeshare expose factories through `./layers/traffic` and diff --git a/src/layers/cctv/frames.js b/src/layers/cctv/frames.js index 5049614923..ba0177f225 100644 --- a/src/layers/cctv/frames.js +++ b/src/layers/cctv/frames.js @@ -1,3 +1,4 @@ +import * as Cesium from 'cesium'; import { FRAME_SIGNATURE_W, FRAME_SIGNATURE_H, @@ -236,6 +237,53 @@ export function createFrames({ state: layerState, services, parts, source }) { ctx.fillText(status.slice(0, 58), 46, h - 42); } + /** + * Whether a camera's monitor plane can be on screen: the mount, the far cap + * and its corners are bounded by one sphere that is tested against the view + * frustum, and at least one of those points must be above the horizon. + * Anything this cannot judge (no viewer, a 2D or Columbus scene, no geometry + * yet) counts as visible, so a missing input never blocks a picture. + * @param {Object} record - Camera record. + * @returns {boolean} + */ + + function projectionInView(record) { + const viewer = layerState._viewer; + if (!viewer || viewer.isDestroyed?.()) return true; + const { camera, scene } = viewer; + if (!camera || !scene || scene.mode !== Cesium.SceneMode.SCENE3D) + return true; + const placed = record?.frustumPositions; + const points = [ + record?.billboard?.position, + placed?.mount, + placed?.capCenter, + placed?.tl, + placed?.tr, + placed?.br, + placed?.bl, + ].filter(Boolean); + if ( + !points.length || + typeof camera.frustum?.computeCullingVolume !== 'function' + ) + return true; + const occluder = new Cesium.EllipsoidalOccluder( + Cesium.Ellipsoid.WGS84, + camera.positionWC, + ); + if (!points.some((point) => occluder.isPointVisible(point))) return false; + const culling = camera.frustum.computeCullingVolume( + camera.positionWC, + camera.directionWC, + camera.upWC, + ); + return ( + culling.computeVisibility(Cesium.BoundingSphere.fromPoints(points)) !== + Cesium.Intersect.OUTSIDE + ); + } + /** * Triggers a new frame fetch for an image-mode projection if the refresh * interval has elapsed. Active cameras refresh more frequently than idle ones. @@ -269,6 +317,10 @@ export function createFrames({ state: layerState, services, parts, source }) { // bypass a provider's explicit minimum between image requests. if (sourceRefreshMs > 0 && sinceLastRefresh < sourceRefreshMs) return; if (!force && sinceLastRefresh < refreshMs) return; + // A plane nobody can see (panned away, far side of the globe) needs no new + // picture; the next tick after it comes back fetches one. A forced refresh + // (fresh activation, calibration) still runs. + if (!force && !projectionInView(record)) return; runtime.lastImageRefreshAt = now; const frameUrl = frameUrlFor(record.camera, refreshMs); @@ -402,6 +454,7 @@ export function createFrames({ state: layerState, services, parts, source }) { mediaUrlFor, paintProjectionPlaceholder, refreshProjectionImage, + projectionInView, paintPlaceholderThrottled, drawProjectionFrame, }; diff --git a/src/layers/cctv/frames.test.mjs b/src/layers/cctv/frames.test.mjs index 0d03e94576..3253074ba0 100644 --- a/src/layers/cctv/frames.test.mjs +++ b/src/layers/cctv/frames.test.mjs @@ -3,6 +3,7 @@ // 1920x1080 projection canvas, instead of being stretched to fill it. import { test } from 'node:test'; import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; import { createFrames, fitToProjection } from './frames.js'; import { FRAME_SIGNATURE_W, @@ -139,3 +140,156 @@ test('same pixels at a new aspect redraw at the new fit', () => { ]); assert.equal(runtime.canvasStamp, 2); }); + +// A camera's monitor plane is fetched only while it can be on screen. The +// viewer is a Cesium camera description over the real WGS84 globe: it hovers +// 30 km above a mount at (0, 0) and looks straight down, so the plane is in +// front of it; turned around, or moved to the far side of the globe, the +// plane is not. +const MOUNT = Cesium.Cartesian3.fromDegrees(0, 0, 20); +const point = (lon, lat, alt = 20) => + Cesium.Cartesian3.fromDegrees(lon, lat, alt); + +function planeRecord() { + const image = {}; + return { + camera: { id: 'plane' }, + billboard: { position: MOUNT }, + frustumPositions: { + mount: MOUNT, + capCenter: point(0.0005, 0, 20), + tl: point(0.0004, 0.0001), + tr: point(0.0006, 0.0001), + br: point(0.0006, -0.0001), + bl: point(0.0004, -0.0001), + }, + projection: { + mode: 'image', + image, + imageLoading: false, + imageReady: false, + lastImageRefreshAt: 0, + }, + }; +} + +function viewerAt(position, direction, up) { + return { + isDestroyed: () => false, + scene: { mode: Cesium.SceneMode.SCENE3D }, + camera: { + positionWC: position, + directionWC: direction, + upWC: up, + frustum: new Cesium.PerspectiveFrustum({ + fov: Cesium.Math.toRadians(60), + aspectRatio: 16 / 9, + near: 1, + far: 5e6, + }), + }, + }; +} + +// Above the mount, looking straight down at the ground. +function lookingDown() { + const position = point(0, 0, 30000); + return viewerAt( + position, + Cesium.Cartesian3.negate(Cesium.Cartesian3.UNIT_X, new Cesium.Cartesian3()), + Cesium.Cartesian3.UNIT_Z, + ); +} + +function framesFor(viewer) { + const state = { + _viewer: viewer, + _healthById: new Map(), + _activeCameraId: 'plane', + }; + return createFrames({ + state, + services: {}, + parts: { + model: { + safeNumber: (value, fallback) => + Number.isFinite(Number(value)) ? Number(value) : fallback, + }, + }, + source: { getFrameUrl: () => '/api/cctv/frame?id=plane' }, + }); +} + +test('a plane in front of the camera fetches its picture', () => { + const frames = framesFor(lookingDown()); + const record = planeRecord(); + assert.equal(frames.projectionInView(record), true); + frames.refreshProjectionImage(record); + assert.match( + record.projection.image.src, + /^\/api\/cctv\/frame\?id=plane&projTs=/, + ); + assert.equal(record.projection.imageLoading, true); +}); + +test('a plane behind the camera is not fetched, but a forced refresh is', () => { + const down = lookingDown(); + const away = viewerAt( + down.camera.positionWC, + Cesium.Cartesian3.UNIT_X, + Cesium.Cartesian3.UNIT_Z, + ); + const frames = framesFor(away); + const record = planeRecord(); + assert.equal(frames.projectionInView(record), false); + frames.refreshProjectionImage(record); + assert.equal(record.projection.image.src, undefined); + assert.equal(record.projection.lastImageRefreshAt, 0); + frames.refreshProjectionImage(record, true); + assert.match(record.projection.image.src, /projTs=/); +}); + +test('a plane below the horizon is not fetched', () => { + const far = point(180, 0, 30000); + const viewer = viewerAt( + far, + Cesium.Cartesian3.normalize( + Cesium.Cartesian3.subtract(MOUNT, far, new Cesium.Cartesian3()), + new Cesium.Cartesian3(), + ), + Cesium.Cartesian3.UNIT_Z, + ); + const frames = framesFor(viewer); + assert.equal(frames.projectionInView(planeRecord()), false); +}); + +test('a skipped refresh does not use up the interval: the plane fetches once it is back in view', () => { + const record = planeRecord(); + const frames = framesFor(lookingDown()); + const away = viewerAt( + lookingDown().camera.positionWC, + Cesium.Cartesian3.UNIT_X, + Cesium.Cartesian3.UNIT_Z, + ); + const awayFrames = framesFor(away); + awayFrames.refreshProjectionImage(record); + assert.equal(record.projection.image.src, undefined); + frames.refreshProjectionImage(record); + assert.match(record.projection.image.src, /projTs=/); +}); + +test('what cannot be judged counts as visible', () => { + const record = planeRecord(); + assert.equal(framesFor(null).projectionInView(record), true); + assert.equal( + framesFor({ ...lookingDown(), isDestroyed: () => true }).projectionInView( + record, + ), + true, + ); + const flat = lookingDown(); + flat.scene.mode = Cesium.SceneMode.SCENE2D; + assert.equal(framesFor(flat).projectionInView(record), true); + const noGeometry = { camera: { id: 'plane' }, projection: record.projection }; + assert.equal(framesFor(lookingDown()).projectionInView(noGeometry), true); +}); diff --git a/src/ui/cctvPanel.test.mjs b/src/ui/cctvPanel.test.mjs index bc9c83c9be..18d18152c3 100644 --- a/src/ui/cctvPanel.test.mjs +++ b/src/ui/cctvPanel.test.mjs @@ -388,6 +388,8 @@ test('the frame preview renders each step of a camera frame request', async (t) globalThis.Image = prior; }); const { controls, byId } = panel(t); + // The preview loads while the panel is open; the panel starts collapsed. + byId('cctv-panel').classList.remove('collapsed'); const frame = byId('cctv-frame'); const wrap = byId('cctv-frame-wrap'); const badge = byId('cctv-source-badge'); @@ -606,3 +608,58 @@ test('the meta line of a disabled layer does not describe its last camera', () = ); assert.match(presentCctvPanel(activeState, true).meta, /^Austin · HDG /); }); + +test('the still preview is fetched only while the tab and the panel are shown', async (t) => { + const prior = globalThis.Image; + const requests = []; + globalThis.Image = class { + constructor() { + requests.push(this); + } + }; + const hidden = Object.getOwnPropertyDescriptor(document, 'hidden'); + let tabHidden = false; + Object.defineProperty(document, 'hidden', { + configurable: true, + get: () => tabHidden, + }); + t.after(() => { + globalThis.Image = prior; + if (hidden) Object.defineProperty(document, 'hidden', hidden); + else delete document.hidden; + }); + const { controls, byId } = panel(t); + const panelElement = byId('cctv-panel'); + const state = (frameUrl) => ({ + enabled: true, + count: 1, + cameraIndex: [camera], + activeCameraId: 'a', + activeCamera: { ...camera, frameUrl, sourceKind: 'snapshot' }, + }); + + // Collapsed panel: nothing is requested, however often the state arrives. + assert.equal(panelElement.classList.contains('collapsed'), true); + controls._renderCctvState(state('a1.jpg')); + controls._renderCctvState(state('a2.jpg')); + assert.equal(requests.length, 0, 'collapsed panel'); + + // Opening it renders again (the real panel does so from a class observer) + // and asks for the current picture once. + panelElement.classList.remove('collapsed'); + controls._renderCctvState(state('a2.jpg')); + assert.equal(requests.length, 1, 'expanded panel'); + assert.equal(requests[0].src, 'a2.jpg'); + requests[0].onload(); + + // A background tab: refreshed URLs are not requested. + tabHidden = true; + controls._renderCctvState(state('a3.jpg')); + assert.equal(requests.length, 1, 'hidden tab'); + + // Back in the tab: the next render fetches the current URL. + tabHidden = false; + controls._renderCctvState(state('a3.jpg')); + assert.equal(requests.length, 2, 'visible tab'); + assert.equal(requests[1].src, 'a3.jpg'); +}); diff --git a/src/ui/cctvPresentation.js b/src/ui/cctvPresentation.js index 2f4cb8584e..8b2003d0f3 100644 --- a/src/ui/cctvPresentation.js +++ b/src/ui/cctvPresentation.js @@ -274,11 +274,14 @@ export function _renderCctvState(state) { const liveIntent = enabled && !!activeCamera?.isVideo && !activeCamera?.browserMediaUrl; this.store.setLive(liveIntent); + // A background tab or a collapsed panel shows nothing, so neither plays the + // video nor fetches the still; the observer and the visibilitychange listener + // render again when the panel is shown. + const panelShown = + !(typeof document !== 'undefined' && document.hidden) && + !this._cctvPanel?.classList?.contains('collapsed'); if (this._cctvVideo) { - const visible = - liveIntent && - !document.hidden && - !this._cctvPanel?.classList.contains('collapsed'); + const visible = liveIntent && panelShown; if (!visible || this._cctvVideoCameraId !== activeId) { this._cctvVideoSurface?.stop(); this._cctvVideoSurface = null; @@ -303,6 +306,7 @@ export function _renderCctvState(state) { // immediate so navigation never waits on the prior camera's request. if ( nextSrc && + panelShown && (cameraChanged || (!frameLoading && this._frame.currentSrc !== nextSrc)) ) { this._queueCctvFrame(nextSrc, nextCameraId, cameraChanged); From 0151c178a4b419545e7bce287b050e8da95f5a05 Mon Sep 17 00:00:00 2001 From: Byrd-IT <189950726+Byrd-IT@users.noreply.github.com> Date: Wed, 4 Nov 2026 05:01:37 -0600 Subject: [PATCH 02/14] docs: changelog fragment for #1543 --- changelog.d/1543-cctv-visible-only-fetch.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 changelog.d/1543-cctv-visible-only-fetch.md diff --git a/changelog.d/1543-cctv-visible-only-fetch.md b/changelog.d/1543-cctv-visible-only-fetch.md new file mode 100644 index 0000000000..4db3c8bc7b --- /dev/null +++ b/changelog.d/1543-cctv-visible-only-fetch.md @@ -0,0 +1,4 @@ +- Stop fetching the active CCTV camera's pictures when nobody can see them. The + monitor plane skips its 10 s still while it is off screen or below the + horizon, and the panel's still preview waits for a visible tab and an open + panel (Byrd-IT, #1543). From 9a3fc84935047dc393c1ec0f1e266041f017f40a Mon Sep 17 00:00:00 2001 From: Byrd-IT <189950726+Byrd-IT@users.noreply.github.com> Date: Thu, 5 Nov 2026 00:22:19 -0600 Subject: [PATCH 03/14] fix(cctv): address review of #1543 (horizon test, resume guard, no per-frame allocation, mobile sheet) - frames.test: viewerAt uses Cesium's default far (5e8) so the below-horizon test fails without occluder.isPointVisible - cctvControls: install the resume observer for a still-only panel too - cctvPresentation: panelShown also requires the Cameras sheet on phones; the observer watches body class/data-mobile-sheet - frames.projectionInView: shared horizonOccluder + scratch sphere/array --- changelog.d/1543-cctv-visible-only-fetch.md | 4 +- src/layers/cctv/frames.js | 23 ++++-- src/layers/cctv/frames.test.mjs | 4 +- src/ui/cctvControls.js | 11 ++- src/ui/cctvPanel.test.mjs | 84 ++++++++++++++++++--- src/ui/cctvPresentation.js | 9 ++- 6 files changed, 110 insertions(+), 25 deletions(-) diff --git a/changelog.d/1543-cctv-visible-only-fetch.md b/changelog.d/1543-cctv-visible-only-fetch.md index 4db3c8bc7b..80421a35c2 100644 --- a/changelog.d/1543-cctv-visible-only-fetch.md +++ b/changelog.d/1543-cctv-visible-only-fetch.md @@ -1,4 +1,4 @@ - Stop fetching the active CCTV camera's pictures when nobody can see them. The monitor plane skips its 10 s still while it is off screen or below the - horizon, and the panel's still preview waits for a visible tab and an open - panel (Byrd-IT, #1543). + horizon, and the panel's still preview waits for a visible tab, an open + panel and, on phones, the open Cameras sheet (Byrd-IT, #1543). diff --git a/src/layers/cctv/frames.js b/src/layers/cctv/frames.js index ba0177f225..8048b0e31a 100644 --- a/src/layers/cctv/frames.js +++ b/src/layers/cctv/frames.js @@ -1,4 +1,5 @@ import * as Cesium from 'cesium'; +import { horizonOccluder } from '../../data/iconOrientation.js'; import { FRAME_SIGNATURE_W, FRAME_SIGNATURE_H, @@ -42,6 +43,9 @@ export function fitToProjection(sourceW, sourceH) { }; } +const _scratchPoints = []; +const _scratchSphere = new Cesium.BoundingSphere(); + export function createFrames({ state: layerState, services, parts, source }) { /** * FNV-1a over the RGB channels of a downsampled frame. Pure (takes the raw @@ -254,7 +258,10 @@ export function createFrames({ state: layerState, services, parts, source }) { if (!camera || !scene || scene.mode !== Cesium.SceneMode.SCENE3D) return true; const placed = record?.frustumPositions; - const points = [ + // Reused buffers: this runs on every projection tick while out of view. + const points = _scratchPoints; + points.length = 0; + for (const point of [ record?.billboard?.position, placed?.mount, placed?.capCenter, @@ -262,16 +269,15 @@ export function createFrames({ state: layerState, services, parts, source }) { placed?.tr, placed?.br, placed?.bl, - ].filter(Boolean); + ]) { + if (point) points.push(point); + } if ( !points.length || typeof camera.frustum?.computeCullingVolume !== 'function' ) return true; - const occluder = new Cesium.EllipsoidalOccluder( - Cesium.Ellipsoid.WGS84, - camera.positionWC, - ); + const occluder = horizonOccluder(camera); if (!points.some((point) => occluder.isPointVisible(point))) return false; const culling = camera.frustum.computeCullingVolume( camera.positionWC, @@ -279,8 +285,9 @@ export function createFrames({ state: layerState, services, parts, source }) { camera.upWC, ); return ( - culling.computeVisibility(Cesium.BoundingSphere.fromPoints(points)) !== - Cesium.Intersect.OUTSIDE + culling.computeVisibility( + Cesium.BoundingSphere.fromPoints(points, _scratchSphere), + ) !== Cesium.Intersect.OUTSIDE ); } diff --git a/src/layers/cctv/frames.test.mjs b/src/layers/cctv/frames.test.mjs index 3253074ba0..7beea0c03a 100644 --- a/src/layers/cctv/frames.test.mjs +++ b/src/layers/cctv/frames.test.mjs @@ -185,7 +185,9 @@ function viewerAt(position, direction, up) { fov: Cesium.Math.toRadians(60), aspectRatio: 16 / 9, near: 1, - far: 5e6, + // Cesium's default far plane, as the app uses: a smaller one rejects + // the far-side mount before the horizon check is ever reached. + far: 5e8, }), }, }; diff --git a/src/ui/cctvControls.js b/src/ui/cctvControls.js index 1e227c92e2..2d5ad447a6 100644 --- a/src/ui/cctvControls.js +++ b/src/ui/cctvControls.js @@ -73,7 +73,10 @@ export class CctvControls { if (state) this._renderCctvState(state); if (this._cctvChip) this._publishCctvChip({}); }); - if (this._cctvVideo && typeof MutationObserver !== 'undefined') { + if ( + (this._cctvVideo || this._cctvFrame) && + typeof MutationObserver !== 'undefined' + ) { this._videoVisibilityObserver = new MutationObserver(() => this._renderCctvState(this._cctvState), ); @@ -82,6 +85,12 @@ export class CctvControls { attributes: true, attributeFilter: ['class', 'hidden'], }); + // On phones the panel is on screen only while the Cameras sheet is open. + if (typeof document !== 'undefined' && document.body) + this._videoVisibilityObserver.observe(document.body, { + attributes: true, + attributeFilter: ['class', 'data-mobile-sheet'], + }); this.listen(document, 'visibilitychange', () => this._renderCctvState(this._cctvState), ); diff --git a/src/ui/cctvPanel.test.mjs b/src/ui/cctvPanel.test.mjs index 18d18152c3..7612eacc3d 100644 --- a/src/ui/cctvPanel.test.mjs +++ b/src/ui/cctvPanel.test.mjs @@ -609,6 +609,15 @@ test('the meta line of a disabled layer does not describe its last camera', () = assert.match(presentCctvPanel(activeState, true).meta, /^Austin · HDG /); }); +const settle = () => new Promise((resolve) => setTimeout(resolve, 0)); +const stillState = (frameUrl) => ({ + enabled: true, + count: 1, + cameraIndex: [camera], + activeCameraId: 'a', + activeCamera: { ...camera, frameUrl, sourceKind: 'snapshot' }, +}); + test('the still preview is fetched only while the tab and the panel are shown', async (t) => { const prior = globalThis.Image; const requests = []; @@ -630,13 +639,7 @@ test('the still preview is fetched only while the tab and the panel are shown', }); const { controls, byId } = panel(t); const panelElement = byId('cctv-panel'); - const state = (frameUrl) => ({ - enabled: true, - count: 1, - cameraIndex: [camera], - activeCameraId: 'a', - activeCamera: { ...camera, frameUrl, sourceKind: 'snapshot' }, - }); + const state = stillState; // Collapsed panel: nothing is requested, however often the state arrives. assert.equal(panelElement.classList.contains('collapsed'), true); @@ -644,22 +647,79 @@ test('the still preview is fetched only while the tab and the panel are shown', controls._renderCctvState(state('a2.jpg')); assert.equal(requests.length, 0, 'collapsed panel'); - // Opening it renders again (the real panel does so from a class observer) - // and asks for the current picture once. + // Opening it resumes through the class observer, with no manual render. panelElement.classList.remove('collapsed'); - controls._renderCctvState(state('a2.jpg')); + await settle(); assert.equal(requests.length, 1, 'expanded panel'); assert.equal(requests[0].src, 'a2.jpg'); requests[0].onload(); // A background tab: refreshed URLs are not requested. tabHidden = true; + document.dispatchEvent(new Event('visibilitychange')); controls._renderCctvState(state('a3.jpg')); assert.equal(requests.length, 1, 'hidden tab'); - // Back in the tab: the next render fetches the current URL. + // Back in the tab: visibilitychange alone fetches the current URL. tabHidden = false; - controls._renderCctvState(state('a3.jpg')); + document.dispatchEvent(new Event('visibilitychange')); assert.equal(requests.length, 2, 'visible tab'); assert.equal(requests[1].src, 'a3.jpg'); }); + +test('the still preview waits for the Cameras sheet on phones', async (t) => { + const prior = globalThis.Image; + const requests = []; + globalThis.Image = class { + constructor() { + requests.push(this); + } + }; + t.after(() => { + globalThis.Image = prior; + document.body.classList.remove('mobile-shell'); + document.body.removeAttribute('data-mobile-sheet'); + }); + const { controls, byId } = panel(t); + byId('cctv-panel').classList.remove('collapsed'); + document.body.classList.add('mobile-shell'); + document.body.setAttribute('data-mobile-sheet', 'layers'); + controls._renderCctvState(stillState('a1.jpg')); + assert.equal(requests.length, 0, 'another sheet is open'); + + document.body.removeAttribute('data-mobile-sheet'); + controls._renderCctvState(stillState('a1.jpg')); + assert.equal(requests.length, 0, 'no sheet is open'); + + document.body.setAttribute('data-mobile-sheet', 'cameras'); + await settle(); + assert.equal(requests.length, 1, 'Cameras sheet opened'); + assert.equal(requests[0].src, 'a1.jpg'); + + // Off a phone the sheet attribute means nothing. + requests[0].onload(); + document.body.classList.remove('mobile-shell'); + document.body.setAttribute('data-mobile-sheet', 'layers'); + controls._renderCctvState(stillState('a2.jpg')); + assert.equal(requests.length, 2, 'desktop ignores the sheet'); +}); + +test('a still-only panel (no video element) resumes from the class change', async (t) => { + const prior = globalThis.Image; + const requests = []; + globalThis.Image = class { + constructor() { + requests.push(this); + } + }; + t.after(() => { + globalThis.Image = prior; + }); + const { controls, byId } = panel(t); + assert.equal(controls._cctvVideo, undefined); + controls._renderCctvState(stillState('a1.jpg')); + assert.equal(requests.length, 0); + byId('cctv-panel').classList.remove('collapsed'); + await settle(); + assert.equal(requests.length, 1); +}); diff --git a/src/ui/cctvPresentation.js b/src/ui/cctvPresentation.js index 8b2003d0f3..7e4b576f62 100644 --- a/src/ui/cctvPresentation.js +++ b/src/ui/cctvPresentation.js @@ -277,9 +277,16 @@ export function _renderCctvState(state) { // A background tab or a collapsed panel shows nothing, so neither plays the // video nor fetches the still; the observer and the visibilitychange listener // render again when the panel is shown. + // On phones the panel also belongs to one sheet: the shell hides it unless + // data-mobile-sheet is 'cameras'. + const body = typeof document !== 'undefined' ? document.body : null; + const sheetClosed = + !!body?.classList?.contains('mobile-shell') && + body.getAttribute('data-mobile-sheet') !== 'cameras'; const panelShown = !(typeof document !== 'undefined' && document.hidden) && - !this._cctvPanel?.classList?.contains('collapsed'); + !this._cctvPanel?.classList?.contains('collapsed') && + !sheetClosed; if (this._cctvVideo) { const visible = liveIntent && panelShown; if (!visible || this._cctvVideoCameraId !== activeId) { From b1b66e9717b4360a092a58e2565ab88ddc16a9d4 Mon Sep 17 00:00:00 2001 From: brandonabyrd Date: Mon, 9 Nov 2026 06:13:20 -0600 Subject: [PATCH 04/14] fix(cctv): keep below-ellipsoid planes refreshing --- src/layers/cctv/frames.js | 32 ++++++++++++++++++++++++--- src/layers/cctv/frames.test.mjs | 39 +++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+), 3 deletions(-) diff --git a/src/layers/cctv/frames.js b/src/layers/cctv/frames.js index 8048b0e31a..7040d242ed 100644 --- a/src/layers/cctv/frames.js +++ b/src/layers/cctv/frames.js @@ -45,6 +45,9 @@ export function fitToProjection(sourceW, sourceH) { const _scratchPoints = []; const _scratchSphere = new Cesium.BoundingSphere(); +const _scratchCartographic = new Cesium.Cartographic(); +// Close to the reference ellipsoid, it is not a reliable terrain horizon. +const LOW_VIEWER_HEIGHT_M = 1000; export function createFrames({ state: layerState, services, parts, source }) { /** @@ -244,7 +247,8 @@ export function createFrames({ state: layerState, services, parts, source }) { /** * Whether a camera's monitor plane can be on screen: the mount, the far cap * and its corners are bounded by one sphere that is tested against the view - * frustum, and at least one of those points must be above the horizon. + * frustum, and at least one of those points must be above the horizon when + * the reference ellipsoid is a reliable occluder for this view. * Anything this cannot judge (no viewer, a 2D or Columbus scene, no geometry * yet) counts as visible, so a missing input never blocks a picture. * @param {Object} record - Camera record. @@ -277,8 +281,30 @@ export function createFrames({ state: layerState, services, parts, source }) { typeof camera.frustum?.computeCullingVolume !== 'function' ) return true; - const occluder = horizonOccluder(camera); - if (!points.some((point) => occluder.isPointVisible(point))) return false; + // The reference ellipsoid can lie above the actual street. Near the + // surface its horizon would incorrectly hide nearby below-ellipsoid planes; + // let the frustum alone decide at low altitude or when height is unknown. + const height = Cesium.Cartographic.fromCartesian( + camera.positionWC, + Cesium.Ellipsoid.WGS84, + _scratchCartographic, + )?.height; + const pointsAboveEllipsoid = points.every((point) => { + const h = Cesium.Cartographic.fromCartesian( + point, + Cesium.Ellipsoid.WGS84, + _scratchCartographic, + )?.height; + return Number.isFinite(h) && h >= 0; + }); + if ( + Number.isFinite(height) && + height >= LOW_VIEWER_HEIGHT_M && + pointsAboveEllipsoid + ) { + const occluder = horizonOccluder(camera); + if (!points.some((point) => occluder.isPointVisible(point))) return false; + } const culling = camera.frustum.computeCullingVolume( camera.positionWC, camera.directionWC, diff --git a/src/layers/cctv/frames.test.mjs b/src/layers/cctv/frames.test.mjs index 7beea0c03a..c297311af4 100644 --- a/src/layers/cctv/frames.test.mjs +++ b/src/layers/cctv/frames.test.mjs @@ -251,6 +251,45 @@ test('a plane behind the camera is not fetched, but a forced refresh is', () => assert.match(record.projection.image.src, /projTs=/); }); +test('a nearby plane below the ellipsoid still fetches for a low viewer', () => { + const record = planeRecord(); + const mount = point(0, 0, -18); + const cap = point(0.00054, 0, -18); + const position = point(0.00135, 0, 4); + record.billboard.position = mount; + record.frustumPositions = { mount, capCenter: cap }; + const direction = Cesium.Cartesian3.normalize( + Cesium.Cartesian3.subtract(cap, position, new Cesium.Cartesian3()), + new Cesium.Cartesian3(), + ); + const viewer = viewerAt(position, direction, Cesium.Cartesian3.UNIT_Z); + const sphere = Cesium.BoundingSphere.fromPoints([mount, cap]); + const culling = viewer.camera.frustum.computeCullingVolume( + position, + direction, + viewer.camera.upWC, + ); + assert.notEqual(culling.computeVisibility(sphere), Cesium.Intersect.OUTSIDE); + const frames = framesFor(viewer); + assert.equal(frames.projectionInView(record), true); + frames.refreshProjectionImage(record); + assert.match(record.projection.image.src, /projTs=/); + + // An above-threshold viewer still needs a conservative result when the + // entire plane itself is below the reference ellipsoid. + const high = point(0.00135, 0, 1200); + const highDirection = Cesium.Cartesian3.normalize( + Cesium.Cartesian3.subtract(cap, high, new Cesium.Cartesian3()), + new Cesium.Cartesian3(), + ); + assert.equal( + framesFor( + viewerAt(high, highDirection, Cesium.Cartesian3.UNIT_Z), + ).projectionInView(record), + true, + ); +}); + test('a plane below the horizon is not fetched', () => { const far = point(180, 0, 30000); const viewer = viewerAt( From 564383e4b53f8944b183154b28430bb992ad637d Mon Sep 17 00:00:00 2001 From: brandonabyrd Date: Mon, 9 Nov 2026 06:35:22 -0600 Subject: [PATCH 05/14] fix(cctv): retain far-side culling below ellipsoid --- src/layers/cctv/frames.js | 42 +++++++++++---------------------- src/layers/cctv/frames.test.mjs | 38 +++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+), 28 deletions(-) diff --git a/src/layers/cctv/frames.js b/src/layers/cctv/frames.js index 7040d242ed..95ef0a9794 100644 --- a/src/layers/cctv/frames.js +++ b/src/layers/cctv/frames.js @@ -1,5 +1,4 @@ import * as Cesium from 'cesium'; -import { horizonOccluder } from '../../data/iconOrientation.js'; import { FRAME_SIGNATURE_W, FRAME_SIGNATURE_H, @@ -45,9 +44,15 @@ export function fitToProjection(sourceW, sourceH) { const _scratchPoints = []; const _scratchSphere = new Cesium.BoundingSphere(); -const _scratchCartographic = new Cesium.Cartographic(); -// Close to the reference ellipsoid, it is not a reliable terrain horizon. -const LOW_VIEWER_HEIGHT_M = 1000; +// Keep the occluding surface below common negative geoid undulations. +const HORIZON_MARGIN_M = 200; +const _radii = Cesium.Ellipsoid.WGS84.radii; +const _horizonEllipsoid = new Cesium.Ellipsoid( + _radii.x - HORIZON_MARGIN_M, + _radii.y - HORIZON_MARGIN_M, + _radii.z - HORIZON_MARGIN_M, +); +const _horizonOccluder = new Cesium.EllipsoidalOccluder(_horizonEllipsoid); export function createFrames({ state: layerState, services, parts, source }) { /** @@ -281,30 +286,11 @@ export function createFrames({ state: layerState, services, parts, source }) { typeof camera.frustum?.computeCullingVolume !== 'function' ) return true; - // The reference ellipsoid can lie above the actual street. Near the - // surface its horizon would incorrectly hide nearby below-ellipsoid planes; - // let the frustum alone decide at low altitude or when height is unknown. - const height = Cesium.Cartographic.fromCartesian( - camera.positionWC, - Cesium.Ellipsoid.WGS84, - _scratchCartographic, - )?.height; - const pointsAboveEllipsoid = points.every((point) => { - const h = Cesium.Cartographic.fromCartesian( - point, - Cesium.Ellipsoid.WGS84, - _scratchCartographic, - )?.height; - return Number.isFinite(h) && h >= 0; - }); - if ( - Number.isFinite(height) && - height >= LOW_VIEWER_HEIGHT_M && - pointsAboveEllipsoid - ) { - const occluder = horizonOccluder(camera); - if (!points.some((point) => occluder.isPointVisible(point))) return false; - } + // WGS84 can be above the actual street; cull against a surface below it + // instead, while retaining far-side occlusion for low and high viewers. + _horizonOccluder.cameraPosition = camera.positionWC; + if (!points.some((point) => _horizonOccluder.isPointVisible(point))) + return false; const culling = camera.frustum.computeCullingVolume( camera.positionWC, camera.directionWC, diff --git a/src/layers/cctv/frames.test.mjs b/src/layers/cctv/frames.test.mjs index c297311af4..d12bd401fb 100644 --- a/src/layers/cctv/frames.test.mjs +++ b/src/layers/cctv/frames.test.mjs @@ -290,6 +290,44 @@ test('a nearby plane below the ellipsoid still fetches for a low viewer', () => ); }); +test('the horizon still rejects a negative-height plane on the far side', () => { + for (const altitude of [4, 30000, 2e7]) { + const record = planeRecord(); + const mount = point(0, 0, -18); + const cap = point(0.00054, 0, -18); + record.billboard.position = mount; + record.frustumPositions = { mount, capCenter: cap }; + const position = point(180, 0, altitude); + const direction = Cesium.Cartesian3.normalize( + Cesium.Cartesian3.subtract(mount, position, new Cesium.Cartesian3()), + new Cesium.Cartesian3(), + ); + const viewer = viewerAt(position, direction, Cesium.Cartesian3.UNIT_Z); + const sphere = Cesium.BoundingSphere.fromPoints([mount, cap]); + assert.notEqual( + viewer.camera.frustum + .computeCullingVolume(position, direction, viewer.camera.upWC) + .computeVisibility(sphere), + Cesium.Intersect.OUTSIDE, + ); + assert.equal(framesFor(viewer).projectionInView(record), false); + } +}); + +test('a low viewer can see a plane beyond the WGS84 horizon', () => { + const record = planeRecord(); + const mount = point(0, 0, 1); + record.billboard.position = mount; + record.frustumPositions = { mount }; + const position = point(0.2, 0, 4); + const direction = Cesium.Cartesian3.normalize( + Cesium.Cartesian3.subtract(mount, position, new Cesium.Cartesian3()), + new Cesium.Cartesian3(), + ); + const viewer = viewerAt(position, direction, Cesium.Cartesian3.UNIT_Z); + assert.equal(framesFor(viewer).projectionInView(record), true); +}); + test('a plane below the horizon is not fetched', () => { const far = point(180, 0, 30000); const viewer = viewerAt( From 58872358944341618b048607fae8ea16d02be75a Mon Sep 17 00:00:00 2001 From: brandonabyrd Date: Mon, 9 Nov 2026 06:35:39 -0600 Subject: [PATCH 06/14] docs(cctv): describe conservative horizon geometry --- src/layers/cctv/frames.js | 4 ++-- src/layers/cctv/frames.test.mjs | 3 +-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/src/layers/cctv/frames.js b/src/layers/cctv/frames.js index 95ef0a9794..aab35fcec6 100644 --- a/src/layers/cctv/frames.js +++ b/src/layers/cctv/frames.js @@ -252,8 +252,8 @@ export function createFrames({ state: layerState, services, parts, source }) { /** * Whether a camera's monitor plane can be on screen: the mount, the far cap * and its corners are bounded by one sphere that is tested against the view - * frustum, and at least one of those points must be above the horizon when - * the reference ellipsoid is a reliable occluder for this view. + * frustum, and at least one of those points must be above a conservative + * horizon computed from a shrunken reference ellipsoid. * Anything this cannot judge (no viewer, a 2D or Columbus scene, no geometry * yet) counts as visible, so a missing input never blocks a picture. * @param {Object} record - Camera record. diff --git a/src/layers/cctv/frames.test.mjs b/src/layers/cctv/frames.test.mjs index d12bd401fb..b21fea1cbc 100644 --- a/src/layers/cctv/frames.test.mjs +++ b/src/layers/cctv/frames.test.mjs @@ -275,8 +275,7 @@ test('a nearby plane below the ellipsoid still fetches for a low viewer', () => frames.refreshProjectionImage(record); assert.match(record.projection.image.src, /projTs=/); - // An above-threshold viewer still needs a conservative result when the - // entire plane itself is below the reference ellipsoid. + // The same below-ellipsoid plane remains visible from a higher viewer. const high = point(0.00135, 0, 1200); const highDirection = Cesium.Cartesian3.normalize( Cesium.Cartesian3.subtract(cap, high, new Cesium.Cartesian3()), From 147d1f5e4ef8b8048b73f73fb67416faa98fcb94 Mon Sep 17 00:00:00 2001 From: Byrd-IT <189950726+Byrd-IT@users.noreply.github.com> Date: Wed, 11 Nov 2026 09:52:15 -0600 Subject: [PATCH 07/14] docs: CURRENT-STATE describes the 200 m horizon margin and the phone Cameras sheet rule (#1543) --- docs/CURRENT-STATE.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 3c217960c8..7cab5e0d5b 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1979,12 +1979,13 @@ count of cameras outside the view. The active camera's pictures follow what can be seen. The monitor plane on the globe stops fetching its still every 10 s while the sphere around the camera mount and the plane is outside the view, or all of its points are below the -horizon (a 2D or Columbus scene always counts as visible), and fetches again -on the first refresh tick after it returns; activating or calibrating a camera -always fetches. The panel's still preview is requested only while the tab is -visible and the panel is expanded, and the panel asks for the current picture -when it is shown again. This matches the panel's live video, which already -played only in a visible tab and an expanded panel. +horizon of the WGS84 ellipsoid shrunk by 200 m (a 2D or Columbus scene always +counts as visible), and fetches again on the first refresh tick after it +returns; activating or calibrating a camera always fetches. The panel's still +preview is requested only while the tab is visible and the panel is expanded +(on phones, also while the Cameras sheet is open), and the panel asks for the +current picture when it is shown again. The panel's live video follows the same +rule. Traffic owns its rendered-surface observer only while enabled, removes it on disable/destroy, and rebuilds no cached heights on frames where the surface identity is unchanged. Its dots and heat-lines are two renderer draw sets, it animates on the frame port's preRender, and it follows the camera through the camera port at its own 5% threshold rather than the shared `percentageChanged` ledger. The surface identity is the globe port's `surfaceVersion()` and tile readiness its `isSettled('surface')`, so the layer no longer reaches Cesium. Heat-lines are always asked for draped: where the Cesium renderer cannot drape (no depth textures) its draw port draws them (and every other draped line) over the surface, in their colour where the surface hides them and hidden past the horizon, recolouring a line in place when only its colour changes, rather than the layer dropping them. From c0752784d239c9fa5294075b14a477cb9b9066b7 Mon Sep 17 00:00:00 2001 From: brandonabyrd Date: Wed, 18 Nov 2026 15:19:38 -0600 Subject: [PATCH 08/14] fix(cctv): cull frames through renderer camera port --- scripts/package-boundaries.json | 1 + src/layers/cctv/frames.js | 76 +++++++++++++------------ src/layers/cctv/frames.test.mjs | 80 ++++++++++++++++++++++++++- src/render/cesium/camera.js | 3 + src/render/cesium/cameraPort.test.mjs | 17 ++++++ src/render/contract/camera.d.ts | 2 + 6 files changed, 143 insertions(+), 36 deletions(-) diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index a09757f481..269b433f33 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -3382,6 +3382,7 @@ "src/layers/cctv/rendering.js", "src/render/motion/iconBook.js", "src/geo/frustum.js", + "src/geo/sphere.js", "src/render/cesium/iconOrientation.js", "src/render/cesium/iconSetPrimitive.js", "src/data/iconSet.js", diff --git a/src/layers/cctv/frames.js b/src/layers/cctv/frames.js index aab35fcec6..d1b70d5e80 100644 --- a/src/layers/cctv/frames.js +++ b/src/layers/cctv/frames.js @@ -1,4 +1,8 @@ -import * as Cesium from 'cesium'; +import { findCamera } from '../../render/rendererOf.js'; +import { offsetEllipsoid } from '../../geo/ellipsoid.js'; +import { horizonFrom } from '../../geo/horizon.js'; +import { frustumPlanes, sphereOutside } from '../../geo/frustum.js'; +import { sphereFromPoints } from '../../geo/sphere.js'; import { FRAME_SIGNATURE_W, FRAME_SIGNATURE_H, @@ -42,17 +46,9 @@ export function fitToProjection(sourceW, sourceH) { }; } -const _scratchPoints = []; -const _scratchSphere = new Cesium.BoundingSphere(); // Keep the occluding surface below common negative geoid undulations. const HORIZON_MARGIN_M = 200; -const _radii = Cesium.Ellipsoid.WGS84.radii; -const _horizonEllipsoid = new Cesium.Ellipsoid( - _radii.x - HORIZON_MARGIN_M, - _radii.y - HORIZON_MARGIN_M, - _radii.z - HORIZON_MARGIN_M, -); -const _horizonOccluder = new Cesium.EllipsoidalOccluder(_horizonEllipsoid); +const _horizonEllipsoid = offsetEllipsoid(-HORIZON_MARGIN_M); export function createFrames({ state: layerState, services, parts, source }) { /** @@ -263,44 +259,54 @@ export function createFrames({ state: layerState, services, parts, source }) { function projectionInView(record) { const viewer = layerState._viewer; if (!viewer || viewer.isDestroyed?.()) return true; - const { camera, scene } = viewer; - if (!camera || !scene || scene.mode !== Cesium.SceneMode.SCENE3D) + const camera = findCamera(viewer); + if (camera?.isWorld3D?.() !== true) return true; + const pose = camera.pose?.(); + const projection = camera.matrices?.()?.projection; + const finiteVector = (v) => v && [v.x, v.y, v.z].every(Number.isFinite); + // A centred perspective is the only shape frustumPlanes can judge exactly. + if ( + !finiteVector(pose?.position) || + !finiteVector(pose.direction) || + !finiteVector(pose.up) || + !(pose.fovy > 0 && pose.fovy < Math.PI) || + !(pose.aspectRatio > 0) || + !(pose.near > 0 && pose.far > pose.near) || + !projection || + projection[8] !== 0 || + projection[9] !== 0 || + projection[15] !== 0 + ) return true; const placed = record?.frustumPositions; - // Reused buffers: this runs on every projection tick while out of view. - const points = _scratchPoints; - points.length = 0; - for (const point of [ - record?.billboard?.position, + const points = [ + record?.position, placed?.mount, placed?.capCenter, placed?.tl, placed?.tr, placed?.br, placed?.bl, - ]) { - if (point) points.push(point); - } + ].filter(Boolean); if ( !points.length || - typeof camera.frustum?.computeCullingVolume !== 'function' + points.some( + (p) => + !Number.isFinite(p.x) || + !Number.isFinite(p.y) || + !Number.isFinite(p.z), + ) ) return true; - // WGS84 can be above the actual street; cull against a surface below it - // instead, while retaining far-side occlusion for low and high viewers. - _horizonOccluder.cameraPosition = camera.positionWC; - if (!points.some((point) => _horizonOccluder.isPointVisible(point))) + const o = _horizonEllipsoid.oneOverRadii; + const eye = pose.position; + // Below the shrunken ellipsoid the occluder can hide nearby visible points. + const outside = Math.hypot(eye.x * o.x, eye.y * o.y, eye.z * o.z) >= 1; + const horizon = outside ? horizonFrom(eye, _horizonEllipsoid) : null; + if (horizon && !points.some((point) => horizon.isPointVisible(point))) return false; - const culling = camera.frustum.computeCullingVolume( - camera.positionWC, - camera.directionWC, - camera.upWC, - ); - return ( - culling.computeVisibility( - Cesium.BoundingSphere.fromPoints(points, _scratchSphere), - ) !== Cesium.Intersect.OUTSIDE - ); + const sphere = sphereFromPoints(points); + return !sphereOutside(frustumPlanes(pose), sphere.center, sphere.radius); } /** diff --git a/src/layers/cctv/frames.test.mjs b/src/layers/cctv/frames.test.mjs index b21fea1cbc..dc1958cc20 100644 --- a/src/layers/cctv/frames.test.mjs +++ b/src/layers/cctv/frames.test.mjs @@ -4,6 +4,7 @@ import { test } from 'node:test'; import assert from 'node:assert/strict'; import * as Cesium from 'cesium'; +import { bindRenderer } from '../../render/rendererOf.js'; import { createFrames, fitToProjection } from './frames.js'; import { FRAME_SIGNATURE_W, @@ -174,7 +175,7 @@ function planeRecord() { } function viewerAt(position, direction, up) { - return { + const viewer = { isDestroyed: () => false, scene: { mode: Cesium.SceneMode.SCENE3D }, camera: { @@ -191,6 +192,22 @@ function viewerAt(position, direction, up) { }), }, }; + bindRenderer(viewer, { + camera: { + isWorld3D: () => viewer.scene.mode === Cesium.SceneMode.SCENE3D, + pose: () => ({ + position: viewer.camera.positionWC, + direction: viewer.camera.directionWC, + up: viewer.camera.upWC, + fovy: viewer.camera.frustum.fovy, + aspectRatio: viewer.camera.frustum.aspectRatio, + near: viewer.camera.frustum.near, + far: viewer.camera.frustum.far, + }), + matrices: () => ({ projection: viewer.camera.frustum.projectionMatrix }), + }, + }); + return viewer; } // Above the mount, looking straight down at the ground. @@ -356,6 +373,67 @@ test('a skipped refresh does not use up the interval: the plane fetches once it assert.match(record.projection.image.src, /projTs=/); }); +test('the renderer scene host culls the far side without raw viewer access', () => { + const native = lookingDown(); + const viewer = { isDestroyed: () => false }; + const camera = native.camera; + const unbind = bindRenderer(viewer, { + camera: { + isWorld3D: () => true, + matrices: () => ({ projection: camera.frustum.projectionMatrix }), + pose: () => ({ + position: camera.positionWC, + direction: Cesium.Cartesian3.UNIT_X, + up: camera.upWC, + fovy: camera.frustum.fovy, + aspectRatio: camera.frustum.aspectRatio, + near: camera.frustum.near, + far: camera.frustum.far, + }), + }, + }); + try { + assert.equal(framesFor(viewer).projectionInView(planeRecord()), false); + } finally { + unbind(); + } +}); + +test('deep viewers do not lose nearby planes to the horizon test', () => { + const mount = point(0, 0, -350); + const position = point(0.00135, 0, -300); + const direction = Cesium.Cartesian3.normalize( + Cesium.Cartesian3.subtract(mount, position, new Cesium.Cartesian3()), + new Cesium.Cartesian3(), + ); + const record = planeRecord(); + record.frustumPositions = { mount }; + record.position = mount; + assert.equal( + framesFor( + viewerAt(position, direction, Cesium.Cartesian3.UNIT_Z), + ).projectionInView(record), + true, + ); +}); + +test('flat, unknown, and off-centre projections fail open', () => { + const native = lookingDown(); + native.camera.directionWC = Cesium.Cartesian3.UNIT_X; + native.scene.mode = Cesium.SceneMode.COLUMBUS_VIEW; + assert.equal(framesFor(native).projectionInView(planeRecord()), true); + native.scene.mode = Cesium.SceneMode.SCENE3D; + native.camera.frustum.xOffset = 0.1; + assert.equal(framesFor(native).projectionInView(planeRecord()), true); + const host = {}; + const unbind = bindRenderer(host, { camera: { pose: () => ({}) } }); + try { + assert.equal(framesFor(host).projectionInView(planeRecord()), true); + } finally { + unbind(); + } +}); + test('what cannot be judged counts as visible', () => { const record = planeRecord(); assert.equal(framesFor(null).projectionInView(record), true); diff --git a/src/render/cesium/camera.js b/src/render/cesium/camera.js index 34fab328e3..46257ff344 100644 --- a/src/render/cesium/camera.js +++ b/src/render/cesium/camera.js @@ -350,6 +350,9 @@ export function createCesiumCamera({ } const cameraPort = { + // The ECEF camera pose describes the globe only in 3D. Consumers that + // cannot prove this must avoid globe-only visibility culling. + isWorld3D: () => scene.mode === Cesium.SceneMode.SCENE3D, on: (event, cb, options) => cameraEvents.on(event, cb, options), onCommand: (cb) => commandHooks.on(cb), setView(spec) { diff --git a/src/render/cesium/cameraPort.test.mjs b/src/render/cesium/cameraPort.test.mjs index 967ff1f761..92922b71ec 100644 --- a/src/render/cesium/cameraPort.test.mjs +++ b/src/render/cesium/cameraPort.test.mjs @@ -337,6 +337,23 @@ test('the camera port gives the clock its own tick back as it goes', () => { } }); +test('camera reports globe mode and fails closed for other modes', () => { + const { scene, camera } = headlessCamera(); + scene.postUpdate = new Cesium.Event(); + scene.requestRender = () => {}; + const { port } = createCesiumCamera({ scene, camera, report: () => {} }); + for (const [mode, expected] of [ + [Cesium.SceneMode.SCENE3D, true], + [Cesium.SceneMode.SCENE2D, false], + [Cesium.SceneMode.COLUMBUS_VIEW, false], + [Cesium.SceneMode.MORPHING, false], + [undefined, false], + ]) { + scene.mode = mode; + assert.equal(port.isWorld3D(), expected); + } +}); + test('setFov holds the vertical angle across resizes, and waits for a first one', () => { const { scene, camera } = headlessCamera(); scene.postUpdate = new Cesium.Event(); diff --git a/src/render/contract/camera.d.ts b/src/render/contract/camera.d.ts index a9b1f7d5ae..82023db6ff 100644 --- a/src/render/contract/camera.d.ts +++ b/src/render/contract/camera.d.ts @@ -234,6 +234,8 @@ export type CameraEvent = 'changed' | 'moveStart' | 'moveEnd' | 'followChanged' | 'flightEnd'; export interface CameraPort { + /** True only when its pose is an ECEF view of the 3D globe. Missing means unknown. */ + isWorld3D?(): boolean; pose(): CameraPose; /** * Place the eye. A position with a `{direction, up}` orientation is placed From b98b9d390f88d8831390f2211b5279b88cf08ccb Mon Sep 17 00:00:00 2001 From: brandonabyrd Date: Wed, 18 Nov 2026 15:31:59 -0600 Subject: [PATCH 09/14] fix(cctv): reuse renderer visibility scratch state --- scripts/package-boundaries.json | 1 - src/layers/cctv/frames.js | 66 ++++---------------- src/layers/cctv/frames.test.mjs | 54 +++++++++-------- src/render/cesium/camera.js | 87 ++++++++++++++++++++++++++- src/render/cesium/cameraPort.test.mjs | 18 +++--- src/render/contract/camera.d.ts | 4 +- 6 files changed, 137 insertions(+), 93 deletions(-) diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 269b433f33..a09757f481 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -3382,7 +3382,6 @@ "src/layers/cctv/rendering.js", "src/render/motion/iconBook.js", "src/geo/frustum.js", - "src/geo/sphere.js", "src/render/cesium/iconOrientation.js", "src/render/cesium/iconSetPrimitive.js", "src/data/iconSet.js", diff --git a/src/layers/cctv/frames.js b/src/layers/cctv/frames.js index d1b70d5e80..d92afd79ec 100644 --- a/src/layers/cctv/frames.js +++ b/src/layers/cctv/frames.js @@ -1,8 +1,4 @@ import { findCamera } from '../../render/rendererOf.js'; -import { offsetEllipsoid } from '../../geo/ellipsoid.js'; -import { horizonFrom } from '../../geo/horizon.js'; -import { frustumPlanes, sphereOutside } from '../../geo/frustum.js'; -import { sphereFromPoints } from '../../geo/sphere.js'; import { FRAME_SIGNATURE_W, FRAME_SIGNATURE_H, @@ -46,9 +42,7 @@ export function fitToProjection(sourceW, sourceH) { }; } -// Keep the occluding surface below common negative geoid undulations. -const HORIZON_MARGIN_M = 200; -const _horizonEllipsoid = offsetEllipsoid(-HORIZON_MARGIN_M); +const _scratchPoints = []; export function createFrames({ state: layerState, services, parts, source }) { /** @@ -260,53 +254,19 @@ export function createFrames({ state: layerState, services, parts, source }) { const viewer = layerState._viewer; if (!viewer || viewer.isDestroyed?.()) return true; const camera = findCamera(viewer); - if (camera?.isWorld3D?.() !== true) return true; - const pose = camera.pose?.(); - const projection = camera.matrices?.()?.projection; - const finiteVector = (v) => v && [v.x, v.y, v.z].every(Number.isFinite); - // A centred perspective is the only shape frustumPlanes can judge exactly. - if ( - !finiteVector(pose?.position) || - !finiteVector(pose.direction) || - !finiteVector(pose.up) || - !(pose.fovy > 0 && pose.fovy < Math.PI) || - !(pose.aspectRatio > 0) || - !(pose.near > 0 && pose.far > pose.near) || - !projection || - projection[8] !== 0 || - projection[9] !== 0 || - projection[15] !== 0 - ) - return true; + if (typeof camera?.visiblePoints !== 'function') return true; const placed = record?.frustumPositions; - const points = [ - record?.position, - placed?.mount, - placed?.capCenter, - placed?.tl, - placed?.tr, - placed?.br, - placed?.bl, - ].filter(Boolean); - if ( - !points.length || - points.some( - (p) => - !Number.isFinite(p.x) || - !Number.isFinite(p.y) || - !Number.isFinite(p.z), - ) - ) - return true; - const o = _horizonEllipsoid.oneOverRadii; - const eye = pose.position; - // Below the shrunken ellipsoid the occluder can hide nearby visible points. - const outside = Math.hypot(eye.x * o.x, eye.y * o.y, eye.z * o.z) >= 1; - const horizon = outside ? horizonFrom(eye, _horizonEllipsoid) : null; - if (horizon && !points.some((point) => horizon.isPointVisible(point))) - return false; - const sphere = sphereFromPoints(points); - return !sphereOutside(frustumPlanes(pose), sphere.center, sphere.radius); + const points = _scratchPoints; + points.length = 0; + if (record?.position) points.push(record.position); + if (placed?.mount) points.push(placed.mount); + if (placed?.capCenter) points.push(placed.capCenter); + if (placed?.tl) points.push(placed.tl); + if (placed?.tr) points.push(placed.tr); + if (placed?.br) points.push(placed.br); + if (placed?.bl) points.push(placed.bl); + // Unknown modes or unsupported cameras must not suppress pictures. + return camera.visiblePoints(points, 200) !== false; } /** diff --git a/src/layers/cctv/frames.test.mjs b/src/layers/cctv/frames.test.mjs index dc1958cc20..2aca236a5e 100644 --- a/src/layers/cctv/frames.test.mjs +++ b/src/layers/cctv/frames.test.mjs @@ -5,6 +5,7 @@ import { test } from 'node:test'; import assert from 'node:assert/strict'; import * as Cesium from 'cesium'; import { bindRenderer } from '../../render/rendererOf.js'; +import { createPointsVisibility } from '../../render/cesium/camera.js'; import { createFrames, fitToProjection } from './frames.js'; import { FRAME_SIGNATURE_W, @@ -194,17 +195,7 @@ function viewerAt(position, direction, up) { }; bindRenderer(viewer, { camera: { - isWorld3D: () => viewer.scene.mode === Cesium.SceneMode.SCENE3D, - pose: () => ({ - position: viewer.camera.positionWC, - direction: viewer.camera.directionWC, - up: viewer.camera.upWC, - fovy: viewer.camera.frustum.fovy, - aspectRatio: viewer.camera.frustum.aspectRatio, - near: viewer.camera.frustum.near, - far: viewer.camera.frustum.far, - }), - matrices: () => ({ projection: viewer.camera.frustum.projectionMatrix }), + visiblePoints: createPointsVisibility(viewer.scene, viewer.camera), }, }); return viewer; @@ -377,20 +368,9 @@ test('the renderer scene host culls the far side without raw viewer access', () const native = lookingDown(); const viewer = { isDestroyed: () => false }; const camera = native.camera; + camera.directionWC = Cesium.Cartesian3.UNIT_X; const unbind = bindRenderer(viewer, { - camera: { - isWorld3D: () => true, - matrices: () => ({ projection: camera.frustum.projectionMatrix }), - pose: () => ({ - position: camera.positionWC, - direction: Cesium.Cartesian3.UNIT_X, - up: camera.upWC, - fovy: camera.frustum.fovy, - aspectRatio: camera.frustum.aspectRatio, - near: camera.frustum.near, - far: camera.frustum.far, - }), - }, + camera: { visiblePoints: createPointsVisibility(native.scene, camera) }, }); try { assert.equal(framesFor(viewer).projectionInView(planeRecord()), false); @@ -399,6 +379,28 @@ test('the renderer scene host culls the far side without raw viewer access', () } }); +test('visibility checks reuse the points array across ticks', () => { + const seen = []; + const host = {}; + const unbind = bindRenderer(host, { + camera: { + visiblePoints: (points) => { + seen.push(points); + return true; + }, + }, + }); + try { + const frames = framesFor(host); + frames.projectionInView(planeRecord()); + frames.projectionInView(planeRecord()); + assert.equal(seen.length, 2); + assert.strictEqual(seen[0], seen[1]); + } finally { + unbind(); + } +}); + test('deep viewers do not lose nearby planes to the horizon test', () => { const mount = point(0, 0, -350); const position = point(0.00135, 0, -300); @@ -417,13 +419,13 @@ test('deep viewers do not lose nearby planes to the horizon test', () => { ); }); -test('flat, unknown, and off-centre projections fail open', () => { +test('flat and unknown projections fail open', () => { const native = lookingDown(); native.camera.directionWC = Cesium.Cartesian3.UNIT_X; native.scene.mode = Cesium.SceneMode.COLUMBUS_VIEW; assert.equal(framesFor(native).projectionInView(planeRecord()), true); native.scene.mode = Cesium.SceneMode.SCENE3D; - native.camera.frustum.xOffset = 0.1; + native.camera.directionWC = undefined; assert.equal(framesFor(native).projectionInView(planeRecord()), true); const host = {}; const unbind = bindRenderer(host, { camera: { pose: () => ({}) } }); diff --git a/src/render/cesium/camera.js b/src/render/cesium/camera.js index 46257ff344..e589de38d6 100644 --- a/src/render/cesium/camera.js +++ b/src/render/cesium/camera.js @@ -86,6 +86,89 @@ function sameMatrix(array, matrix) { return true; } +/** Conservative globe/frustum visibility; null means unknown. */ +export function createPointsVisibility(scene, camera) { + const visibilitySphere = new Cesium.BoundingSphere(); + let visibilityMargin = null; + let visibilityEllipsoid = null; + let visibilityOccluder = null; + return function visiblePoints(points, marginM) { + if ( + scene.mode !== Cesium.SceneMode.SCENE3D || + !points?.length || + !Number.isFinite(marginM) || + marginM < 0 || + typeof camera.frustum?.computeCullingVolume !== 'function' + ) + return null; + const radii = Cesium.Ellipsoid.WGS84.radii; + if (marginM >= Math.min(radii.x, radii.y, radii.z)) return null; + const eye = camera.positionWC; + if ( + !eye || + !Number.isFinite(eye.x) || + !Number.isFinite(eye.y) || + !Number.isFinite(eye.z) + ) + return null; + const direction = camera.directionWC; + const up = camera.upWC; + if ( + !direction || + !up || + !Number.isFinite(direction.x) || + !Number.isFinite(direction.y) || + !Number.isFinite(direction.z) || + !Number.isFinite(up.x) || + !Number.isFinite(up.y) || + !Number.isFinite(up.z) + ) + return null; + for (const p of points) { + if ( + !p || + !Number.isFinite(p.x) || + !Number.isFinite(p.y) || + !Number.isFinite(p.z) + ) + return null; + } + if (visibilityMargin !== marginM) { + visibilityMargin = marginM; + visibilityEllipsoid = new Cesium.Ellipsoid( + radii.x - marginM, + radii.y - marginM, + radii.z - marginM, + ); + visibilityOccluder = new Cesium.EllipsoidalOccluder(visibilityEllipsoid); + } + const inverse = visibilityEllipsoid.oneOverRadii; + const outside = + Math.hypot(eye.x * inverse.x, eye.y * inverse.y, eye.z * inverse.z) >= 1; + if (outside) { + visibilityOccluder.cameraPosition = eye; + let visible = false; + for (const p of points) { + if (visibilityOccluder.isPointVisible(p)) { + visible = true; + break; + } + } + if (!visible) return false; + } + const culling = camera.frustum.computeCullingVolume( + eye, + camera.directionWC, + camera.upWC, + ); + return ( + culling.computeVisibility( + Cesium.BoundingSphere.fromPoints(points, visibilitySphere), + ) !== Cesium.Intersect.OUTSIDE + ); + }; +} + /** * @param {{scene: object, camera: object, report: (error: unknown) => void, * widget?: object, capabilities?: ReadonlySet, @@ -350,9 +433,7 @@ export function createCesiumCamera({ } const cameraPort = { - // The ECEF camera pose describes the globe only in 3D. Consumers that - // cannot prove this must avoid globe-only visibility culling. - isWorld3D: () => scene.mode === Cesium.SceneMode.SCENE3D, + visiblePoints: createPointsVisibility(scene, camera), on: (event, cb, options) => cameraEvents.on(event, cb, options), onCommand: (cb) => commandHooks.on(cb), setView(spec) { diff --git a/src/render/cesium/cameraPort.test.mjs b/src/render/cesium/cameraPort.test.mjs index 92922b71ec..5328fca3f0 100644 --- a/src/render/cesium/cameraPort.test.mjs +++ b/src/render/cesium/cameraPort.test.mjs @@ -337,21 +337,23 @@ test('the camera port gives the clock its own tick back as it goes', () => { } }); -test('camera reports globe mode and fails closed for other modes', () => { +test('camera visibility is unknown outside 3D and resolves on the globe', () => { const { scene, camera } = headlessCamera(); scene.postUpdate = new Cesium.Event(); scene.requestRender = () => {}; const { port } = createCesiumCamera({ scene, camera, report: () => {} }); - for (const [mode, expected] of [ - [Cesium.SceneMode.SCENE3D, true], - [Cesium.SceneMode.SCENE2D, false], - [Cesium.SceneMode.COLUMBUS_VIEW, false], - [Cesium.SceneMode.MORPHING, false], - [undefined, false], + const points = [Cesium.Cartesian3.fromDegrees(0, 0, 10)]; + for (const mode of [ + Cesium.SceneMode.SCENE2D, + Cesium.SceneMode.COLUMBUS_VIEW, + Cesium.SceneMode.MORPHING, + undefined, ]) { scene.mode = mode; - assert.equal(port.isWorld3D(), expected); + assert.equal(port.visiblePoints(points, 200), null); } + scene.mode = Cesium.SceneMode.SCENE3D; + assert.equal(typeof port.visiblePoints(points, 200), 'boolean'); }); test('setFov holds the vertical angle across resizes, and waits for a first one', () => { diff --git a/src/render/contract/camera.d.ts b/src/render/contract/camera.d.ts index 82023db6ff..8bf2705242 100644 --- a/src/render/contract/camera.d.ts +++ b/src/render/contract/camera.d.ts @@ -234,8 +234,8 @@ export type CameraEvent = 'changed' | 'moveStart' | 'moveEnd' | 'followChanged' | 'flightEnd'; export interface CameraPort { - /** True only when its pose is an ECEF view of the 3D globe. Missing means unknown. */ - isWorld3D?(): boolean; + /** Conservative visibility of an ECEF point set, with a horizon margin in metres; null means unknown. */ + visiblePoints?(points: Ecef[], horizonMarginM: number): boolean | null; pose(): CameraPose; /** * Place the eye. A position with a `{direction, up}` orientation is placed From 02c60c0a208328d7fe7da692c9bd5e3d1a966fc7 Mon Sep 17 00:00:00 2001 From: brandonabyrd Date: Wed, 18 Nov 2026 15:42:17 -0600 Subject: [PATCH 10/14] fix(cctv): fail open before projection geometry exists --- src/layers/cctv/frames.js | 1 + src/layers/cctv/frames.test.mjs | 6 +++++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/src/layers/cctv/frames.js b/src/layers/cctv/frames.js index d92afd79ec..41c59f0e24 100644 --- a/src/layers/cctv/frames.js +++ b/src/layers/cctv/frames.js @@ -256,6 +256,7 @@ export function createFrames({ state: layerState, services, parts, source }) { const camera = findCamera(viewer); if (typeof camera?.visiblePoints !== 'function') return true; const placed = record?.frustumPositions; + if (!placed) return true; const points = _scratchPoints; points.length = 0; if (record?.position) points.push(record.position); diff --git a/src/layers/cctv/frames.test.mjs b/src/layers/cctv/frames.test.mjs index 2aca236a5e..d2c6b1a6d7 100644 --- a/src/layers/cctv/frames.test.mjs +++ b/src/layers/cctv/frames.test.mjs @@ -448,6 +448,10 @@ test('what cannot be judged counts as visible', () => { const flat = lookingDown(); flat.scene.mode = Cesium.SceneMode.SCENE2D; assert.equal(framesFor(flat).projectionInView(record), true); - const noGeometry = { camera: { id: 'plane' }, projection: record.projection }; + const noGeometry = { + camera: { id: 'plane' }, + projection: record.projection, + position: point(180, 0, 20), + }; assert.equal(framesFor(lookingDown()).projectionInView(noGeometry), true); }); From 28007e20efbbb05f0b2079013d9cca90c1c534c5 Mon Sep 17 00:00:00 2001 From: brandonabyrd Date: Wed, 18 Nov 2026 16:17:57 -0600 Subject: [PATCH 11/14] fix(cctv): register camera point visibility capability --- src/layers/cctv/frames.js | 3 ++- src/render/cesium/camera.js | 3 ++- src/render/cesium/controlledCamera.test.mjs | 2 ++ src/render/cesium/ports.js | 5 ++++- src/render/cesium/ports.test.mjs | 1 + src/render/contract/common.d.ts | 2 ++ src/render/contract/index.js | 2 ++ src/render/stub/index.js | 2 ++ src/render/stub/stub.test.mjs | 9 +++++++++ 9 files changed, 26 insertions(+), 3 deletions(-) diff --git a/src/layers/cctv/frames.js b/src/layers/cctv/frames.js index 41c59f0e24..c0a820dd3d 100644 --- a/src/layers/cctv/frames.js +++ b/src/layers/cctv/frames.js @@ -43,6 +43,7 @@ export function fitToProjection(sourceW, sourceH) { } const _scratchPoints = []; +const HORIZON_MARGIN_M = 200; export function createFrames({ state: layerState, services, parts, source }) { /** @@ -267,7 +268,7 @@ export function createFrames({ state: layerState, services, parts, source }) { if (placed?.br) points.push(placed.br); if (placed?.bl) points.push(placed.bl); // Unknown modes or unsupported cameras must not suppress pictures. - return camera.visiblePoints(points, 200) !== false; + return camera.visiblePoints(points, HORIZON_MARGIN_M) !== false; } /** diff --git a/src/render/cesium/camera.js b/src/render/cesium/camera.js index e589de38d6..bcf251224f 100644 --- a/src/render/cesium/camera.js +++ b/src/render/cesium/camera.js @@ -433,7 +433,6 @@ export function createCesiumCamera({ } const cameraPort = { - visiblePoints: createPointsVisibility(scene, camera), on: (event, cb, options) => cameraEvents.on(event, cb, options), onCommand: (cb) => commandHooks.on(cb), setView(spec) { @@ -753,6 +752,8 @@ export function createCesiumCamera({ }); // Cesium keeps the eye in `camera.transform`: a tracked entity's frame, a // `lookAt` target's, or the identity. + if (!capabilities || capabilities.has('pointVisibility')) + cameraPort.visiblePoints = createPointsVisibility(scene, camera); if (!capabilities || capabilities.has('followFrame')) cameraPort.followFrame = () => { if (!lastFollowFrame || !sameMatrix(lastFollowFrame, camera.transform)) diff --git a/src/render/cesium/controlledCamera.test.mjs b/src/render/cesium/controlledCamera.test.mjs index 54945e31a3..e92f74c8da 100644 --- a/src/render/cesium/controlledCamera.test.mjs +++ b/src/render/cesium/controlledCamera.test.mjs @@ -321,6 +321,8 @@ test('the application’s Cesium renderer runs the controller around its preUpda const renderer = await plugin.create({ container: {} }); assert.equal(scene.screenSpaceCameraController.enableInputs, false); assert.equal(typeof renderer.camera.native.setPose, 'function'); + assert.equal(renderer.capabilities.has('pointVisibility'), true); + assert.equal(renderer.camera.visiblePoints([], 200), null); renderer.frame.on('preUpdate', () => order.push('preUpdate')); scene.preUpdate.raise(scene, Cesium.JulianDate.fromDate(new Date(5000))); assert.deepEqual(order, [['before', 5000], 'preUpdate', 'after']); diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index 5f73daa482..ba69cb1991 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -13,7 +13,7 @@ * absent, never stubbed. */ import * as Cesium from 'cesium'; -import { createCesiumCamera } from './camera.js'; +import { createCesiumCamera, createPointsVisibility } from './camera.js'; import { createControlledCamera } from './controlledCamera.js'; import { listenerList, toCartesian, uncaught } from './common.js'; import { createCesiumCredits } from './credits.js'; @@ -80,6 +80,7 @@ export function cesiumCapabilities(scene, only) { // Raster shells; other field kinds are refused. 'fields', 'followFrame', + 'pointVisibility', // Cesium's AUTODETECT tracking frame (`follow.js`). 'followAutodetect', 'cameraChangeThreshold', @@ -484,6 +485,8 @@ export function createCesiumPorts( : {}), }); const cameraPort = cameraPart.port; + if (controlled && capabilities.has('pointVisibility')) + cameraPort.visiblePoints = createPointsVisibility(scene, camera); measureCameraChanged = cameraPart.measureChanged ?? null; const effectsPart = createCesiumEffects(scene, { capabilities, diff --git a/src/render/cesium/ports.test.mjs b/src/render/cesium/ports.test.mjs index fc0e40bff2..e7cb9582a2 100644 --- a/src/render/cesium/ports.test.mjs +++ b/src/render/cesium/ports.test.mjs @@ -12,6 +12,7 @@ import { createNativeClick } from './nativeClick.js'; test('capabilities follow what the scene supports', () => { const effects = [ 'followFrame', + 'pointVisibility', 'followAutodetect', 'cameraChangeThreshold', 'columns', diff --git a/src/render/contract/common.d.ts b/src/render/contract/common.d.ts index df585c2484..09b15c4acd 100644 --- a/src/render/contract/common.d.ts +++ b/src/render/contract/common.d.ts @@ -179,6 +179,8 @@ export type Capability = | 'pickPosition' /** Points tested against the frame's depth (`query.occlusionTest`). */ | 'occlusionTest' + /** Conservative camera visibility of a point set (`camera.visiblePoints`). */ + | 'pointVisibility' /** Outward user zooms that keep the Earth framed (`controls.keepEarthFramed`). */ | 'keepEarthFramed' /** Height sampling against tiles and terrain. */ diff --git a/src/render/contract/index.js b/src/render/contract/index.js index 2198b6226c..c18e0e5cb2 100644 --- a/src/render/contract/index.js +++ b/src/render/contract/index.js @@ -48,6 +48,7 @@ export const CAPABILITIES = Object.freeze([ 'followFrame', 'cameraChangeThreshold', 'occlusionTest', + 'pointVisibility', 'keepEarthFramed', ]); @@ -207,6 +208,7 @@ export const PORTS = deepFreeze({ 'matrices', ), ['followFrame', 'followFrame'], + ['visiblePoints', 'pointVisibility'], ['controls.keepEarthFramed', 'keepEarthFramed'], ]), query: Object.fromEntries([ diff --git a/src/render/stub/index.js b/src/render/stub/index.js index 9eb21cfc58..85451d63c3 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -261,6 +261,8 @@ export function createStubRenderer(options = {}) { camera.setViewRectangle(viewRectangle); if (capabilities.has('followFrame')) camera.port.followFrame = camera.eyeFrame; + if (capabilities.has('pointVisibility')) + camera.port.visiblePoints = () => null; camera.port.setView({ destination: { lon: -97.7431, lat: 30.2672, height: 15000000 }, }); diff --git a/src/render/stub/stub.test.mjs b/src/render/stub/stub.test.mjs index d2da3f359d..04517dd6fe 100644 --- a/src/render/stub/stub.test.mjs +++ b/src/render/stub/stub.test.mjs @@ -40,6 +40,15 @@ test('the stub passes the conformance suite', async () => { ]); }); +test('point visibility capability is optional and the stub reports unknown', () => { + const without = createStubRenderer({ capabilities: [] }); + const withVisibility = createStubRenderer({ + capabilities: ['pointVisibility'], + }); + assert.equal(without.camera.visiblePoints, undefined); + assert.equal(withVisibility.camera.visiblePoints([], 200), null); +}); + test('a frame runs the contract’s steps in order', () => { const r = createStubRenderer(); r.frame.requestRender('test'); From b020a1cd91a0a265e736586eb9911a02303253c0 Mon Sep 17 00:00:00 2001 From: brandonabyrd Date: Wed, 18 Nov 2026 16:25:19 -0600 Subject: [PATCH 12/14] docs: describe camera point visibility capability --- docs/RENDERER-CONTRACT.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 76d547cb09..26a5b789ef 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -81,6 +81,9 @@ optional: target's east-north-up frame, or the identity. `setView` keeps that frame while it places a world pose. A share link's follow offset is re-expressed in it, satellites included. +- `camera.visiblePoints(points, horizonMarginM)` (capability `pointVisibility`) + conservatively reports whether a point set may be visible; `null` means the + renderer cannot determine visibility and callers should fail open. - `globe.surfaceVersion()` (capability `surfaceIdentity`) is a number that changes whenever what surface heights answer against changes (base, terrain or photoreal route swapped, the globe shown or hidden) and never From 99a70a0e0c13716283355529e1d78f09f8105eea Mon Sep 17 00:00:00 2001 From: German Khokhlov Date: Thu, 19 Nov 2026 18:28:51 +0400 Subject: [PATCH 13/14] fix(cctv): keep the Context camera card's still and tidy the visibility port The still preview gate looked only at the CCTV panel, so the Context camera card, which reads the same frame, stopped updating while the panel was collapsed or another phone sheet was open. A mounted card now counts itself in the CCTV store, and the still is requested while the panel or a card is shown; live video still follows the panel only. Review follow-ups in the same area: - visiblePoints is registered once, in createCesiumPorts, and drops checks for input that cannot happen; the contract documents horizonMarginM and when it answers false or null. - The layer passes the mount and the four corners once each and asks findCamera for the port. - Phone sheet names come from a shared module instead of literals. - Layer tests cover the fetch gate; the geometry cases moved to the camera port tests. Comments and CURRENT-STATE match the code. --- changelog.d/1543-cctv-visible-only-fetch.md | 4 +- docs/CURRENT-STATE.md | 18 +- docs/RENDERER-CONTRACT.md | 8 +- scripts/package-boundaries.json | 3 + src/layers/cctv/frames.js | 30 +- src/layers/cctv/frames.test.mjs | 296 +++----------------- src/render/cesium/camera.js | 53 +--- src/render/cesium/cameraPort.test.mjs | 136 ++++++++- src/render/cesium/ports.js | 2 +- src/render/contract/camera.d.ts | 9 +- src/ui/cctvControls.js | 16 +- src/ui/cctvPanel.test.mjs | 112 +++++--- src/ui/cctvPresentation.js | 37 ++- src/ui/contextCardFrame.test.mjs | 167 +++++++++++ src/ui/mobileSheets.js | 25 ++ src/ui/mobileShell.js | 39 +-- src/ui/stores/cctv.js | 9 + src/ui/views/panels/CctvPreview.vue | 11 +- 18 files changed, 545 insertions(+), 430 deletions(-) create mode 100644 src/ui/contextCardFrame.test.mjs create mode 100644 src/ui/mobileSheets.js diff --git a/changelog.d/1543-cctv-visible-only-fetch.md b/changelog.d/1543-cctv-visible-only-fetch.md index 80421a35c2..f12c20dbf3 100644 --- a/changelog.d/1543-cctv-visible-only-fetch.md +++ b/changelog.d/1543-cctv-visible-only-fetch.md @@ -1,4 +1,4 @@ - Stop fetching the active CCTV camera's pictures when nobody can see them. The monitor plane skips its 10 s still while it is off screen or below the - horizon, and the panel's still preview waits for a visible tab, an open - panel and, on phones, the open Cameras sheet (Byrd-IT, #1543). + horizon, and the still preview waits for a visible tab and an open panel or + Context camera card (on phones, the open Cameras or Context sheet) (Byrd-IT, #1543). diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 7cab5e0d5b..9d6038a653 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1976,16 +1976,14 @@ The view pass reruns while the camera moves, paced by its own cost. The camera picker lists the cameras in view, active camera first, and closes with the count of cameras outside the view. -The active camera's pictures follow what can be seen. The monitor plane on the -globe stops fetching its still every 10 s while the sphere around the camera -mount and the plane is outside the view, or all of its points are below the -horizon of the WGS84 ellipsoid shrunk by 200 m (a 2D or Columbus scene always -counts as visible), and fetches again on the first refresh tick after it -returns; activating or calibrating a camera always fetches. The panel's still -preview is requested only while the tab is visible and the panel is expanded -(on phones, also while the Cameras sheet is open), and the panel asks for the -current picture when it is shown again. The panel's live video follows the same -rule. +The active camera's pictures follow what can be seen. The monitor plane skips +its 10 s still while the renderer reports it off screen or below the horizon, +and fetches on the first refresh tick after it is back. Activating or +calibrating a camera bypasses visibility and the usual refresh interval, but +still waits for an in-flight request and the provider's minimum interval. +The panel's still and live video run only while the tab is visible and the +panel is open (on phones, the Cameras sheet). The still also loads while +Context shows the camera's card (on phones, the Context sheet). Traffic owns its rendered-surface observer only while enabled, removes it on disable/destroy, and rebuilds no cached heights on frames where the surface identity is unchanged. Its dots and heat-lines are two renderer draw sets, it animates on the frame port's preRender, and it follows the camera through the camera port at its own 5% threshold rather than the shared `percentageChanged` ledger. The surface identity is the globe port's `surfaceVersion()` and tile readiness its `isSettled('surface')`, so the layer no longer reaches Cesium. Heat-lines are always asked for draped: where the Cesium renderer cannot drape (no depth textures) its draw port draws them (and every other draped line) over the surface, in their colour where the surface hides them and hidden past the horizon, recolouring a line in place when only its colour changes, rather than the layer dropping them. diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 26a5b789ef..9134799705 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -82,8 +82,12 @@ optional: while it places a world pose. A share link's follow offset is re-expressed in it, satellites included. - `camera.visiblePoints(points, horizonMarginM)` (capability `pointVisibility`) - conservatively reports whether a point set may be visible; `null` means the - renderer cannot determine visibility and callers should fail open. + is whether any of the points may be on screen: `false` only when their + bounding sphere is outside the view or all of them are below the horizon + of the WGS84 ellipsoid shrunk by `horizonMarginM` metres; `null` when it + cannot tell (not a 3D scene, an empty point set, or a non-finite point or + camera vector), and callers count that as visible. Supply a finite, + nonnegative margin smaller than the shortest WGS84 radius. - `globe.surfaceVersion()` (capability `surfaceIdentity`) is a number that changes whenever what surface heights answer against changes (base, terrain or photoreal route swapped, the globe shown or hidden) and never diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index a09757f481..3d6c2d9652 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1067,6 +1067,7 @@ "src/ui/cctv.js", "src/ui/cctvBindings.js", "src/ui/cctvCalibration.js", + "src/ui/mobileSheets.js", "src/ui/cctvControls.js", "src/ui/cctvFrames.js", "src/ui/cctvVideo.js", @@ -1301,6 +1302,7 @@ "src/data/distanceFormat.js", "src/i18n/marker.js", "src/ui/mobileShell.js", + "src/ui/mobileSheets.js", "src/exclusiveSurfaces.js", "src/ui/placeNames.js", "src/hudLayouts.js", @@ -4708,6 +4710,7 @@ "src/ui/applicationShell.js", "src/ui/railEdgeScroll.js", "src/ui/mobileShell.js", + "src/ui/mobileSheets.js", "src/ui/localePicker.js", "src/ui/cyberSonarControls.js", "src/ui/locationNavigation.js", diff --git a/src/layers/cctv/frames.js b/src/layers/cctv/frames.js index c0a820dd3d..7ca4d4b6fc 100644 --- a/src/layers/cctv/frames.js +++ b/src/layers/cctv/frames.js @@ -42,7 +42,9 @@ export function fitToProjection(sourceW, sourceH) { }; } +const PLANE_POINTS = ['mount', 'tl', 'tr', 'br', 'bl']; const _scratchPoints = []; +// Keep the occluding surface below common negative geoid undulations. const HORIZON_MARGIN_M = 200; export function createFrames({ state: layerState, services, parts, source }) { @@ -241,33 +243,18 @@ export function createFrames({ state: layerState, services, parts, source }) { } /** - * Whether a camera's monitor plane can be on screen: the mount, the far cap - * and its corners are bounded by one sphere that is tested against the view - * frustum, and at least one of those points must be above a conservative - * horizon computed from a shrunken reference ellipsoid. - * Anything this cannot judge (no viewer, a 2D or Columbus scene, no geometry - * yet) counts as visible, so a missing input never blocks a picture. + * Whether a camera's monitor plane may be on screen; what cannot be judged counts as visible. * @param {Object} record - Camera record. * @returns {boolean} */ - function projectionInView(record) { - const viewer = layerState._viewer; - if (!viewer || viewer.isDestroyed?.()) return true; - const camera = findCamera(viewer); + const camera = findCamera(layerState._viewer); if (typeof camera?.visiblePoints !== 'function') return true; - const placed = record?.frustumPositions; + const placed = record.frustumPositions; if (!placed) return true; const points = _scratchPoints; points.length = 0; - if (record?.position) points.push(record.position); - if (placed?.mount) points.push(placed.mount); - if (placed?.capCenter) points.push(placed.capCenter); - if (placed?.tl) points.push(placed.tl); - if (placed?.tr) points.push(placed.tr); - if (placed?.br) points.push(placed.br); - if (placed?.bl) points.push(placed.bl); - // Unknown modes or unsupported cameras must not suppress pictures. + for (const key of PLANE_POINTS) points.push(placed[key]); return camera.visiblePoints(points, HORIZON_MARGIN_M) !== false; } @@ -304,9 +291,7 @@ export function createFrames({ state: layerState, services, parts, source }) { // bypass a provider's explicit minimum between image requests. if (sourceRefreshMs > 0 && sinceLastRefresh < sourceRefreshMs) return; if (!force && sinceLastRefresh < refreshMs) return; - // A plane nobody can see (panned away, far side of the globe) needs no new - // picture; the next tick after it comes back fetches one. A forced refresh - // (fresh activation, calibration) still runs. + // Skip before stamping lastImageRefreshAt, so the first tick back in view fetches. if (!force && !projectionInView(record)) return; runtime.lastImageRefreshAt = now; @@ -441,7 +426,6 @@ export function createFrames({ state: layerState, services, parts, source }) { mediaUrlFor, paintProjectionPlaceholder, refreshProjectionImage, - projectionInView, paintPlaceholderThrottled, drawProjectionFrame, }; diff --git a/src/layers/cctv/frames.test.mjs b/src/layers/cctv/frames.test.mjs index d2c6b1a6d7..0170797e09 100644 --- a/src/layers/cctv/frames.test.mjs +++ b/src/layers/cctv/frames.test.mjs @@ -3,9 +3,7 @@ // 1920x1080 projection canvas, instead of being stretched to fill it. import { test } from 'node:test'; import assert from 'node:assert/strict'; -import * as Cesium from 'cesium'; import { bindRenderer } from '../../render/rendererOf.js'; -import { createPointsVisibility } from '../../render/cesium/camera.js'; import { createFrames, fitToProjection } from './frames.js'; import { FRAME_SIGNATURE_W, @@ -143,31 +141,23 @@ test('same pixels at a new aspect redraw at the new fit', () => { assert.equal(runtime.canvasStamp, 2); }); -// A camera's monitor plane is fetched only while it can be on screen. The -// viewer is a Cesium camera description over the real WGS84 globe: it hovers -// 30 km above a mount at (0, 0) and looks straight down, so the plane is in -// front of it; turned around, or moved to the far side of the globe, the -// plane is not. -const MOUNT = Cesium.Cartesian3.fromDegrees(0, 0, 20); -const point = (lon, lat, alt = 20) => - Cesium.Cartesian3.fromDegrees(lon, lat, alt); +const MOUNT = { x: 0, y: 0, z: 0 }; function planeRecord() { - const image = {}; return { camera: { id: 'plane' }, - billboard: { position: MOUNT }, + position: MOUNT, frustumPositions: { mount: MOUNT, - capCenter: point(0.0005, 0, 20), - tl: point(0.0004, 0.0001), - tr: point(0.0006, 0.0001), - br: point(0.0006, -0.0001), - bl: point(0.0004, -0.0001), + capCenter: { x: 1, y: 0, z: 0 }, + tl: { x: 1, y: -1, z: 1 }, + tr: { x: 1, y: 1, z: 1 }, + br: { x: 1, y: 1, z: -1 }, + bl: { x: 1, y: -1, z: -1 }, }, projection: { mode: 'image', - image, + image: {}, imageLoading: false, imageReady: false, lastImageRefreshAt: 0, @@ -175,42 +165,6 @@ function planeRecord() { }; } -function viewerAt(position, direction, up) { - const viewer = { - isDestroyed: () => false, - scene: { mode: Cesium.SceneMode.SCENE3D }, - camera: { - positionWC: position, - directionWC: direction, - upWC: up, - frustum: new Cesium.PerspectiveFrustum({ - fov: Cesium.Math.toRadians(60), - aspectRatio: 16 / 9, - near: 1, - // Cesium's default far plane, as the app uses: a smaller one rejects - // the far-side mount before the horizon check is ever reached. - far: 5e8, - }), - }, - }; - bindRenderer(viewer, { - camera: { - visiblePoints: createPointsVisibility(viewer.scene, viewer.camera), - }, - }); - return viewer; -} - -// Above the mount, looking straight down at the ground. -function lookingDown() { - const position = point(0, 0, 30000); - return viewerAt( - position, - Cesium.Cartesian3.negate(Cesium.Cartesian3.UNIT_X, new Cesium.Cartesian3()), - Cesium.Cartesian3.UNIT_Z, - ); -} - function framesFor(viewer) { const state = { _viewer: viewer, @@ -230,28 +184,33 @@ function framesFor(viewer) { }); } -test('a plane in front of the camera fetches its picture', () => { - const frames = framesFor(lookingDown()); +function framesWithCamera(t, camera) { + const host = {}; + t.after(bindRenderer(host, { camera })); + return framesFor(host); +} + +test('a plane the renderer may show fetches its picture', (t) => { + const visiblePoints = t.mock.fn(() => true); + const frames = framesWithCamera(t, { visiblePoints }); const record = planeRecord(); - assert.equal(frames.projectionInView(record), true); frames.refreshProjectionImage(record); assert.match( record.projection.image.src, /^\/api\/cctv\/frame\?id=plane&projTs=/, ); assert.equal(record.projection.imageLoading, true); + assert.equal(visiblePoints.mock.callCount(), 1); + const [points, margin] = visiblePoints.mock.calls[0].arguments; + const { mount, tl, tr, br, bl } = record.frustumPositions; + assert.deepEqual(points, [mount, tl, tr, br, bl]); + assert.equal(points[0], mount); + assert.equal(margin, 200); }); -test('a plane behind the camera is not fetched, but a forced refresh is', () => { - const down = lookingDown(); - const away = viewerAt( - down.camera.positionWC, - Cesium.Cartesian3.UNIT_X, - Cesium.Cartesian3.UNIT_Z, - ); - const frames = framesFor(away); +test('a plane the renderer cannot show is not fetched, but a forced refresh is', (t) => { + const frames = framesWithCamera(t, { visiblePoints: () => false }); const record = planeRecord(); - assert.equal(frames.projectionInView(record), false); frames.refreshProjectionImage(record); assert.equal(record.projection.image.src, undefined); assert.equal(record.projection.lastImageRefreshAt, 0); @@ -259,199 +218,32 @@ test('a plane behind the camera is not fetched, but a forced refresh is', () => assert.match(record.projection.image.src, /projTs=/); }); -test('a nearby plane below the ellipsoid still fetches for a low viewer', () => { +test('a skipped refresh does not use up the interval', (t) => { + let visible = false; + const frames = framesWithCamera(t, { visiblePoints: () => visible }); const record = planeRecord(); - const mount = point(0, 0, -18); - const cap = point(0.00054, 0, -18); - const position = point(0.00135, 0, 4); - record.billboard.position = mount; - record.frustumPositions = { mount, capCenter: cap }; - const direction = Cesium.Cartesian3.normalize( - Cesium.Cartesian3.subtract(cap, position, new Cesium.Cartesian3()), - new Cesium.Cartesian3(), - ); - const viewer = viewerAt(position, direction, Cesium.Cartesian3.UNIT_Z); - const sphere = Cesium.BoundingSphere.fromPoints([mount, cap]); - const culling = viewer.camera.frustum.computeCullingVolume( - position, - direction, - viewer.camera.upWC, - ); - assert.notEqual(culling.computeVisibility(sphere), Cesium.Intersect.OUTSIDE); - const frames = framesFor(viewer); - assert.equal(frames.projectionInView(record), true); frames.refreshProjectionImage(record); - assert.match(record.projection.image.src, /projTs=/); - - // The same below-ellipsoid plane remains visible from a higher viewer. - const high = point(0.00135, 0, 1200); - const highDirection = Cesium.Cartesian3.normalize( - Cesium.Cartesian3.subtract(cap, high, new Cesium.Cartesian3()), - new Cesium.Cartesian3(), - ); - assert.equal( - framesFor( - viewerAt(high, highDirection, Cesium.Cartesian3.UNIT_Z), - ).projectionInView(record), - true, - ); -}); - -test('the horizon still rejects a negative-height plane on the far side', () => { - for (const altitude of [4, 30000, 2e7]) { - const record = planeRecord(); - const mount = point(0, 0, -18); - const cap = point(0.00054, 0, -18); - record.billboard.position = mount; - record.frustumPositions = { mount, capCenter: cap }; - const position = point(180, 0, altitude); - const direction = Cesium.Cartesian3.normalize( - Cesium.Cartesian3.subtract(mount, position, new Cesium.Cartesian3()), - new Cesium.Cartesian3(), - ); - const viewer = viewerAt(position, direction, Cesium.Cartesian3.UNIT_Z); - const sphere = Cesium.BoundingSphere.fromPoints([mount, cap]); - assert.notEqual( - viewer.camera.frustum - .computeCullingVolume(position, direction, viewer.camera.upWC) - .computeVisibility(sphere), - Cesium.Intersect.OUTSIDE, - ); - assert.equal(framesFor(viewer).projectionInView(record), false); - } -}); - -test('a low viewer can see a plane beyond the WGS84 horizon', () => { - const record = planeRecord(); - const mount = point(0, 0, 1); - record.billboard.position = mount; - record.frustumPositions = { mount }; - const position = point(0.2, 0, 4); - const direction = Cesium.Cartesian3.normalize( - Cesium.Cartesian3.subtract(mount, position, new Cesium.Cartesian3()), - new Cesium.Cartesian3(), - ); - const viewer = viewerAt(position, direction, Cesium.Cartesian3.UNIT_Z); - assert.equal(framesFor(viewer).projectionInView(record), true); -}); - -test('a plane below the horizon is not fetched', () => { - const far = point(180, 0, 30000); - const viewer = viewerAt( - far, - Cesium.Cartesian3.normalize( - Cesium.Cartesian3.subtract(MOUNT, far, new Cesium.Cartesian3()), - new Cesium.Cartesian3(), - ), - Cesium.Cartesian3.UNIT_Z, - ); - const frames = framesFor(viewer); - assert.equal(frames.projectionInView(planeRecord()), false); -}); - -test('a skipped refresh does not use up the interval: the plane fetches once it is back in view', () => { - const record = planeRecord(); - const frames = framesFor(lookingDown()); - const away = viewerAt( - lookingDown().camera.positionWC, - Cesium.Cartesian3.UNIT_X, - Cesium.Cartesian3.UNIT_Z, - ); - const awayFrames = framesFor(away); - awayFrames.refreshProjectionImage(record); assert.equal(record.projection.image.src, undefined); + visible = true; frames.refreshProjectionImage(record); assert.match(record.projection.image.src, /projTs=/); }); -test('the renderer scene host culls the far side without raw viewer access', () => { - const native = lookingDown(); - const viewer = { isDestroyed: () => false }; - const camera = native.camera; - camera.directionWC = Cesium.Cartesian3.UNIT_X; - const unbind = bindRenderer(viewer, { - camera: { visiblePoints: createPointsVisibility(native.scene, camera) }, - }); - try { - assert.equal(framesFor(viewer).projectionInView(planeRecord()), false); - } finally { - unbind(); +test('what cannot be judged counts as visible', (t) => { + for (const frames of [ + framesWithCamera(t, { visiblePoints: () => null }), + framesWithCamera(t, { pose: () => ({}) }), + framesFor(null), + ]) { + const record = planeRecord(); + frames.refreshProjectionImage(record); + assert.match(record.projection.image.src, /projTs=/); } -}); -test('visibility checks reuse the points array across ticks', () => { - const seen = []; - const host = {}; - const unbind = bindRenderer(host, { - camera: { - visiblePoints: (points) => { - seen.push(points); - return true; - }, - }, - }); - try { - const frames = framesFor(host); - frames.projectionInView(planeRecord()); - frames.projectionInView(planeRecord()); - assert.equal(seen.length, 2); - assert.strictEqual(seen[0], seen[1]); - } finally { - unbind(); - } -}); - -test('deep viewers do not lose nearby planes to the horizon test', () => { - const mount = point(0, 0, -350); - const position = point(0.00135, 0, -300); - const direction = Cesium.Cartesian3.normalize( - Cesium.Cartesian3.subtract(mount, position, new Cesium.Cartesian3()), - new Cesium.Cartesian3(), - ); - const record = planeRecord(); - record.frustumPositions = { mount }; - record.position = mount; - assert.equal( - framesFor( - viewerAt(position, direction, Cesium.Cartesian3.UNIT_Z), - ).projectionInView(record), - true, - ); -}); - -test('flat and unknown projections fail open', () => { - const native = lookingDown(); - native.camera.directionWC = Cesium.Cartesian3.UNIT_X; - native.scene.mode = Cesium.SceneMode.COLUMBUS_VIEW; - assert.equal(framesFor(native).projectionInView(planeRecord()), true); - native.scene.mode = Cesium.SceneMode.SCENE3D; - native.camera.directionWC = undefined; - assert.equal(framesFor(native).projectionInView(planeRecord()), true); - const host = {}; - const unbind = bindRenderer(host, { camera: { pose: () => ({}) } }); - try { - assert.equal(framesFor(host).projectionInView(planeRecord()), true); - } finally { - unbind(); - } -}); - -test('what cannot be judged counts as visible', () => { - const record = planeRecord(); - assert.equal(framesFor(null).projectionInView(record), true); - assert.equal( - framesFor({ ...lookingDown(), isDestroyed: () => true }).projectionInView( - record, - ), - true, - ); - const flat = lookingDown(); - flat.scene.mode = Cesium.SceneMode.SCENE2D; - assert.equal(framesFor(flat).projectionInView(record), true); - const noGeometry = { - camera: { id: 'plane' }, - projection: record.projection, - position: point(180, 0, 20), - }; - assert.equal(framesFor(lookingDown()).projectionInView(noGeometry), true); + const noGeometry = planeRecord(); + delete noGeometry.frustumPositions; + const visiblePoints = t.mock.fn(() => false); + framesWithCamera(t, { visiblePoints }).refreshProjectionImage(noGeometry); + assert.equal(visiblePoints.mock.callCount(), 0); + assert.match(noGeometry.projection.image.src, /projTs=/); }); diff --git a/src/render/cesium/camera.js b/src/render/cesium/camera.js index bcf251224f..9c31d34c8d 100644 --- a/src/render/cesium/camera.js +++ b/src/render/cesium/camera.js @@ -86,6 +86,9 @@ function sameMatrix(array, matrix) { return true; } +const finiteVector = (v) => + !!v && Number.isFinite(v.x) && Number.isFinite(v.y) && Number.isFinite(v.z); + /** Conservative globe/frustum visibility; null means unknown. */ export function createPointsVisibility(scene, camera) { const visibilitySphere = new Cesium.BoundingSphere(); @@ -93,47 +96,20 @@ export function createPointsVisibility(scene, camera) { let visibilityEllipsoid = null; let visibilityOccluder = null; return function visiblePoints(points, marginM) { - if ( - scene.mode !== Cesium.SceneMode.SCENE3D || - !points?.length || - !Number.isFinite(marginM) || - marginM < 0 || - typeof camera.frustum?.computeCullingVolume !== 'function' - ) - return null; - const radii = Cesium.Ellipsoid.WGS84.radii; - if (marginM >= Math.min(radii.x, radii.y, radii.z)) return null; const eye = camera.positionWC; - if ( - !eye || - !Number.isFinite(eye.x) || - !Number.isFinite(eye.y) || - !Number.isFinite(eye.z) - ) - return null; const direction = camera.directionWC; const up = camera.upWC; if ( - !direction || - !up || - !Number.isFinite(direction.x) || - !Number.isFinite(direction.y) || - !Number.isFinite(direction.z) || - !Number.isFinite(up.x) || - !Number.isFinite(up.y) || - !Number.isFinite(up.z) + scene.mode !== Cesium.SceneMode.SCENE3D || + !points?.length || + !finiteVector(eye) || + !finiteVector(direction) || + !finiteVector(up) || + !points.every(finiteVector) ) return null; - for (const p of points) { - if ( - !p || - !Number.isFinite(p.x) || - !Number.isFinite(p.y) || - !Number.isFinite(p.z) - ) - return null; - } if (visibilityMargin !== marginM) { + const radii = Cesium.Ellipsoid.WGS84.radii; visibilityMargin = marginM; visibilityEllipsoid = new Cesium.Ellipsoid( radii.x - marginM, @@ -143,6 +119,7 @@ export function createPointsVisibility(scene, camera) { visibilityOccluder = new Cesium.EllipsoidalOccluder(visibilityEllipsoid); } const inverse = visibilityEllipsoid.oneOverRadii; + // Inside the ellipsoid Cesium's occluder hides nearby points; judge by the frustum alone. const outside = Math.hypot(eye.x * inverse.x, eye.y * inverse.y, eye.z * inverse.z) >= 1; if (outside) { @@ -156,11 +133,7 @@ export function createPointsVisibility(scene, camera) { } if (!visible) return false; } - const culling = camera.frustum.computeCullingVolume( - eye, - camera.directionWC, - camera.upWC, - ); + const culling = camera.frustum.computeCullingVolume(eye, direction, up); return ( culling.computeVisibility( Cesium.BoundingSphere.fromPoints(points, visibilitySphere), @@ -752,8 +725,6 @@ export function createCesiumCamera({ }); // Cesium keeps the eye in `camera.transform`: a tracked entity's frame, a // `lookAt` target's, or the identity. - if (!capabilities || capabilities.has('pointVisibility')) - cameraPort.visiblePoints = createPointsVisibility(scene, camera); if (!capabilities || capabilities.has('followFrame')) cameraPort.followFrame = () => { if (!lastFollowFrame || !sameMatrix(lastFollowFrame, camera.transform)) diff --git a/src/render/cesium/cameraPort.test.mjs b/src/render/cesium/cameraPort.test.mjs index 5328fca3f0..36d841efed 100644 --- a/src/render/cesium/cameraPort.test.mjs +++ b/src/render/cesium/cameraPort.test.mjs @@ -19,7 +19,7 @@ import { headlessCamera, withVirtualClock, } from './cameraGoldens.js'; -import { createCesiumCamera } from './camera.js'; +import { createCesiumCamera, createPointsVisibility } from './camera.js'; import { createCesiumPorts } from './ports.js'; import { bindRenderer, cameraOf } from '../rendererOf.js'; @@ -337,11 +337,20 @@ test('the camera port gives the clock its own tick back as it goes', () => { } }); -test('camera visibility is unknown outside 3D and resolves on the globe', () => { - const { scene, camera } = headlessCamera(); - scene.postUpdate = new Cesium.Event(); +test('visiblePoints is there only with its capability, and unknown outside 3D', (t) => { + const { scene } = headlessCamera(); + for (const name of ['preUpdate', 'postUpdate', 'preRender', 'postRender']) + scene[name] = new Cesium.Event(); + scene.primitives = { add() {}, remove() {} }; scene.requestRender = () => {}; - const { port } = createCesiumCamera({ scene, camera, report: () => {} }); + const viewer = { scene, clock: { currentTime: Cesium.JulianDate.now() } }; + const without = createCesiumPorts(viewer, { capabilities: new Set() }); + assert.equal(without.camera.visiblePoints, undefined); + without.dispose(); + const ports = createCesiumPorts(viewer, { + capabilities: new Set(['pointVisibility']), + }); + t.after(() => ports.dispose()); const points = [Cesium.Cartesian3.fromDegrees(0, 0, 10)]; for (const mode of [ Cesium.SceneMode.SCENE2D, @@ -350,10 +359,123 @@ test('camera visibility is unknown outside 3D and resolves on the globe', () => undefined, ]) { scene.mode = mode; - assert.equal(port.visiblePoints(points, 200), null); + assert.equal(ports.camera.visiblePoints(points, 200), null); } scene.mode = Cesium.SceneMode.SCENE3D; - assert.equal(typeof port.visiblePoints(points, 200), 'boolean'); + assert.equal(typeof ports.camera.visiblePoints(points, 200), 'boolean'); +}); + +const point = (lon, lat, altitude = 20) => + Cesium.Cartesian3.fromDegrees(lon, lat, altitude); +const down = Cesium.Cartesian3.negate( + Cesium.Cartesian3.UNIT_X, + new Cesium.Cartesian3(), +); +const up = Cesium.Cartesian3.UNIT_Z; +const frustum = new Cesium.PerspectiveFrustum({ + fov: Cesium.Math.toRadians(60), + aspectRatio: 16 / 9, + near: 1, + // Cesium's default far plane, as the app uses. + far: 5e8, +}); + +function visibility(position, direction, up) { + const visiblePoints = createPointsVisibility( + { mode: Cesium.SceneMode.SCENE3D }, + { positionWC: position, directionWC: direction, upWC: up, frustum }, + ); + return (points) => visiblePoints(points, 200); +} + +function directionTo(position, target) { + return Cesium.Cartesian3.normalize( + Cesium.Cartesian3.subtract(target, position, new Cesium.Cartesian3()), + new Cesium.Cartesian3(), + ); +} + +function assertInFrustum(points, position, direction) { + const culling = frustum.computeCullingVolume(position, direction, up); + assert.notEqual( + culling.computeVisibility(Cesium.BoundingSphere.fromPoints(points)), + Cesium.Intersect.OUTSIDE, + ); +} + +test('a plane in front of the camera is visible', () => { + assert.equal(visibility(point(0, 0, 30000), down, up)([point(0, 0)]), true); +}); + +test('a plane behind the camera is outside the frustum', () => { + assert.equal( + visibility(point(0, 0, 30000), Cesium.Cartesian3.UNIT_X, up)([point(0, 0)]), + false, + ); +}); + +test('a corner can be in view when the mount and centre are outside', () => { + const visible = visibility(point(0, 0, 30000), down, up); + const mount = point(0.3, 0); + const points = [ + mount, + point(0.1, 0.0001), + point(0.3, 0.0001), + point(0.3, -0.0001), + point(0.1, -0.0001), + ]; + assert.equal(visible(points), true); + assert.equal(visible([mount]), false); + assert.equal(visible([point(0.2, 0)]), false); +}); + +test('a nearby plane below the ellipsoid is visible to low and high viewers', () => { + const cap = point(0.00054, 0, -18); + const points = [point(0, 0, -18), cap]; + for (const altitude of [4, 1200]) { + const position = point(0.00135, 0, altitude); + const direction = directionTo(position, cap); + assertInFrustum(points, position, direction); + assert.equal(visibility(position, direction, up)(points), true); + } +}); + +test('the horizon rejects a negative-height plane on the far side', () => { + const mount = point(0, 0, -18); + const points = [mount, point(0.00054, 0, -18)]; + for (const altitude of [4, 30000, 2e7]) { + const position = point(180, 0, altitude); + const direction = directionTo(position, mount); + assertInFrustum(points, position, direction); + assert.equal(visibility(position, direction, up)(points), false); + } +}); + +test('a low viewer can see a plane beyond the WGS84 horizon', () => { + const mount = point(0, 0, 1); + const position = point(0.2, 0, 4); + assert.equal( + visibility(position, directionTo(position, mount), up)([mount]), + true, + ); +}); + +test('deep viewers do not lose nearby planes to the horizon test', () => { + const mount = point(0, 0, -350); + const position = point(0.00135, 0, -300); + assert.equal( + visibility(position, directionTo(position, mount), up)([mount]), + true, + ); +}); + +test('a non-finite camera direction leaves visibility unknown', () => { + const visible = visibility( + point(0, 0, 30000), + new Cesium.Cartesian3(NaN, 0, 0), + up, + ); + assert.equal(visible([point(0, 0)]), null); }); test('setFov holds the vertical angle across resizes, and waits for a first one', () => { diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index ba69cb1991..6a9329ab90 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -485,7 +485,7 @@ export function createCesiumPorts( : {}), }); const cameraPort = cameraPart.port; - if (controlled && capabilities.has('pointVisibility')) + if (capabilities.has('pointVisibility')) cameraPort.visiblePoints = createPointsVisibility(scene, camera); measureCameraChanged = cameraPart.measureChanged ?? null; const effectsPart = createCesiumEffects(scene, { diff --git a/src/render/contract/camera.d.ts b/src/render/contract/camera.d.ts index 8bf2705242..d1f12fd156 100644 --- a/src/render/contract/camera.d.ts +++ b/src/render/contract/camera.d.ts @@ -234,7 +234,14 @@ export type CameraEvent = 'changed' | 'moveStart' | 'moveEnd' | 'followChanged' | 'flightEnd'; export interface CameraPort { - /** Conservative visibility of an ECEF point set, with a horizon margin in metres; null means unknown. */ + /** + * Whether any of the ECEF points may be on screen: false only when their + * bounding sphere is outside the view or all of them are below the horizon + * of WGS84 shrunk by `horizonMarginM` metres; null when it cannot tell + * (not a 3D scene, an empty point set, or a non-finite point or camera + * vector), which callers treat as visible. Supply a finite, nonnegative + * margin smaller than the shortest WGS84 radius. + */ visiblePoints?(points: Ecef[], horizonMarginM: number): boolean | null; pose(): CameraPose; /** diff --git a/src/ui/cctvControls.js b/src/ui/cctvControls.js index 2d5ad447a6..11440f3a95 100644 --- a/src/ui/cctvControls.js +++ b/src/ui/cctvControls.js @@ -1,3 +1,5 @@ +import { watch } from 'vue'; +import { MOBILE_SHEET_ATTR } from './mobileSheets.js'; import { EMPTY_CCTV_FRAME, _clearCctvFrame, @@ -86,11 +88,14 @@ export class CctvControls { attributeFilter: ['class', 'hidden'], }); // On phones the panel is on screen only while the Cameras sheet is open. - if (typeof document !== 'undefined' && document.body) - this._videoVisibilityObserver.observe(document.body, { - attributes: true, - attributeFilter: ['class', 'data-mobile-sheet'], - }); + this._videoVisibilityObserver.observe(document.body, { + attributes: true, + attributeFilter: ['class', MOBILE_SHEET_ATTR], + }); + this._offPreviewCards = watch( + () => this.store.previewCards, + () => this._renderCctvState(this._cctvState), + ); this.listen(document, 'visibilitychange', () => this._renderCctvState(this._cctvState), ); @@ -163,6 +168,7 @@ export class CctvControls { this._quebecCctvOverlay?.dispose(); this._cctvVideoSurface?.stop(); this._videoVisibilityObserver?.disconnect(); + this._offPreviewCards?.(); this._actionGeneration++; this.listeners.abort(); this._cctvUnsubscribe?.(); diff --git a/src/ui/cctvPanel.test.mjs b/src/ui/cctvPanel.test.mjs index 7612eacc3d..dc082cb652 100644 --- a/src/ui/cctvPanel.test.mjs +++ b/src/ui/cctvPanel.test.mjs @@ -20,7 +20,7 @@ const BUTTONS = { _cctvProjectionBtn: 'cctv-projection-btn', }; -function panel(t) { +function panel(t, { video = false } = {}) { document.body.replaceChildren(); const host = document.body.appendChild(document.createElement('div')); const pinia = createPinia(); @@ -32,6 +32,7 @@ function panel(t) { document.getElementById(id), ]), ); + if (video) elements._cctvVideo = document.getElementById('cctv-video'); const controls = new CctvControls({ elements: { ...elements, @@ -377,16 +378,7 @@ test('a second edit of the same chip gets a fresh input', async (t) => { }); test('the frame preview renders each step of a camera frame request', async (t) => { - const prior = globalThis.Image; - const requests = []; - globalThis.Image = class { - constructor() { - requests.push(this); - } - }; - t.after(() => { - globalThis.Image = prior; - }); + const requests = mockImages(t); const { controls, byId } = panel(t); // The preview loads while the panel is open; the panel starts collapsed. byId('cctv-panel').classList.remove('collapsed'); @@ -610,15 +602,7 @@ test('the meta line of a disabled layer does not describe its last camera', () = }); const settle = () => new Promise((resolve) => setTimeout(resolve, 0)); -const stillState = (frameUrl) => ({ - enabled: true, - count: 1, - cameraIndex: [camera], - activeCameraId: 'a', - activeCamera: { ...camera, frameUrl, sourceKind: 'snapshot' }, -}); - -test('the still preview is fetched only while the tab and the panel are shown', async (t) => { +function mockImages(t) { const prior = globalThis.Image; const requests = []; globalThis.Image = class { @@ -626,6 +610,22 @@ test('the still preview is fetched only while the tab and the panel are shown', requests.push(this); } }; + t.after(() => { + globalThis.Image = prior; + }); + return requests; +} + +const stillState = (frameUrl, id = 'a') => ({ + enabled: true, + count: 2, + cameraIndex: [camera, { ...camera, id: 'b' }], + activeCameraId: id, + activeCamera: { ...camera, id, frameUrl, sourceKind: 'snapshot' }, +}); + +test('the still preview is fetched only while the tab and the panel are shown', async (t) => { + const requests = mockImages(t); const hidden = Object.getOwnPropertyDescriptor(document, 'hidden'); let tabHidden = false; Object.defineProperty(document, 'hidden', { @@ -633,11 +633,11 @@ test('the still preview is fetched only while the tab and the panel are shown', get: () => tabHidden, }); t.after(() => { - globalThis.Image = prior; if (hidden) Object.defineProperty(document, 'hidden', hidden); else delete document.hidden; }); const { controls, byId } = panel(t); + assert.equal(controls._cctvVideo, undefined); const panelElement = byId('cctv-panel'); const state = stillState; @@ -668,15 +668,8 @@ test('the still preview is fetched only while the tab and the panel are shown', }); test('the still preview waits for the Cameras sheet on phones', async (t) => { - const prior = globalThis.Image; - const requests = []; - globalThis.Image = class { - constructor() { - requests.push(this); - } - }; + const requests = mockImages(t); t.after(() => { - globalThis.Image = prior; document.body.classList.remove('mobile-shell'); document.body.removeAttribute('data-mobile-sheet'); }); @@ -704,22 +697,53 @@ test('the still preview waits for the Cameras sheet on phones', async (t) => { assert.equal(requests.length, 2, 'desktop ignores the sheet'); }); -test('a still-only panel (no video element) resumes from the class change', async (t) => { - const prior = globalThis.Image; - const requests = []; - globalThis.Image = class { - constructor() { - requests.push(this); - } - }; - t.after(() => { - globalThis.Image = prior; - }); +test('a camera picked while the panel is collapsed shows its own still on expanding', async (t) => { + const requests = mockImages(t); const { controls, byId } = panel(t); - assert.equal(controls._cctvVideo, undefined); + const panelElement = byId('cctv-panel'); + panelElement.classList.remove('collapsed'); controls._renderCctvState(stillState('a1.jpg')); - assert.equal(requests.length, 0); - byId('cctv-panel').classList.remove('collapsed'); - await settle(); assert.equal(requests.length, 1); + assert.equal(requests[0].src, 'a1.jpg'); + panelElement.classList.add('collapsed'); + await settle(); + controls._renderCctvState(stillState('b1.jpg', 'b')); + assert.equal(requests.length, 1); + requests[0].onload(); + panelElement.classList.remove('collapsed'); + await settle(); + await nextTick(); + assert.equal(requests.length, 2); + assert.equal(requests[1].src, 'b1.jpg'); + assert.equal(byId('cctv-frame').dataset.cameraId, 'b'); + assert.notEqual(byId('cctv-frame').getAttribute('src'), 'a1.jpg'); +}); + +test('leaving the Cameras sheet stops the live video and coming back starts it again', async (t) => { + const { controls, byId } = panel(t, { video: true }); + byId('cctv-panel').classList.remove('collapsed'); + document.body.classList.add('mobile-shell'); + document.body.setAttribute('data-mobile-sheet', 'cameras'); + t.after(() => { + document.body.classList.remove('mobile-shell'); + document.body.removeAttribute('data-mobile-sheet'); + }); + controls._renderCctvState({ + enabled: true, + count: 1, + cameraIndex: [camera], + activeCameraId: 'a', + activeCamera: { ...camera, isVideo: true }, + }); + const first = controls._cctvVideoSurface; + assert.ok(first); + const stop = t.mock.method(first, 'stop'); + document.body.setAttribute('data-mobile-sheet', 'layers'); + await settle(); + assert.equal(stop.mock.callCount(), 1); + assert.equal(controls._cctvVideoSurface, null); + document.body.setAttribute('data-mobile-sheet', 'cameras'); + await settle(); + assert.ok(controls._cctvVideoSurface); + assert.notEqual(controls._cctvVideoSurface, first); }); diff --git a/src/ui/cctvPresentation.js b/src/ui/cctvPresentation.js index 7e4b576f62..2c637465e3 100644 --- a/src/ui/cctvPresentation.js +++ b/src/ui/cctvPresentation.js @@ -4,6 +4,15 @@ import { cctvSourceLabelText, cctvSourceMessageText } from './cctvFrames.js'; import { createCctvVideoSurface } from './cctvVideo.js'; import { presentCctvCalibration } from './cctvCalibration.js'; import { roundHeadingDegrees } from '../data/headingDegrees.js'; +import { + MOBILE_SHELL_CLASS, + MOBILE_SHEET_ATTR, + sheetForPanelId, +} from './mobileSheets.js'; + +const CAMERAS_SHEET = sheetForPanelId('cctv-panel'); +const CONTEXT_SHEET = sheetForPanelId('global-context-panel'); + export function _calBadgeLabel(badge) { switch (badge) { case 'calibrated': @@ -274,19 +283,21 @@ export function _renderCctvState(state) { const liveIntent = enabled && !!activeCamera?.isVideo && !activeCamera?.browserMediaUrl; this.store.setLive(liveIntent); - // A background tab or a collapsed panel shows nothing, so neither plays the - // video nor fetches the still; the observer and the visibilitychange listener - // render again when the panel is shown. - // On phones the panel also belongs to one sheet: the shell hides it unless - // data-mobile-sheet is 'cameras'. - const body = typeof document !== 'undefined' ? document.body : null; - const sheetClosed = - !!body?.classList?.contains('mobile-shell') && - body.getAttribute('data-mobile-sheet') !== 'cameras'; + // A background tab, a collapsed panel or a closed phone sheet shows no + // picture; the observers and visibilitychange render again on showing. + const body = globalThis.document?.body; + const phone = body?.classList.contains(MOBILE_SHELL_CLASS); + const sheet = body?.getAttribute(MOBILE_SHEET_ATTR); + const tabShown = !!body && !document.hidden; const panelShown = - !(typeof document !== 'undefined' && document.hidden) && - !this._cctvPanel?.classList?.contains('collapsed') && - !sheetClosed; + tabShown && + !this._cctvPanel?.classList.contains('collapsed') && + (!phone || sheet === CAMERAS_SHEET); + // Context's camera card shows the same still. + const cardShown = + tabShown && + this.store.previewCards > 0 && + (!phone || sheet === CONTEXT_SHEET); if (this._cctvVideo) { const visible = liveIntent && panelShown; if (!visible || this._cctvVideoCameraId !== activeId) { @@ -313,7 +324,7 @@ export function _renderCctvState(state) { // immediate so navigation never waits on the prior camera's request. if ( nextSrc && - panelShown && + (panelShown || cardShown) && (cameraChanged || (!frameLoading && this._frame.currentSrc !== nextSrc)) ) { this._queueCctvFrame(nextSrc, nextCameraId, cameraChanged); diff --git a/src/ui/contextCardFrame.test.mjs b/src/ui/contextCardFrame.test.mjs new file mode 100644 index 0000000000..475f65f53a --- /dev/null +++ b/src/ui/contextCardFrame.test.mjs @@ -0,0 +1,167 @@ +import '../testSupport/registerDom.mjs'; +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { createPinia } from 'pinia'; +import { createApp, nextTick } from 'vue'; +import { CctvControls } from './cctvControls.js'; +import { useCctvStore } from './stores/cctv.js'; +import CctvPanel from './views/panels/CctvPanel.vue'; +import CctvPreview from './views/panels/CctvPreview.vue'; + +const settle = () => new Promise((r) => setTimeout(r, 0)); +const camera = { + id: 'a', + city: 'Austin', + name: 'Congress Ave', + headingDeg: 91.6, + fovDeg: 60, + rangeM: 120.4, + sourceLabel: 'Configured Source', + calBadge: 'curated', +}; +const stillState = (frameUrl, id = 'a') => ({ + enabled: true, + count: 2, + cameraIndex: [camera, { ...camera, id: 'b' }], + activeCameraId: id, + activeCamera: { ...camera, id, frameUrl, sourceKind: 'snapshot' }, +}); + +function fixture(t, { card = true } = {}) { + document.body.replaceChildren(); + const host = document.body.appendChild(document.createElement('div')); + const cardHost = document.body.appendChild(document.createElement('div')); + const pinia = createPinia(); + const app = createApp(CctvPanel).use(pinia); + app.mount(host); + let preview; + function mountCard() { + preview = createApp(CctvPreview, { cameraId: 'a' }).use(pinia); + preview.mount(cardHost); + } + if (card) mountCard(); + const controls = new CctvControls({ + elements: { + _cctvPanel: document.getElementById('cctv-panel'), + _cctvFrame: document.getElementById('cctv-frame'), + _cctvFrameWrap: document.getElementById('cctv-frame-wrap'), + }, + cctv: {}, + actions: { + isEnabled: () => true, + setPanelCollapsed() {}, + syncViewport() {}, + }, + store: useCctvStore(pinia), + }); + t.after(() => { + controls.destroy(); + app.unmount(); + preview?.unmount(); + }); + return { + controls, + cardHost, + mountCard, + panelEl: document.getElementById('cctv-panel'), + }; +} + +function mockImages(t) { + const prior = globalThis.Image; + const requests = []; + globalThis.Image = class { + constructor() { + requests.push(this); + } + }; + t.after(() => { + globalThis.Image = prior; + }); + return requests; +} + +test('desktop: the Context card keeps refreshing while the accordion folds CCTV', async (t) => { + const requests = mockImages(t); + const { controls, cardHost, panelEl } = fixture(t); + panelEl.classList.remove('collapsed'); + controls._renderCctvState(stillState('a1.jpg')); + assert.equal(requests.length, 1); + requests[0].onload(); + await settle(); + await nextTick(); + assert.equal(cardHost.querySelector('img')?.getAttribute('src'), 'a1.jpg'); + // Context opens: the desktop accordion folds CCTV (class collapsed). + panelEl.classList.add('collapsed'); + await settle(); + controls._renderCctvState(stillState('a2.jpg')); + assert.equal(requests.length, 2); + assert.equal(requests[1].src, 'a2.jpg'); + requests[1].onload(); + controls._renderCctvState(stillState('a3.jpg')); + assert.equal(requests.length, 3); + assert.equal(requests[2].src, 'a3.jpg'); + requests[2].onload(); + await settle(); + await nextTick(); + assert.equal(cardHost.querySelector('img')?.getAttribute('src'), 'a3.jpg'); +}); + +test('phone: a camera picked with the Context sheet open gets its still', async (t) => { + const requests = mockImages(t); + t.after(() => { + document.body.classList.remove('mobile-shell'); + document.body.removeAttribute('data-mobile-sheet'); + }); + const { controls, cardHost, panelEl } = fixture(t); + document.body.classList.add('mobile-shell'); + document.body.setAttribute('data-mobile-sheet', 'context'); + panelEl.classList.remove('collapsed'); + controls._renderCctvState(stillState('a1.jpg')); + controls._renderCctvState(stillState('a2.jpg')); + await settle(); + await nextTick(); + assert.ok( + requests.length >= 1, + 'the Context card on the Context sheet requests the still', + ); + requests.at(-1).onload(); + await settle(); + await nextTick(); + assert.ok( + cardHost.querySelector('.cctv-preview__expand'), + 'the card shows a frame, not Acquiring frame…', + ); +}); + +test('phone: the card on a closed Context sheet waits', async (t) => { + const requests = mockImages(t); + const { controls, panelEl } = fixture(t); + panelEl.classList.add('collapsed'); + document.body.classList.add('mobile-shell'); + document.body.setAttribute('data-mobile-sheet', 'layers'); + t.after(() => { + document.body.classList.remove('mobile-shell'); + document.body.removeAttribute('data-mobile-sheet'); + }); + controls._renderCctvState(stillState('a1.jpg')); + assert.equal(requests.length, 0); + document.body.setAttribute('data-mobile-sheet', 'context'); + await settle(); + assert.equal(requests.length, 1); + assert.equal(requests[0].src, 'a1.jpg'); +}); + +test('desktop: a card that mounts asks for the still', async (t) => { + const requests = mockImages(t); + const { controls, panelEl, mountCard } = fixture(t, { card: false }); + panelEl.classList.add('collapsed'); + controls._renderCctvState(stillState('a1.jpg')); + await settle(); + assert.equal(requests.length, 0); + mountCard(); + await settle(); + await nextTick(); + assert.equal(requests.length, 1); + assert.equal(requests[0].src, 'a1.jpg'); +}); diff --git a/src/ui/mobileSheets.js b/src/ui/mobileSheets.js new file mode 100644 index 0000000000..3187d15cc1 --- /dev/null +++ b/src/ui/mobileSheets.js @@ -0,0 +1,25 @@ +export const MOBILE_SHELL_CLASS = 'mobile-shell'; +export const MOBILE_SHEET_ATTR = 'data-mobile-sheet'; + +/** + * Panels each sheet expands. A sheet also shows its rail's other panels + * collapsed (Scenes under Layers), per styles/mobile-shell.css. + */ +export const MOBILE_SHEET_PANELS = Object.freeze({ + layers: Object.freeze(['data-panel']), + cameras: Object.freeze(['cctv-panel', 'street-level-panel']), + context: Object.freeze(['global-context-panel']), + search: Object.freeze(['location-bar']), + more: Object.freeze(['control-panel', 'pp-toggles']), +}); + +/** + * @param {string} panelId + * @returns {string|null} The sheet that presents `panelId`. + */ +export function sheetForPanelId(panelId) { + for (const [sheet, ids] of Object.entries(MOBILE_SHEET_PANELS)) { + if (ids.includes(panelId)) return sheet; + } + return null; +} diff --git a/src/ui/mobileShell.js b/src/ui/mobileShell.js index 7570e2d170..861add6ba2 100644 --- a/src/ui/mobileShell.js +++ b/src/ui/mobileShell.js @@ -18,22 +18,20 @@ import { readPanelState, } from './rail/panelState.js'; +import { + MOBILE_SHELL_CLASS, + MOBILE_SHEET_ATTR, + MOBILE_SHEET_PANELS, +} from './mobileSheets.js'; + +export { + MOBILE_SHELL_CLASS, + MOBILE_SHEET_ATTR, + MOBILE_SHEET_PANELS, + sheetForPanelId, +} from './mobileSheets.js'; + export const MOBILE_SHELL_MEDIA_QUERY = '(max-width: 720px)'; -export const MOBILE_SHELL_CLASS = 'mobile-shell'; -export const MOBILE_SHEET_ATTR = 'data-mobile-sheet'; - -/** - * Panels each sheet expands. A sheet also shows its rail's other panels - * collapsed (Scenes under Layers), per styles/mobile-shell.css. - */ -export const MOBILE_SHEET_PANELS = Object.freeze({ - layers: Object.freeze(['data-panel']), - cameras: Object.freeze(['cctv-panel', 'street-level-panel']), - context: Object.freeze(['global-context-panel']), - search: Object.freeze(['location-bar']), - more: Object.freeze(['control-panel', 'pp-toggles']), -}); - export const MOBILE_TABS = Object.freeze([ Object.freeze({ sheet: 'layers', label: msg('Layers'), icon: 'layers' }), Object.freeze({ sheet: 'cameras', label: msg('Cameras'), icon: 'videocam' }), @@ -58,17 +56,6 @@ const BORROWED_PANELS = Object.freeze([ const BORROW_OPTIONS = Object.freeze({ persist: false, syncShare: false }); -/** - * @param {string} panelId - * @returns {string|null} The sheet that presents `panelId`. - */ -export function sheetForPanelId(panelId) { - for (const [sheet, ids] of Object.entries(MOBILE_SHEET_PANELS)) { - if (ids.includes(panelId)) return sheet; - } - return null; -} - /** * The sheet after a tab press: the same tab closes its sheet, another opens. * @param {string|null} current diff --git a/src/ui/stores/cctv.js b/src/ui/stores/cctv.js index eaea1d6780..b0a6cfdb59 100644 --- a/src/ui/stores/cctv.js +++ b/src/ui/stores/cctv.js @@ -20,6 +20,8 @@ export const useCctvStore = defineStore('gev-cctv', () => { /** The preview: requested and shown frame, loading and error state. */ const frame = shallowRef(null); + /** Number of camera cards outside the panel showing its preview, including Context's card. */ + const previewCards = shallowRef(0); /** Whether the live video surface replaces the still frame. */ const live = shallowRef(false); /** `{label, state}` for the source badge; null until first synced. */ @@ -49,6 +51,11 @@ export const useCctvStore = defineStore('gev-cctv', () => { frame.value = markRaw(next); } + /** @param {boolean} shown */ + function showPreviewCard(shown) { + previewCards.value = Math.max(0, previewCards.value + (shown ? 1 : -1)); + } + /** @param {boolean} on */ function setLive(on) { live.value = Boolean(on); @@ -73,6 +80,7 @@ export const useCctvStore = defineStore('gev-cctv', () => { view, calEdit, frame, + previewCards, live, sourceBadge, summary, @@ -80,6 +88,7 @@ export const useCctvStore = defineStore('gev-cctv', () => { publish, setCalEdit, setFrame, + showPreviewCard, setLive, setSourceBadge, setSummary, diff --git a/src/ui/views/panels/CctvPreview.vue b/src/ui/views/panels/CctvPreview.vue index f5aae41cf2..15a4fa5f7d 100644 --- a/src/ui/views/panels/CctvPreview.vue +++ b/src/ui/views/panels/CctvPreview.vue @@ -1,5 +1,5 @@