perf(cctv): fetch the active camera's pictures only while they can be seen

This commit is contained in:
Byrd-IT authored and brandonabyrd committed 2026-11-18 17:13:06 -06:00
1 parent 6e0baacd57
commit 3bda877a8a
5 files changed
+282 -4

No files matched your search

+53
View File
@@ -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,
};
+154
View File
@@ -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);
});