From f509c688e8d8089e9fc640e327c4352afc0f2592 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 7 Nov 2026 03:54:06 -0800 Subject: [PATCH] Check annotation visibility and frame marks through the renderer's ports The annotation engine no longer imports Cesium. The camera assist tests whether a fresh mark is in view against the frustum planes of the camera port's view-projection, with the same one-metre sphere Cesium's culling volume used, and asks the query port whether it is behind the globe. The view-projection is in world coordinates, so the test now also holds when the camera has a reference frame of its own. Framing uses the camera port and the geo helpers for spheres, angles and distances. It leaves the Cesium allow-list. The window.__CESIUM__ dev hook the QA scripts read moves to the application viewer module, which every app boot loads before the viewer is made. A new test covers the assist: marks in view, off the frustum, behind the globe, and a camera that cannot answer. --- src/annotations/annotationEngine.js | 93 ++++++++++++++--------- src/annotations/annotationEngine.test.mjs | 64 ++++++++++++++++ src/app/viewer.js | 5 ++ src/render/cesiumAllowList.json | 1 - 4 files changed, 124 insertions(+), 39 deletions(-) diff --git a/src/annotations/annotationEngine.js b/src/annotations/annotationEngine.js index 6c2d72ca5..d9b29ea0c 100644 --- a/src/annotations/annotationEngine.js +++ b/src/annotations/annotationEngine.js @@ -1,7 +1,9 @@ import { isUnavailableCapability } from '../sources/capability.js'; import { defaultGeospatial } from '../search/defaults.js'; -import * as Cesium from 'cesium'; -import { cameraOf } from '../render/cesium/camera.js'; +import { cameraOf, findCamera, findQuery } from '../render/rendererOf.js'; +import { fromDegrees } from '../geo/ellipsoid.js'; +import { sphereFromPoints } from '../geo/sphere.js'; +import { distance, toRadians } from '../geo/vector.js'; import { greatCircleMeters } from '../geoDistance.js'; import { holdContinuousRender, @@ -21,11 +23,6 @@ import { } from '../sources/phaseTiming.js'; import { formatDistanceText } from '../data/distanceFormat.js'; -// Dev convenience: expose the app's Cesium instance for console/preview probing -// (single shared module instance — avoids dual-Cesium state bugs when testing). -if (typeof window !== 'undefined' && !window.__CESIUM__) - window.__CESIUM__ = Cesium; - /** * Annotation engine — the voice agent's "whiteboard" over the 3D world. * @@ -1697,17 +1694,15 @@ export function createAnnotationEngine({ frameAnnotation(marks[0]); return; } - const cart = points.map((p) => - Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height || 0), - ); - const sphere = Cesium.BoundingSphere.fromPoints(cart); + const cart = points.map((p) => fromDegrees(p.lon, p.lat, p.height || 0)); + const sphere = sphereFromPoints(cart); const camera = cameraOf(viewer); camera.flyToBounds( { center: sphere.center, radius: sphere.radius }, { offset: { heading: camera.pose().heading, - pitch: Cesium.Math.toRadians(-35), + pitch: toRadians(-35), range: Math.max(900, sphere.radius * 2.6), }, durationS: 1.6, @@ -1722,23 +1717,35 @@ export function createAnnotationEngine({ * globe. On any API hiccup, report visible — bad data must never move the camera. */ function isPointOnScreen(p) { try { - const camera = viewer.camera; - const pos = Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height || 0); - const cv = camera.frustum.computeCullingVolume( - camera.position, - camera.direction, - camera.up, - ); - if ( - cv.computeVisibility(new Cesium.BoundingSphere(pos, 1)) === - Cesium.Intersect.OUTSIDE - ) - return false; - const occluder = new Cesium.EllipsoidalOccluder( - Cesium.Ellipsoid.WGS84, - camera.position, - ); - return occluder.isPointVisible(pos); + const camera = findCamera(viewer); + const query = findQuery(viewer); + if (!camera || !query) return true; + const pos = fromDegrees(p.lon, p.lat, p.height || 0); + // Inside the view frustum: a 1 m sphere at the point is not wholly + // outside any of its six planes, read off the view-projection (depth + // runs -1..1). An invalid matrix measures no distance and reads as + // visible. + const { view, projection } = camera.matrices(); + const m = new Float64Array(16); + for (let col = 0; col < 4; col++) + for (let row = 0; row < 4; row++) { + let sum = 0; + for (let k = 0; k < 4; k++) + sum += projection[k * 4 + row] * view[col * 4 + k]; + m[col * 4 + row] = sum; + } + const at = (row, col) => m[col * 4 + row]; + for (const [axis, sign] of FRUSTUM_PLANES) { + const a = at(3, 0) + sign * at(axis, 0); + const b = at(3, 1) + sign * at(axis, 1); + const c = at(3, 2) + sign * at(axis, 2); + const d = at(3, 3) + sign * at(axis, 3); + const distanceM = + (a * pos.x + b * pos.y + c * pos.z + d) / Math.hypot(a, b, c); + if (distanceM < -1) return false; + } + // On the near side of the globe. + return !query.isOccluded(pos); } catch { return true; } @@ -1775,7 +1782,7 @@ export function createAnnotationEngine({ { offset: { heading: camera.pose().heading, - pitch: Cesium.Math.toRadians(-35), + pitch: toRadians(-35), range: range * 2.4, }, durationS: 1.8, @@ -1988,8 +1995,8 @@ export function createAnnotationEngine({ { lon, lat, height }, { orientation: { - heading: Cesium.Math.toRadians(heading), - pitch: Cesium.Math.toRadians(pitch), + heading: toRadians(heading), + pitch: toRadians(pitch), roll: 0, }, durationS: duration, @@ -2156,13 +2163,23 @@ function pendingAnimation(anno, now) { // fly_to_location natural-region heuristic uses (owner field test 2026-07-23). const VIEWPORT_ASSIST_RANGE_CAP_M = 120000; +/** The view frustum's planes as `row 3 ± row axis` of the view-projection. */ +const FRUSTUM_PLANES = [ + [0, 1], + [0, -1], + [1, 1], + [1, -1], + [2, 1], + [2, -1], +]; + /** flyTo range from a Places viewport box (low/high lat-lng corners), or null. */ function viewportRange(vp) { if (!vp?.low || !vp?.high) return null; try { - const span = Cesium.Cartesian3.distance( - Cesium.Cartesian3.fromDegrees(vp.low.longitude, vp.low.latitude), - Cesium.Cartesian3.fromDegrees(vp.high.longitude, vp.high.latitude), + const span = distance( + fromDegrees(vp.low.longitude, vp.low.latitude), + fromDegrees(vp.high.longitude, vp.high.latitude), ); return Number.isFinite(span) && span > 0 ? Math.max(300, Math.min(span * 0.7, VIEWPORT_ASSIST_RANGE_CAP_M)) @@ -2187,9 +2204,9 @@ function ringRange(ring) { if (lon < minLon) minLon = lon; if (lon > maxLon) maxLon = lon; } - const span = Cesium.Cartesian3.distance( - Cesium.Cartesian3.fromDegrees(minLon, minLat), - Cesium.Cartesian3.fromDegrees(maxLon, maxLat), + const span = distance( + fromDegrees(minLon, minLat), + fromDegrees(maxLon, maxLat), ); return Math.max(300, span * 0.7); } diff --git a/src/annotations/annotationEngine.test.mjs b/src/annotations/annotationEngine.test.mjs index faf66d912..78a9dc660 100644 --- a/src/annotations/annotationEngine.test.mjs +++ b/src/annotations/annotationEngine.test.mjs @@ -1690,3 +1690,67 @@ test('plain recaption keeps the old mark addressable when its removal throws', a ); assert.equal(engine.count(), 0); }); + +// The camera assist frames a fresh mark only when none of it is in view: +// off the frustum or behind the globe, as the renderer's camera and query +// ports see it. A camera that cannot answer leaves the view alone. +test('camera assist frames marks out of view and leaves visible ones alone', async (t) => { + installAnimationFrameStubs(t); + const { bindRenderer } = await import('../render/rendererOf.js'); + const { horizonFrom } = await import('../geo/horizon.js'); + const viewerOver = (lon, lat, height, { broken = false } = {}) => { + const position = Cesium.Cartesian3.fromDegrees(lon, lat, height); + const direction = Cesium.Cartesian3.negate( + Cesium.Cartesian3.normalize(position, new Cesium.Cartesian3()), + new Cesium.Cartesian3(), + ); + const right = Cesium.Cartesian3.normalize( + Cesium.Cartesian3.cross(direction, Cesium.Cartesian3.UNIT_Z, new Cesium.Cartesian3()), + new Cesium.Cartesian3(), + ); + const up = Cesium.Cartesian3.cross(right, direction, new Cesium.Cartesian3()); + const view = Cesium.Matrix4.computeView(position, direction, up, right, new Cesium.Matrix4()); + const frustum = new Cesium.PerspectiveFrustum({ + fov: Cesium.Math.toRadians(60), aspectRatio: 16 / 9, near: 1, far: 5e7, + }); + const flights = []; + const viewer = {}; + const horizon = horizonFrom(position); + bindRenderer(viewer, { + camera: { + pose: () => ({ heading: 0 }), + matrices() { + if (broken) throw new Error('no camera'); + return { + view: Float64Array.from(Cesium.Matrix4.toArray(view)), + projection: Float64Array.from(Cesium.Matrix4.toArray(frustum.projectionMatrix)), + }; + }, + flyTo: (...args) => flights.push(['flyTo', ...args]), + flyToBounds: (...args) => flights.push(['flyToBounds', ...args]), + }, + query: { isOccluded: (p) => !horizon.isPointVisible(p) }, + }); + return { viewer, flights }; + }; + const pinAt = async (viewer, lon, lat) => { + const engine = createAnnotationEngine({ viewer, renderer: fakeRenderer().renderer }); + await engine.annotate([{ type: 'pin', manual: true, latitude: lat, longitude: lon }], { persist: true, flyTo: false }); + }; + + const inView = viewerOver(-97.74, 30.27, 9000); + await pinAt(inView.viewer, -97.742, 30.268); + assert.equal(inView.flights.length, 0, 'a mark in view is left alone'); + + const aside = viewerOver(-97.74, 30.27, 9000); + await pinAt(aside.viewer, -97.5, 30.6); + assert.equal(aside.flights.length, 1, 'a mark off the frustum is framed'); + + const behind = viewerOver(60, 30, 9_000_000); + await pinAt(behind.viewer, -120, -30); + assert.equal(behind.flights.length, 1, 'a mark behind the globe is framed'); + + const broken = viewerOver(-97.74, 30.27, 9000, { broken: true }); + await pinAt(broken.viewer, -97.5, 30.6); + assert.equal(broken.flights.length, 0, 'a camera that cannot answer moves nothing'); +}); diff --git a/src/app/viewer.js b/src/app/viewer.js index 9bc72b7f4..550363ddd 100644 --- a/src/app/viewer.js +++ b/src/app/viewer.js @@ -2,6 +2,11 @@ import * as Cesium from 'cesium'; import { applyModelAtmosphereWorkaround } from './atmosphereCompat.js'; import { StarrySky } from '../sky/starrySky.js'; +// Dev convenience: expose the app's Cesium instance for console/preview probing +// (single shared module instance — avoids dual-Cesium state bugs when testing). +if (typeof window !== 'undefined' && !window.__CESIUM__) + window.__CESIUM__ = Cesium; + /** Cesium.Viewer options of the standard globe viewer. */ export function applicationViewerOptions(creditContainer) { return { diff --git a/src/render/cesiumAllowList.json b/src/render/cesiumAllowList.json index ddb3a2546..2194a66ce 100644 --- a/src/render/cesiumAllowList.json +++ b/src/render/cesiumAllowList.json @@ -1,6 +1,5 @@ [ "dev/conformance/main.js", - "src/annotations/annotationEngine.js", "src/annotations/drawTool.js", "src/annotations/worldAnnotationRenderer.js", "src/app/embed.js",