From fdf7ed93ce117d2d7d025426d83d07c6f3e02bb2 Mon Sep 17 00:00:00 2001 From: German Khokhlov Date: Fri, 20 Nov 2026 03:39:09 +0400 Subject: [PATCH] fix(annotations): sample arrow, route and area points outside the view (#1277) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A point of an arrow, route or area outside the view frustum was not sampled and stood in at 0 m, so a partly visible arrow could hide, point at the wrong place or vanish behind the eye. Such points are sampled again within the 32-sample budget and the one-second retry, as on main; lone points outside the view still skip sampling. The 0 m stand-in exceptions are removed. Also from review: shared viewPlanes for transit and the renderer, a −430..9000 m segment test against the view planes, tighter tests and shorter docs. --- changelog.d/1277-annotation-issue-fix.md | 10 +- docs/CURRENT-STATE.md | 18 +- src/annotations/screenAnnotationRenderer.js | 155 +++--- .../screenAnnotationRenderer.test.mjs | 449 ++++++++++++------ src/geo/frustum.js | 20 + src/layers/transit/rendering.js | 19 +- src/testSupport/fakeCesiumScene.mjs | 2 +- 7 files changed, 408 insertions(+), 265 deletions(-) diff --git a/changelog.d/1277-annotation-issue-fix.md b/changelog.d/1277-annotation-issue-fix.md index 29437bebd8..cffd40a520 100644 --- a/changelog.d/1277-annotation-issue-fix.md +++ b/changelog.d/1277-annotation-issue-fix.md @@ -1,5 +1,5 @@ -- Stop screen annotations sampling surface height for marks that are hidden, - behind the camera or over the horizon. Visible marks still waiting for - terrain share 32 samples per projection pass and retry once a second, so - drawing a large board no longer stalls the app for seconds (asturksever, - #1277). +- Drawing a large board of screen annotations no longer stalls the app for + seconds: marks behind the camera, past the horizon or out of view no longer + sample the surface height under them, and marks still waiting for the map + surface to load share a small sampling budget and retry once a second + (asturksever, #1277). diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index f8b179f1d1..8ecdd7c399 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -178,16 +178,14 @@ voice follow-ups match on them and bikeshare uses the raw station name as its ID. The text is still untrusted: normalization does not prevent prompt injection. -Screen annotations skip hidden records and, before surface sampling, reject an -unsettled anchor only when its whole accepted height range (-430 to 9000 m) is -behind the camera or below the globe horizon; a settled height is tested as the -actual point. Anchors outside the conservative frustum do not sample and still -project at their cached or zero height, without the horizon test that this -stand-in height cannot decide, so a partly visible arrow keeps its connector. -Unresolved visible heights share a 32-sample budget per projection pass (each -board change and each rendered frame runs one), served oldest-refused first, -retry at most once per second per anchor, and retain no extra timer or -listener. Validated heights remain settled in the bounded cache. +`src/annotations/screenAnnotationRenderer.js` does not sample the surface +height under an anchor whose whole accepted height range (-430 to 9000 m) is +behind the camera or below the globe horizon; such an anchor is hidden. A lone +point whose range lies outside one plane of the view frustum is not sampled +either. Points of arrows, routes and areas are sampled even outside the view, +so the visible part of a mark runs to their real height. Until sampled, a point +is projected at 0 m. At most 32 samples run per `projectAll()` pass, +oldest-refused first, and each anchor retries a miss at most once a second. Terrain height requests accept at most 64 points, matching the browser service's existing batch size and one bounded upstream chunk. Larger requests return HTTP diff --git a/src/annotations/screenAnnotationRenderer.js b/src/annotations/screenAnnotationRenderer.js index 88205fa0d4..371a3aacd1 100644 --- a/src/annotations/screenAnnotationRenderer.js +++ b/src/annotations/screenAnnotationRenderer.js @@ -9,9 +9,9 @@ import { nextTick } from 'vue'; import { useScreenAnnotationsStore } from '../ui/stores/screenAnnotations.js'; import { applicationPinia } from '../ui/vueRuntime.js'; import { heightsOf } from '../queries/heights.js'; -import { fromDegrees, fromDegreesInto, toLonLatH } from '../geo/ellipsoid.js'; -import { frustumPlanes, sphereOutside } from '../geo/frustum.js'; -import { distance } from '../geo/vector.js'; +import { fromDegrees, toLonLatH } from '../geo/ellipsoid.js'; +import { viewPlanes } from '../geo/frustum.js'; +import { distance, dot } from '../geo/vector.js'; import { canvasOf as sceneCanvasOf, findCamera, @@ -88,11 +88,12 @@ export function createScreenAnnotationRenderer( const arrowMarkers = new Map(); let viewBox = null; - // The eye this frame is projected from (the camera port's pose), and the - // query port and canvas it is projected through, read once per pass. + // Read the camera pose, query port, canvas and view-frustum planes once + // per projection pass. let pose = null; let passQuery = null; let passCanvas = null; + let cullingPlanes = null; // The renderer's canvas; a viewer with no renderer bound, its own. const canvasOf = () => sceneCanvasOf(viewer); const records = new Map(); // anno.id -> { key, anno, group, parts } @@ -115,15 +116,12 @@ export function createScreenAnnotationRenderer( const MAX_SURFACE_HEIGHT = 9000; const HEIGHT_SAMPLE_BUDGET = 32; // clampNow calls per projection pass const HEIGHT_RETRY_MS = 1000; // minimum interval between misses per anchor - let cullingPlanes = null; // the pass's view frustum (`frustumPlanes`) - const HEIGHT_BOUNDS_RADIUS = 9500; // m about the 0 m point: every accepted height - const heightBoundsCenter = { x: 0, y: 0, z: 0 }; // Fair sampling: keys refused by an exhausted budget queue in arrival order, // and each pass reserves budget for the oldest queued keys first, so a fixed // iteration order cannot starve anchors beyond the first budget's worth. - let heightQueue = new Set(); // keys refused in earlier passes, oldest first - let heightReserved = new Set(); // queued keys this pass serves first - let heightRefused = new Set(); // keys refused during this pass + const heightQueue = new Set(); + const heightReserved = new Set(); // queued keys this pass serves first + const heightRefused = new Set(); // keys refused during this pass let heightBudget = HEIGHT_SAMPLE_BUDGET; // unreserved slots left this pass let projGen = 0; // bumped each projection frame; entries used this frame are "hot" function trimHeightCache() { @@ -161,12 +159,11 @@ export function createScreenAnnotationRenderer( return `${lon.toFixed(5)},${lat.toFixed(5)}`; } - // Best-effort surface height under a coordinate (clamps onto the 3D tiles). - // Returns 0 until the tile loads, then caches the validated height. - // canSample=false returns the cached height (or 0) without surface sampling. + // Best-effort surface height under a coordinate (clamps onto the 3D tiles): + // the validated height once the tile loads, null until then. // `key` and `cached` are the caller's cache lookup for this coordinate. - function groundHeight(lon, lat, key, cached, canSample = true) { - if (cached && cached.settled) { + function groundHeight(lon, lat, key, cached) { + if (cached?.settled) { // Mark hot for this frame + bump to most-recently-used so heights for live // marks survive eviction while places we've navigated away from age out. cached.gen = projGen; @@ -175,18 +172,17 @@ export function createScreenAnnotationRenderer( return cached.h; } const now = Date.now(); - if (cached && (!canSample || now < cached.nextAttempt)) { + if (cached && now < cached.nextAttempt) { cached.gen = projGen; - return cached.h; + return null; } - if (!canSample) return 0; if (heightReserved.has(key)) { heightReserved.delete(key); } else if (heightBudget > 0) { heightBudget--; } else { heightRefused.add(key); - return cached?.h || 0; + return null; } try { const heights = heightsOf(viewer); @@ -209,15 +205,13 @@ export function createScreenAnnotationRenderer( } catch { /* tiles not ready */ } - const fallback = cached ? cached.h : 0; heightCache.set(key, { - h: fallback, settled: false, gen: projGen, nextAttempt: now + HEIGHT_RETRY_MS, }); trimHeightCache(); - return fallback; + return null; } function add(anno) { @@ -413,49 +407,35 @@ export function createScreenAnnotationRenderer( // Area-type updates route through the hybrid proxy only. } - function project(lon, lat, allowOffscreen = false) { + // The window position of a point at its surface height (0 m until that is + // sampled), or null when it is not in view. A point of an arrow, route or + // area (`connector`) is sampled even outside the view, so the part of the + // mark that is in view runs to the real height of the part that is not. + function project(lon, lat, allowOffscreen = false, connector = false) { + if (!pose) return null; // Anchor at the real surface height (cached + validated), so marks sit on // the ground/building instead of at sea level. The settle-once cache keeps // it stable (no per-frame jitter that earlier broke nearby projections). - // A settled height is tested as the actual point below. An unknown height - // is rejected before GPU-backed surface sampling only when the whole - // accepted height range is proven hidden by one constraint. const key = heightKey(lon, lat); const cached = heightCache.get(key); - let height; - let horizonTest = true; - if (cached?.settled) { - height = groundHeight(lon, lat, key, cached); - } else { - if (heightRangeHidden(lon, lat)) return null; - // The frustum restricts sampling only; an endpoint outside it still - // projects (at its cached or zero height, without the horizon test) - // so a partly visible arrow, route or ring keeps its on-screen - // connector and label. - fromDegreesInto(lon, lat, 0, heightBoundsCenter); - const inFrustum = - !cullingPlanes || - !sphereOutside(cullingPlanes, heightBoundsCenter, HEIGHT_BOUNDS_RADIUS); - height = groundHeight(lon, lat, key, cached, inFrustum); - horizonTest = inFrustum; + let sample = true; + if (!cached?.settled) { + // Unsettled: before sampling, cull only if the whole height range is hidden. + const low = fromDegrees(lon, lat, MIN_SURFACE_HEIGHT); + const high = fromDegrees(lon, lat, MAX_SURFACE_HEIGHT); + if (heightRangeHidden(low, high)) return null; + // A lone point outside the view is not sampled; the entry keeps its + // retry time. + sample = connector || !rangeOutsideView(low, high); + if (!sample && cached) cached.gen = projGen; } - const world = fromDegrees(lon, lat, height); - if (!pose) return null; + const height = sample ? groundHeight(lon, lat, key, cached) : null; + const world = fromDegrees(lon, lat, height ?? 0); // Reject points behind the camera (they produce wrapped/extreme coords). - const eye = pose.position; - const look = pose.direction; - if ( - (world.x - eye.x) * look.x + - (world.y - eye.y) * look.y + - (world.z - eye.z) * look.z <= - 0 - ) - return null; - // Reject points beyond the globe horizon. An unsampled stand-in height - // outside the frustum cannot decide it: the range test above found no - // proof that the real height is hidden. + if (behindEye(world)) return null; + // Reject points beyond the globe horizon. const query = passQuery; - if (!query || (horizonTest && query.isOccluded(world))) return null; + if (!query || query.isOccluded(world)) return null; const win = query.project(world); if (!win || !Number.isFinite(win.x) || !Number.isFinite(win.y)) return null; // Reject absurd off-screen projections (anchor not in view). @@ -474,20 +454,30 @@ export function createScreenAnnotationRenderer( // region (behind the camera plane; the occluder's cone beyond the horizon // plane) is convex. So when both height-range endpoints fail the SAME test, // every intermediate height fails it too. Mixed failures prove nothing. - // With no pose (no eye to test from) nothing is proven hidden. - function heightRangeHidden(lon, lat) { - if (!pose) return false; - const low = fromDegrees(lon, lat, MIN_SURFACE_HEIGHT); - const high = fromDegrees(lon, lat, MAX_SURFACE_HEIGHT); + function heightRangeHidden(low, high) { + if (behindEye(low) && behindEye(high)) return true; + return Boolean(passQuery?.isOccluded(low) && passQuery.isOccluded(high)); + } + + // Whether the height range lies wholly outside one view-frustum plane, so + // no accepted height under the point is in view. + function rangeOutsideView(low, high) { + if (!cullingPlanes) return false; + for (const { normal, w } of cullingPlanes) + if (dot(normal, low) + w < 0 && dot(normal, high) + w < 0) return true; + return false; + } + + // Whether `point` is on or behind the camera plane (needs a pose). + function behindEye(point) { const eye = pose.position; const look = pose.direction; - const behind = (point) => + return ( (point.x - eye.x) * look.x + (point.y - eye.y) * look.y + (point.z - eye.z) * look.z <= - 0; - if (behind(low) && behind(high)) return true; - return Boolean(passQuery?.isOccluded(low) && passQuery.isOccluded(high)); + 0 + ); } // Tracked-entity z-order: the tracked aircraft is a Cesium billboard in the @@ -569,23 +559,16 @@ export function createScreenAnnotationRenderer( publish(); return; } - // Serve the oldest refused keys first; the rest of the budget is open. - heightReserved = new Set(); + heightReserved.clear(); for (const key of heightQueue) { if (heightReserved.size >= HEIGHT_SAMPLE_BUDGET) break; heightReserved.add(key); } heightBudget = HEIGHT_SAMPLE_BUDGET - heightReserved.size; - heightRefused = new Set(); + heightRefused.clear(); projGen += 1; // new frame: entries touched below are "hot" and survive trimming pose = findCamera(viewer)?.pose() ?? null; - // A pose with no perspective frustum culls nothing. - cullingPlanes = - Number.isFinite(pose?.fovy) && - Number.isFinite(pose.aspectRatio) && - Number.isFinite(pose.near) - ? frustumPlanes(pose) - : null; + cullingPlanes = viewPlanes(pose); passQuery = findQuery(viewer); passCanvas = canvasOf(); const trackedRect = trackedEntityRect(); @@ -622,7 +605,9 @@ export function createScreenAnnotationRenderer( const polygons = anno.polygons?.length ? anno.polygons : [[anno.ring]]; for (const polygon of polygons) { const projectedRings = polygon.map((ring) => - ring.map(([lon, lat]) => project(lon, lat, polygon.length > 1)), + ring.map(([lon, lat]) => + project(lon, lat, polygon.length > 1, true), + ), ); // Keep the historical visible-outer projection, but never fill over // an unprojectable hole or hide another independently visible part. @@ -656,8 +641,8 @@ export function createScreenAnnotationRenderer( group.display = 'none'; } } else if (anno.type === 'arrow' && parts.path) { - const a = project(anno.anchor.lon, anno.anchor.lat); - const b = project(anno.to.lon, anno.to.lat); + const a = project(anno.anchor.lon, anno.anchor.lat, false, true); + const b = project(anno.to.lon, anno.to.lat, false, true); if (a && b) { // gentle arc so the connector reads as a drawn gesture, not a ruler line const mx = (a.x + b.x) / 2; @@ -682,7 +667,9 @@ export function createScreenAnnotationRenderer( group.display = 'none'; } } else if (anno.type === 'route' && parts.poly) { - const projected = anno.path.map((pt) => project(pt.lon, pt.lat)); + const projected = anno.path.map((pt) => + project(pt.lon, pt.lat, false, true), + ); const pts = []; for (const p of projected) { if (p) pts.push(`${p.x.toFixed(1)},${p.y.toFixed(1)}`); @@ -746,11 +733,9 @@ export function createScreenAnnotationRenderer( } // Still-refused queued keys keep their place; new refusals join the back. // Keys no longer requesting a sample (settled, culled, removed) drop out. - const nextQueue = new Set(); for (const key of heightQueue) - if (heightRefused.has(key)) nextQueue.add(key); - for (const key of heightRefused) nextQueue.add(key); - heightQueue = nextQueue; + if (!heightRefused.has(key)) heightQueue.delete(key); + for (const key of heightRefused) heightQueue.add(key); // Keep clustered callouts readable. const placed = []; diff --git a/src/annotations/screenAnnotationRenderer.test.mjs b/src/annotations/screenAnnotationRenderer.test.mjs index e15923383c..cca738aae8 100644 --- a/src/annotations/screenAnnotationRenderer.test.mjs +++ b/src/annotations/screenAnnotationRenderer.test.mjs @@ -188,7 +188,7 @@ test('outline upgrade preserves the existing SVG group identity', async (t) => { ), positionCartographic: { height: 1000 }, }; - t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 100, y: 100 })); + projectTo(t, { x: 100, y: 100 }); const sampledAnchors = []; const scene = sceneFor(camera, { canvas: { clientWidth: 1280, clientHeight: 720, width: 1280, height: 720 }, @@ -597,16 +597,12 @@ test('a mark hidden from Draw is not drawn or placed, and comes back when shown' test('hidden and back-facing annotations do not sample; visible unresolved heights have bounded retries', (t) => { const store = samplingBoard(t); t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 1000 }); - t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ - x: 100, - y: 100, - })); + projectTo(t, { x: 100, y: 100 }); const camera = { positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 100000), directionWC: new Cesium.Cartesian3(-1, 0, 0), upWC: new Cesium.Cartesian3(0, 0, 1), positionCartographic: { height: 100000 }, - moveEnd: new Cesium.Event(), }; let samples = 0; const postRender = new Cesium.Event(); @@ -618,7 +614,6 @@ test('hidden and back-facing annotations do not sample; visible unresolved heigh sampleHeight() { samples++; }, - requestRender() {}, }; const renderer = samplingRenderer(store, scene); const mark = (id, lon) => ({ @@ -633,24 +628,31 @@ test('hidden and back-facing annotations do not sample; visible unresolved heigh renderer.add(mark('near-side', 0)); for (let i = 0; i < 100; i++) postRender.raiseEvent(); assert.equal(samples, 1); - for (let i = 0; i < 10; i++) { + t.mock.timers.tick(999); + postRender.raiseEvent(); + assert.equal(samples, 1, 'no retry within a second of the miss'); + t.mock.timers.tick(1); + postRender.raiseEvent(); + assert.equal(samples, 2, 'one retry once a second has passed'); + for (let i = 0; i < 9; i++) { t.mock.timers.tick(1000); postRender.raiseEvent(); } assert.equal(samples, 11); - camera.moveEnd.raiseEvent(); - postRender.raiseEvent(); - assert.equal(samples, 11, 'camera events cannot bypass the retry interval'); renderer.update(mark('near-side', 0), { empty: true }); t.mock.timers.tick(1000); postRender.raiseEvent(); assert.equal(samples, 11, 'hidden records do not sample'); + // With no perspective frustum (no view planes), only the range's + // behind-camera test keeps this anchor from sampling. camera.directionWC = new Cesium.Cartesian3(1, 0, 0); + camera.frustum = new Cesium.OrthographicOffCenterFrustum(); renderer.update(mark('near-side', 0)); postRender.raiseEvent(); assert.equal(samples, 11, 'behind-camera anchors do not sample'); + delete camera.frustum; // Turned 45 degrees east: the anchor is in front and above the horizon, - // but outside the 60-degree frustum plus the 9.5 km height-bound radius. + // but outside the 60-degree frustum at every accepted height. camera.directionWC = new Cesium.Cartesian3(-Math.SQRT1_2, Math.SQRT1_2, 0); postRender.raiseEvent(); assert.equal(samples, 11, 'outside-frustum anchors do not sample'); @@ -669,23 +671,14 @@ test('hidden and back-facing annotations do not sample; visible unresolved heigh 'a projection pass caps synchronous surface work', ); renderer.destroy(); - assert.equal(camera.moveEnd.numberOfListeners, 0); assert.equal(postRender.numberOfListeners, 0); }); -function sampledLon(world) { - return cartographicLon(Cesium.Cartographic.fromCartesian(world)); -} - function cartographicLon(carto) { return Number(Cesium.Math.toDegrees(carto.longitude).toFixed(5)); } -/** - * A board with no view mounted, for tests that count surface samples: the - * renderer projects on `add` and on each post-render event, and the store - * holds what it would draw. Animation frames run at once. - */ +/** A board with no view mounted: tests read the store's marks. Animation frames run at once. */ function samplingBoard(t) { const previousRaf = globalThis.requestAnimationFrame; globalThis.requestAnimationFrame = (fn) => { @@ -698,23 +691,12 @@ function samplingBoard(t) { return useScreenAnnotationsStore(createPinia()); } -/** - * The renderer over `scene`, its camera port's pose taking the double - * camera's own `upWC` where it has one (the fake scene's pose is +Y up), so - * the frustum the renderer culls with is the double's. - */ +/** The screen renderer over a viewer double around `scene`. */ function samplingRenderer(store, scene) { - const viewer = { scene, camera: scene.camera, trackedEntity: null }; - const { camera } = bindFakeCesiumScene(viewer); - const pose = camera.pose; - camera.pose = () => { - const up = scene.camera.upWC; - return up ? { ...pose(), up: { x: up.x, y: up.y, z: up.z } } : pose(); - }; - return createScreenAnnotationRenderer(viewer, { - store, - activeTrackedReadoutId: () => null, - }); + return createScreenAnnotationRenderer( + { scene, camera: scene.camera, trackedEntity: null }, + { store, activeTrackedReadoutId: () => null }, + ); } function squareFrustum() { @@ -726,19 +708,63 @@ function squareFrustum() { return frustum; } -test('an arrow with one endpoint outside a real frustum keeps its visible connector', (t) => { - const store = samplingBoard(t); - t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', (_scene, world) => - sampledLon(world) > 0.1 ? { x: 1100, y: 400 } : { x: 400, y: 400 }, - ); - // 5 km straight down over (0, 0): east is +Y, north is +Z in ECEF here. - const camera = { - positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 5000), - directionWC: new Cesium.Cartesian3(-1, 0, 0), - upWC: new Cesium.Cartesian3(0, 0, 1), - positionCartographic: { height: 5000 }, +const metresEast = (m) => Number((m / 111319.49).toFixed(5)); // degrees of longitude at the equator +const metresNorth = (m) => Number((m / 110574).toFixed(5)); // degrees of latitude at the equator +const at = (p, h) => Cesium.Cartesian3.fromDegrees(p.lon, p.lat, h); + +/** + * A camera double `height` m above (0, 0) looking due east (+Y), pitched + * `pitchDeg` up (+X is up there). + */ +function eastwardCamera(height, pitchDeg = 0) { + const p = Cesium.Math.toRadians(pitchDeg); + return { + positionWC: Cesium.Cartesian3.fromDegrees(0, 0, height), + directionWC: new Cesium.Cartesian3(Math.sin(p), Math.cos(p), 0), + upWC: new Cesium.Cartesian3(Math.cos(p), -Math.sin(p), 0), + positionCartographic: { height }, frustum: squareFrustum(), }; +} + +/** The drawn end point of the board's only arrow, or null when it is hidden. */ +function arrowEnd(store) { + const [mark] = store.board.marks; + const path = mark.children.find((child) => child?.attrs?.class?.includes('gev-anno-arrow')); + const end = path?.attrs.d?.match(/(-?[\d.]+) (-?[\d.]+)$/); + return mark.display === '' && end ? { x: Number(end[1]), y: Number(end[2]) } : null; +} + +/** + * Project through `camera` (position, direction, up, square frustum) onto an + * 800 x 800 canvas for the test's length; returns that projection. + */ +function projectThrough(t, camera, size = 800) { + const tan = Math.tan(camera.frustum.fov / 2); + const toWindow = (world) => { + const right = Cesium.Cartesian3.cross(camera.directionWC, camera.upWC, new Cesium.Cartesian3()); + const v = Cesium.Cartesian3.subtract(world, camera.positionWC, new Cesium.Cartesian3()); + const z = Cesium.Cartesian3.dot(v, camera.directionWC); + return { + x: ((Cesium.Cartesian3.dot(v, right) / z / tan + 1) / 2) * size, + y: ((1 - Cesium.Cartesian3.dot(v, camera.upWC) / z / tan) / 2) * size, + }; + }; + projectTo(t, (_scene, world) => toWindow(world)); + return toWindow; +} + +/** Whether `point`'s accepted heights (a 9.5 km sphere holds them) are all outside `camera`'s frustum. */ +function outsideFrustum(camera, point) { + const volume = camera.frustum.computeCullingVolume(camera.positionWC, camera.directionWC, camera.upWC); + return volume.computeVisibility(new Cesium.BoundingSphere(point, 9500)) === Cesium.Intersect.OUTSIDE; +} + +/** + * An 800 x 800 scene over `camera` whose surface under a longitude is + * `surface(lon)`; `sampled` lists the sampled longitudes. + */ +function surfaceScene(camera, surface) { const sampled = []; const postRender = new Cesium.Event(); const scene = { @@ -747,111 +773,72 @@ test('an arrow with one endpoint outside a real frustum keeps its visible connec postRender, sampleHeightSupported: true, sampleHeight(cartographic) { - sampled.push(cartographicLon(cartographic)); - return 0; + const lon = cartographicLon(cartographic); + sampled.push(lon); + return surface(lon); }, }; - // The 0.2-degree endpoint (~22 km east) is well beyond the side plane plus - // the 9.5 km height-bound radius, yet in front of the camera and the horizon. - const far = Cesium.Cartesian3.fromDegrees(0.2, 0, 0); - const volume = camera.frustum.computeCullingVolume( - camera.positionWC, - camera.directionWC, - camera.upWC, - ); - assert.equal( - volume.computeVisibility(new Cesium.BoundingSphere(far, 9500)), - Cesium.Intersect.OUTSIDE, - ); + return { scene, postRender, sampled }; +} + +test('an arrow with one endpoint outside a real frustum keeps its visible connector', (t) => { + const store = samplingBoard(t); + // 30 km straight down over (0, 0): east is +Y, north is +Z in ECEF here. + const camera = { + positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 30000), + directionWC: new Cesium.Cartesian3(-1, 0, 0), + upWC: new Cesium.Cartesian3(0, 0, 1), + positionCartographic: { height: 30000 }, + frustum: squareFrustum(), + }; + const toWindow = projectThrough(t, camera); + // 35 km east: in front of the camera and the horizon, but outside the + // frustum at every accepted height. + const far = { lon: metresEast(35000), lat: 0 }; + assert.ok(outsideFrustum(camera, at(far, 0))); + const farWin = toWindow(at(far, 0)); + assert.ok(farWin.x > 800 && farWin.x < 1600, 'far end off-screen right, inside the 2w limit'); + const { scene, postRender, sampled } = surfaceScene(camera, () => 0); const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); renderer.add({ id: 'partial-arrow', type: 'arrow', label: 'Ridge', anchor: { lon: 0, lat: 0 }, - to: { lon: 0.2, lat: 0 }, + to: far, }); postRender.raiseEvent(); const [mark] = store.board.marks; assert.equal(mark.display, '', 'the arrow stays drawn'); const path = mark.children.find((child) => child.attrs.class?.includes('gev-anno-arrow')); - assert.match(path.attrs.d, /^M 400\.0 400\.0 Q .* 1100\.0 400\.0$/); - assert.deepEqual([...new Set(sampled)], [0], 'only the in-frustum endpoint samples'); - renderer.destroy(); + assert.ok(path.attrs.d.startsWith('M 400.0 400.0 Q ')); + assert.ok(path.attrs.d.endsWith(` ${farWin.x.toFixed(1)} ${farWin.y.toFixed(1)}`)); + assert.deepEqual([...new Set(sampled)], [0, far.lon], 'the off-view end samples too'); }); -// An arrow whose far end lies outside the frustum (so it is not sampled) and -// beyond the horizon at the 0 m stand-in height, but above it at its real -// 100 m height, keeps its connector and label. -test('an arrow whose unsampled far end is past the 0 m horizon keeps its connector', (t) => { - const previousRaf = globalThis.requestAnimationFrame; - globalThis.requestAnimationFrame = (fn) => { - fn(); - return 1; - }; - t.after(() => { - globalThis.requestAnimationFrame = previousRaf; - }); - const W = 800; - const H = 800; - const half = Cesium.Math.toRadians(30); - const frustum = new Cesium.PerspectiveFrustum(); - frustum.fov = 2 * half; - frustum.aspectRatio = 1; - frustum.near = 1; - frustum.far = 1e8; - // 100 m above the ellipsoid at (0, 0), level, looking due east. - const camera = { - positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 100), - directionWC: new Cesium.Cartesian3(0, 1, 0), - upWC: new Cesium.Cartesian3(1, 0, 0), - positionCartographic: { height: 100 }, - frustum, - }; - // A real perspective projection matching the frustum above. - t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', (_scene, world, result) => { - const right = Cesium.Cartesian3.cross(camera.directionWC, camera.upWC, new Cesium.Cartesian3()); - const v = Cesium.Cartesian3.subtract(world, camera.positionWC, new Cesium.Cartesian3()); - const z = Cesium.Cartesian3.dot(v, camera.directionWC); - const out = result || new Cesium.Cartesian2(); - out.x = ((Cesium.Cartesian3.dot(v, right) / z / Math.tan(half) + 1) / 2) * W; - out.y = ((1 - Cesium.Cartesian3.dot(v, camera.upWC) / z / Math.tan(half)) / 2) * H; - return out; - }); - // Near end 2 km east; far end 56 km away, 50 degrees north of the view axis. - const near = { lon: Number((2000 / 111319.49).toFixed(5)), lat: 0 }; +// The far end lies outside the frustum and beyond the horizon at 0 m, but +// above it at its real 100 m height: it is sampled, so the arrow keeps its +// connector and label. +test('an arrow whose far end is past the horizon only at 0 m keeps its connector', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(100); + const toWindow = projectThrough(t, camera); + const near = { lon: metresEast(2000), lat: 0 }; const bearing = Cesium.Math.toRadians(50); const far = { - lon: Number(((56000 * Math.cos(bearing)) / 111319.49).toFixed(5)), - lat: Number(((56000 * Math.sin(bearing)) / 110574).toFixed(5)), + lon: metresEast(56000 * Math.cos(bearing)), + lat: metresNorth(56000 * Math.sin(bearing)), }; const surface = { [near.lon]: 10, [far.lon]: 100 }; - const postRender = new Cesium.Event(); - const scene = { - camera, - canvas: { width: W, height: H }, - postRender, - sampleHeightSupported: true, - sampleHeight(cartographic) { - return surface[cartographicLon(cartographic)]; - }, - }; - - // Preconditions: the scenario is the one described above. + const { scene, postRender } = surfaceScene(camera, (lon) => surface[lon]); const occluder = new Cesium.EllipsoidalOccluder(Cesium.Ellipsoid.WGS84, camera.positionWC); - const farAt = (h) => Cesium.Cartesian3.fromDegrees(far.lon, far.lat, h); - assert.equal(occluder.isPointVisible(farAt(100)), true, 'far end above the horizon at 100 m'); - assert.equal(occluder.isPointVisible(farAt(0)), false, 'far end past the horizon at 0 m'); - const volume = frustum.computeCullingVolume(camera.positionWC, camera.directionWC, camera.upWC); - assert.equal( - volume.computeVisibility(new Cesium.BoundingSphere(farAt(0), 9500)), - Cesium.Intersect.OUTSIDE, - 'far end outside the frustum plus the 9.5 km sampling sphere', - ); - const farWin = Cesium.SceneTransforms.worldToWindowCoordinates(scene, farAt(100)); - assert.ok(farWin.x > -W && farWin.x < 0, 'far end off-screen left, inside [-w, 2w]'); + assert.equal(occluder.isPointVisible(at(far, 100)), true, 'far end above the horizon at 100 m'); + assert.equal(occluder.isPointVisible(at(far, 0)), false, 'far end past the horizon at 0 m'); + assert.ok(outsideFrustum(camera, at(far, 0)), 'far end outside the frustum at every accepted height'); + const farWin = toWindow(at(far, 100)); + assert.ok(farWin.x > -800 && farWin.x < 0, 'far end off-screen left, inside [-w, 2w]'); - const store = useScreenAnnotationsStore(createPinia()); const renderer = samplingRenderer(store, scene); t.after(() => renderer.destroy()); renderer.add({ @@ -868,9 +855,158 @@ test('an arrow whose unsampled far end is past the 0 m horizon keeps its connect assert.match(path.attrs.d, /^M 400\.0 4\d\d\.\d Q /, 'the connector starts at the on-screen end'); }); +test('an arrow whose end crosses the 2h screen limit only at 0 m keeps its connector', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(18000); + const toWindow = projectThrough(t, camera); + const start = { lon: metresEast(40000), lat: 0 }; + const end = { lon: metresEast(10000), lat: 0 }; + const { scene, postRender, sampled } = surfaceScene(camera, (lon) => (lon === end.lon ? 1500 : 0)); + assert.ok(toWindow(at(start, 0)).y < 800, 'start on screen'); + assert.ok(outsideFrustum(camera, at(end, 0)), 'end sphere outside the frustum'); + assert.ok(toWindow(at(end, 1500)).y < 1600, 'end inside the limit at its real height'); + assert.ok(toWindow(at(end, 0)).y > 1600, 'end past the limit at 0 m'); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ id: 'a', type: 'arrow', label: 'Ridge', anchor: start, to: end }); + for (let i = 0; i < 3; i++) postRender.raiseEvent(); + assert.equal(store.board.marks[0].display, '', 'the partly visible arrow stays drawn'); + assert.deepEqual([...new Set(sampled)], [start.lon, end.lon], 'the off-view end samples too'); +}); + +test('an upward-looking arrow keeps a far end that is behind the eye only at 0 m', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(100, 59); + projectThrough(t, camera); + // Roofs: 132 m 19 m east (in view), 145 m 12 m west (above the view). + const start = { lon: metresEast(19), lat: 0 }; + const end = { lon: metresEast(-12), lat: 0 }; + const { scene, postRender } = surfaceScene(camera, (lon) => (lon === start.lon ? 132 : 145)); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ id: 'up', type: 'arrow', label: 'Tower', anchor: start, to: end }); + for (let i = 0; i < 4; i++) postRender.raiseEvent(); + const drawn = arrowEnd(store); + assert.ok(drawn, 'the arrow from the on-screen roof is drawn'); + assert.ok(drawn.y < 0 && drawn.y > -800, `the connector leaves through the top edge (end y ${drawn.y})`); +}); + +test('an arrow crossing the view between two off-view ends on a plateau is drawn', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(4000); + projectThrough(t, camera); + // Both ends 2 km ahead and 2 km to either side on a 4000 m plateau: at 0 m + // both fall past the 2h limit, at 4000 m the arc crosses the screen. + const a = { lon: metresEast(2000), lat: metresNorth(2000) }; + const b = { lon: metresEast(2000), lat: metresNorth(-2000) }; + const { scene, postRender } = surfaceScene(camera, () => 4000); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ id: 'plateau', type: 'arrow', label: 'Pass', anchor: a, to: b }); + for (let i = 0; i < 4; i++) postRender.raiseEvent(); + const drawn = arrowEnd(store); + assert.ok(drawn, 'the arrow is drawn'); + assert.ok(Math.abs(drawn.y - 400) < 5, `the connector crosses at eye level (end y ${drawn.y})`); +}); + +test('an arrow to an off-view peak points at the peak, not at 0 m below it', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(4000); + projectThrough(t, camera); + // From a 4000 m plateau 2 km ahead to a 4500 m peak just left of the view. + const start = { lon: metresEast(2000), lat: 0 }; + const end = { lon: metresEast(1000), lat: metresNorth(900) }; + const { scene, postRender } = surfaceScene(camera, (lon) => (lon === start.lon ? 4000 : 4500)); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ id: 'peak', type: 'arrow', label: 'Peak', anchor: start, to: end }); + for (let i = 0; i < 4; i++) postRender.raiseEvent(); + const drawn = arrowEnd(store); + assert.ok(drawn, 'the arrow is drawn'); + assert.ok( + Math.abs(drawn.x + 223.8) < 2 && Math.abs(drawn.y - 53.8) < 2, + `end at the 4500 m projection (-223.8, 53.8), got (${drawn.x}, ${drawn.y})`, + ); +}); + +test('a lone label beyond the horizon just outside the view stays hidden', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(100); + const toWindow = projectThrough(t, camera); + const bearing = Cesium.Math.toRadians(34); + const anchor = { + lon: metresEast(200000 * Math.cos(bearing)), + lat: metresNorth(200000 * Math.sin(bearing)), + }; + const occluder = new Cesium.EllipsoidalOccluder(Cesium.Ellipsoid.WGS84, camera.positionWC); + assert.equal(occluder.isPointVisible(at(anchor, 0)), false, 'beyond the horizon at 0 m'); + assert.ok(outsideFrustum(camera, at(anchor, 0)), 'sphere outside the frustum'); + assert.ok(toWindow(at(anchor, 0)).x > -800, 'projection inside [-w, 2w]'); + const { scene, postRender } = surfaceScene(camera, () => 0); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ id: 'l', type: 'label', label: 'Far city', anchor }); + for (let i = 0; i < 3; i++) postRender.raiseEvent(); + assert.equal(store.board.marks[0].display, 'none', 'its callout does not peek in at the left edge'); +}); + +test('an arrow wholly beyond the horizon is not drawn across the screen', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(100); + projectThrough(t, camera); + const a = { lon: metresEast(80000), lat: metresNorth(67000) }; + const b = { lon: metresEast(80000), lat: metresNorth(-67000) }; + const occluder = new Cesium.EllipsoidalOccluder(Cesium.Ellipsoid.WGS84, camera.positionWC); + for (const point of [a, b]) { + assert.equal(occluder.isPointVisible(at(point, 0)), false, 'end beyond the horizon at 0 m'); + assert.ok(outsideFrustum(camera, at(point, 0)), 'end sphere outside the frustum'); + } + const { scene, postRender } = surfaceScene(camera, () => 0); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ id: 'x', type: 'arrow', label: 'Ghost', anchor: a, to: b }); + for (let i = 0; i < 3; i++) postRender.raiseEvent(); + assert.equal(store.board.marks[0].display, 'none', 'no ghost connector'); +}); + +test('a visible area ring keeps a vertex past the horizon only at 0 m', (t) => { + const store = samplingBoard(t); + const camera = eastwardCamera(100); + const toWindow = projectThrough(t, camera); + const bearing = Cesium.Math.toRadians(50); + const far = { lon: metresEast(56000 * Math.cos(bearing)), lat: metresNorth(56000 * Math.sin(bearing)) }; + const nearLon = metresEast(2000); + const vertices = [ + { lon: nearLon, lat: metresNorth(300) }, + { lon: nearLon, lat: metresNorth(-300) }, + far, + ]; + const occluder = new Cesium.EllipsoidalOccluder(Cesium.Ellipsoid.WGS84, camera.positionWC); + assert.ok(outsideFrustum(camera, at(far, 0))); + assert.equal(occluder.isPointVisible(at(far, 0)), false); + assert.equal(occluder.isPointVisible(at(far, 100)), true); + const { scene, postRender, sampled } = surfaceScene(camera, (lon) => (lon === far.lon ? 100 : 10)); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + renderer.add({ + id: 'triangle', type: 'area', label: 'Ridge', anchor: vertices[0], + ring: vertices.map(({ lon, lat }) => [lon, lat]), + }); + postRender.raiseEvent(); + const [mark] = store.board.marks; + assert.equal(mark.display, '', 'the triangle stays drawn'); + const path = mark.children.find((child) => child.attrs.class?.includes('gev-anno-area')); + const coords = vertices.map((p) => { + const { x, y } = toWindow(at(p, p === far ? 100 : 10)); + return `${x.toFixed(1)},${y.toFixed(1)}`; + }); + assert.equal(path.attrs.d, `M ${coords.join(' L ')} Z`, 'the far vertex sits at its real height'); + assert.deepEqual(sampled, [nearLon, nearLon, far.lon], 'the off-view vertex samples too'); +}); + test('a low-angle cached roof stays visible when range endpoints fail different tests', (t) => { const store = samplingBoard(t); - t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 400, y: 380 })); + projectTo(t, { x: 400, y: 380 }); // Camera 1 m above the ellipsoid, heading east, pitched 25 degrees down. const pitch = Cesium.Math.toRadians(25); const camera = { @@ -919,7 +1055,7 @@ test('a low-angle cached roof stays visible when range endpoints fail different test('height retries beyond the first budget are served under sparse passes', (t) => { const store = samplingBoard(t); t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 1000 }); - t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', () => ({ x: 100, y: 100 })); + projectTo(t, { x: 100, y: 100 }); const camera = { positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 100000), directionWC: new Cesium.Cartesian3(-1, 0, 0), @@ -957,16 +1093,37 @@ test('height retries beyond the first budget are served under sparse passes', (t } assert.ok(lastSamples.slice(0, 2).includes(1), 'the 33rd point is served within two passes'); assert.equal(lastSamples.at(-1), 0, 'and then stays settled'); - // Points refused in one pass are served first in the next: every point is - // retried within any two consecutive sparse passes. - pass = []; - t.mock.timers.tick(1000); - postRender.raiseEvent(); - const firstPass = pass; - pass = []; - t.mock.timers.tick(1000); - postRender.raiseEvent(); - const served = new Set([...firstPass, ...pass]); - for (const lon of lons.slice(0, -1)) assert.ok(served.has(lon), `${lon} retried`); renderer.destroy(); }); + +test('points refused longest are sampled before newer refusals', (t) => { + const store = samplingBoard(t); + t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 1000 }); + projectTo(t, { x: 100, y: 100 }); + const camera = { + positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 100000), + directionWC: new Cesium.Cartesian3(-1, 0, 0), + positionCartographic: { height: 100000 }, + }; + const lons = Array.from({ length: 65 }, (_, i) => Number(((i + 1) / 1000).toFixed(3))); + let pass = []; + const { scene, postRender } = surfaceScene(camera, (lon) => { + pass.push(lon); + }); + const renderer = samplingRenderer(store, scene); + t.after(() => renderer.destroy()); + for (const lon of lons) { + renderer.add({ id: `p${lon}`, type: 'label', label: 'P', anchor: { lon, lat: 0 } }); + } + assert.deepEqual(pass, lons, 'every point gets its first miss'); + const passes = []; + for (let i = 0; i < 3; i++) { + t.mock.timers.tick(1000); + pass = []; + postRender.raiseEvent(); + passes.push(pass); + } + assert.deepEqual(passes[0], lons.slice(0, 32), 'a pass serves the first 32 in board order'); + assert.deepEqual(passes[1], lons.slice(32, 64), 'the next serves the 32 refused longest'); + assert.deepEqual(passes[2], [...lons.slice(0, 31), lons[64]], 'then the rest of the queue, before newer refusals'); +}); diff --git a/src/geo/frustum.js b/src/geo/frustum.js index 614d2fa500..162b505549 100644 --- a/src/geo/frustum.js +++ b/src/geo/frustum.js @@ -47,6 +47,26 @@ export function frustumPlanes(pose) { return [left, rightPlane, bottom, top, nearPlane, farPlane]; } +/** + * `frustumPlanes(pose)`, or null when the pose does not describe a + * perspective frustum: no position, direction or up, or no finite `fovy`, + * `aspectRatio` or `near` (an orthographic camera, no camera). + * @param {object|null|undefined} pose + * @returns {ReturnType|null} + */ +export function viewPlanes(pose) { + if ( + !pose?.position || + !pose.direction || + !pose.up || + !Number.isFinite(pose.fovy) || + !Number.isFinite(pose.aspectRatio) || + !Number.isFinite(pose.near) + ) + return null; + return frustumPlanes(pose); +} + /** * Whether a sphere is wholly outside `planes` (from `frustumPlanes`), as * the default renderer's `CullingVolume.computeVisibility` reports diff --git a/src/layers/transit/rendering.js b/src/layers/transit/rendering.js index 6a6cda15f3..c98f8d0e6d 100644 --- a/src/layers/transit/rendering.js +++ b/src/layers/transit/rendering.js @@ -9,7 +9,7 @@ import { poseSignature } from '../../render/camera/poseSignature.js'; import { heightsOf } from '../../queries/heights.js'; import { fromDegreesInto } from '../../geo/ellipsoid.js'; import { Vec3 } from '../../geo/vector.js'; -import { frustumPlanes } from '../../geo/frustum.js'; +import { viewPlanes } from '../../geo/frustum.js'; import { perspectiveCourseRotation } from '../../data/screenRotation.js'; import { PLACED_WAKE_MS, @@ -1074,23 +1074,6 @@ export function createRendering({ state, services, parts }) { ); } - /** - * The planes of the frustum the camera looks through, as the default - * renderer culls with them, or null when the pose does not describe one. - */ - function viewPlanes(pose) { - if ( - !pose?.position || - !pose.direction || - !pose.up || - !Number.isFinite(pose.fovy) || - !Number.isFinite(pose.aspectRatio) || - !Number.isFinite(pose.near) - ) - return null; - return frustumPlanes(pose); - } - function refreshVisibility() { if (!state._enabled) return 0; const now = Date.now(); diff --git a/src/testSupport/fakeCesiumScene.mjs b/src/testSupport/fakeCesiumScene.mjs index 35f7e605f0..741e74d012 100644 --- a/src/testSupport/fakeCesiumScene.mjs +++ b/src/testSupport/fakeCesiumScene.mjs @@ -234,7 +234,7 @@ export function bindFakeCesiumScene( direction: c?.directionWC ? plain(c.directionWC) : { x: 0, y: 0, z: -1 }, - up: { x: 0, y: 1, z: 0 }, + up: c?.upWC ? plain(c.upWC) : { x: 0, y: 1, z: 0 }, right: { x: 1, y: 0, z: 0 }, // An orthographic frustum has none, as the Cesium port reports it. fovy: