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.
This commit is contained in:
Sameh Khamis committed 2026-11-07 04:13:56 -08:00
1 parent 9fe3e7633f
commit f509c688e8
4 files changed
+124 -39

No files matched your search

+55 -38
View File
@@ -1,7 +1,9 @@
import { isUnavailableCapability } from '../sources/capability.js'; import { isUnavailableCapability } from '../sources/capability.js';
import { defaultGeospatial } from '../search/defaults.js'; import { defaultGeospatial } from '../search/defaults.js';
import * as Cesium from 'cesium'; import { cameraOf, findCamera, findQuery } from '../render/rendererOf.js';
import { cameraOf } from '../render/cesium/camera.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 { greatCircleMeters } from '../geoDistance.js';
import { import {
holdContinuousRender, holdContinuousRender,
@@ -21,11 +23,6 @@ import {
} from '../sources/phaseTiming.js'; } from '../sources/phaseTiming.js';
import { formatDistanceText } from '../data/distanceFormat.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. * Annotation engine — the voice agent's "whiteboard" over the 3D world.
* *
@@ -1697,17 +1694,15 @@ export function createAnnotationEngine({
frameAnnotation(marks[0]); frameAnnotation(marks[0]);
return; return;
} }
const cart = points.map((p) => const cart = points.map((p) => fromDegrees(p.lon, p.lat, p.height || 0));
Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height || 0), const sphere = sphereFromPoints(cart);
);
const sphere = Cesium.BoundingSphere.fromPoints(cart);
const camera = cameraOf(viewer); const camera = cameraOf(viewer);
camera.flyToBounds( camera.flyToBounds(
{ center: sphere.center, radius: sphere.radius }, { center: sphere.center, radius: sphere.radius },
{ {
offset: { offset: {
heading: camera.pose().heading, heading: camera.pose().heading,
pitch: Cesium.Math.toRadians(-35), pitch: toRadians(-35),
range: Math.max(900, sphere.radius * 2.6), range: Math.max(900, sphere.radius * 2.6),
}, },
durationS: 1.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. */ * globe. On any API hiccup, report visible — bad data must never move the camera. */
function isPointOnScreen(p) { function isPointOnScreen(p) {
try { try {
const camera = viewer.camera; const camera = findCamera(viewer);
const pos = Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height || 0); const query = findQuery(viewer);
const cv = camera.frustum.computeCullingVolume( if (!camera || !query) return true;
camera.position, const pos = fromDegrees(p.lon, p.lat, p.height || 0);
camera.direction, // Inside the view frustum: a 1 m sphere at the point is not wholly
camera.up, // outside any of its six planes, read off the view-projection (depth
); // runs -1..1). An invalid matrix measures no distance and reads as
if ( // visible.
cv.computeVisibility(new Cesium.BoundingSphere(pos, 1)) === const { view, projection } = camera.matrices();
Cesium.Intersect.OUTSIDE const m = new Float64Array(16);
) for (let col = 0; col < 4; col++)
return false; for (let row = 0; row < 4; row++) {
const occluder = new Cesium.EllipsoidalOccluder( let sum = 0;
Cesium.Ellipsoid.WGS84, for (let k = 0; k < 4; k++)
camera.position, sum += projection[k * 4 + row] * view[col * 4 + k];
); m[col * 4 + row] = sum;
return occluder.isPointVisible(pos); }
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 { } catch {
return true; return true;
} }
@@ -1775,7 +1782,7 @@ export function createAnnotationEngine({
{ {
offset: { offset: {
heading: camera.pose().heading, heading: camera.pose().heading,
pitch: Cesium.Math.toRadians(-35), pitch: toRadians(-35),
range: range * 2.4, range: range * 2.4,
}, },
durationS: 1.8, durationS: 1.8,
@@ -1988,8 +1995,8 @@ export function createAnnotationEngine({
{ lon, lat, height }, { lon, lat, height },
{ {
orientation: { orientation: {
heading: Cesium.Math.toRadians(heading), heading: toRadians(heading),
pitch: Cesium.Math.toRadians(pitch), pitch: toRadians(pitch),
roll: 0, roll: 0,
}, },
durationS: duration, durationS: duration,
@@ -2156,13 +2163,23 @@ function pendingAnimation(anno, now) {
// fly_to_location natural-region heuristic uses (owner field test 2026-07-23). // fly_to_location natural-region heuristic uses (owner field test 2026-07-23).
const VIEWPORT_ASSIST_RANGE_CAP_M = 120000; 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. */ /** flyTo range from a Places viewport box (low/high lat-lng corners), or null. */
function viewportRange(vp) { function viewportRange(vp) {
if (!vp?.low || !vp?.high) return null; if (!vp?.low || !vp?.high) return null;
try { try {
const span = Cesium.Cartesian3.distance( const span = distance(
Cesium.Cartesian3.fromDegrees(vp.low.longitude, vp.low.latitude), fromDegrees(vp.low.longitude, vp.low.latitude),
Cesium.Cartesian3.fromDegrees(vp.high.longitude, vp.high.latitude), fromDegrees(vp.high.longitude, vp.high.latitude),
); );
return Number.isFinite(span) && span > 0 return Number.isFinite(span) && span > 0
? Math.max(300, Math.min(span * 0.7, VIEWPORT_ASSIST_RANGE_CAP_M)) ? 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 < minLon) minLon = lon;
if (lon > maxLon) maxLon = lon; if (lon > maxLon) maxLon = lon;
} }
const span = Cesium.Cartesian3.distance( const span = distance(
Cesium.Cartesian3.fromDegrees(minLon, minLat), fromDegrees(minLon, minLat),
Cesium.Cartesian3.fromDegrees(maxLon, maxLat), fromDegrees(maxLon, maxLat),
); );
return Math.max(300, span * 0.7); return Math.max(300, span * 0.7);
} }
+64
View File
@@ -1690,3 +1690,67 @@ test('plain recaption keeps the old mark addressable when its removal throws', a
); );
assert.equal(engine.count(), 0); 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');
});
+5
View File
@@ -2,6 +2,11 @@ import * as Cesium from 'cesium';
import { applyModelAtmosphereWorkaround } from './atmosphereCompat.js'; import { applyModelAtmosphereWorkaround } from './atmosphereCompat.js';
import { StarrySky } from '../sky/starrySky.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. */ /** Cesium.Viewer options of the standard globe viewer. */
export function applicationViewerOptions(creditContainer) { export function applicationViewerOptions(creditContainer) {
return { return {
-1
View File
@@ -1,6 +1,5 @@
[ [
"dev/conformance/main.js", "dev/conformance/main.js",
"src/annotations/annotationEngine.js",
"src/annotations/drawTool.js", "src/annotations/drawTool.js",
"src/annotations/worldAnnotationRenderer.js", "src/annotations/worldAnnotationRenderer.js",
"src/app/embed.js", "src/app/embed.js",