From c0752784d239c9fa5294075b14a477cb9b9066b7 Mon Sep 17 00:00:00 2001 From: brandonabyrd Date: Wed, 18 Nov 2026 15:19:38 -0600 Subject: [PATCH] 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