fix(cctv): cull frames through renderer camera port

This commit is contained in:
brandonabyrd committed 2026-11-18 17:13:06 -06:00
1 parent 147d1f5e4e
commit c0752784d2
6 files changed
+143 -36

No files matched your search

+1
View File
@@ -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",
+41 -35
View File
@@ -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);
}
/**
+79 -1
View File
@@ -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);
+3
View File
@@ -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) {
+17
View File
@@ -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();
+2
View File
@@ -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