Ask for heights through one service per scene

About 20 sites called scene.sampleHeight, globe.getHeight,
scene.clampToHeight or the MostDetailed variants directly, each with its own
idea of a miss (undefined, NaN, a throw). They now ask heightsFor(scene) in
src/queries/heights.js:

- now(point, { against, exclude }) answers from what is loaded, or null;
  against is 'surface' (what is drawn) or 'terrain' (loaded terrain only).
- clampNow(position) moves a position onto the drawn surface, or null.
- batch() and clampBatch() wait for the most detailed tiles: null per
  missed point, a rejection when the whole query fails.
- supported() reports { surface, clamp } without allocating.

Cesium still answers now() synchronously, so nothing changes on screen and
nothing is slower: in the live app 1,000 calls cost the same through the
service as direct (terrain 0.5-0.7 ms, surface 2-6 ms a call, run-to-run
noise larger than the difference). Every site already treated a miss as
"hold the last value or fall back"; a renderer that can only answer from a
cache or asynchronously can now plug in at one place.

- A Bhote Koshi evidence point whose terrain sample misses stays at its
  fallback elevation instead of reading the miss as sea level.
- The mesh floor sampler skips a scene without depth-texture support
  instead of spending its budget on probes that throw.
- The world annotation probe's trace reads hit/missed.
- A source scan forbids direct height calls outside the service.

The service is exported as ./queries/heights and documented in
docs/APPLICATION.md.
This commit is contained in:
Sameh Khamis committed 2026-11-04 09:24:30 -08:00
1 parent 02d492a079
commit 9bdeffeca3
32 files changed
+704 -210

No files matched your search

+3 -1
View File
@@ -1,5 +1,6 @@
import * as Cesium from 'cesium';
import { plausibleSurfaceHeight, sampledSurfaceHeight } from './view.js';
import { heightsFor } from '../../queries/heights.js';
/** Fly the globe camera once to frame a photo after it opens. */
export function createCameraFraming({ state }) {
@@ -30,7 +31,8 @@ export function createCameraFraming({ state }) {
const scene = state.viewer?.scene;
const carto = Cesium.Cartographic.fromDegrees(lon, lat);
let height = sampledSurfaceHeight(scene, carto);
if (height === null) height = scene?.globe?.getHeight?.(carto);
if (height === null && scene)
height = heightsFor(scene).now(carto, { against: 'terrain' });
if (!plausibleSurfaceHeight(height)) height = fallback;
return plausibleSurfaceHeight(height) ? height : 0;
}
+10 -2
View File
@@ -799,7 +799,11 @@ test('under Google 3D the ground is measured again once its tiles load, without
const viewer = fakeViewer();
// 4 km up the ellipsoid, 2 km over a city whose tiles are still loading.
let ground;
viewer.camera.positionCartographic = { height: 4000 };
viewer.camera.positionCartographic = {
longitude: 0,
latitude: 0,
height: 4000,
};
viewer.scene.globe = { show: false };
viewer.scene.sampleHeightSupported = true;
viewer.scene.sampleHeight = () => ground;
@@ -823,7 +827,11 @@ test('an unknown ground is measured only a few times, and not after the layer is
t.mock.timers.enable({ apis: ['setTimeout'] });
const viewer = fakeViewer();
let samples = 0;
viewer.camera.positionCartographic = { height: 4000 };
viewer.camera.positionCartographic = {
longitude: 0,
latitude: 0,
height: 4000,
};
viewer.scene.globe = { show: false };
viewer.scene.sampleHeightSupported = true;
viewer.scene.sampleHeight = () => {
+6 -8
View File
@@ -1,5 +1,6 @@
import * as Cesium from 'cesium';
import { wrapLon } from './tileMath.js';
import { heightsFor } from '../../queries/heights.js';
/** Equirectangular metres between {lon, lat} points, the short way round ±180°; street scale. */
export function metresBetween(a, b) {
@@ -21,12 +22,9 @@ export function plausibleSurfaceHeight(height) {
* underground before tiles load).
*/
export function sampledSurfaceHeight(scene, carto) {
let height = null;
try {
if (scene?.sampleHeightSupported) height = scene.sampleHeight(carto);
} catch {
/* not sampleable yet */
}
const height = scene?.sampleHeightSupported
? heightsFor(scene).now(carto)
: null;
return plausibleSurfaceHeight(height) ? height : null;
}
@@ -41,8 +39,8 @@ export function groundUnderCamera(viewer) {
if (!carto || !scene) return null;
const globe = scene.globe;
if (globe && globe.show !== false) {
const ground = globe.getHeight?.(carto);
if (Number.isFinite(ground)) return ground;
const ground = heightsFor(scene).now(carto, { against: 'terrain' });
if (ground !== null) return ground;
}
const sampled = sampledSurfaceHeight(scene, carto);
return sampled !== null && sampled < carto.height ? sampled : null;