feat(globe): surface height quality

engine.surface.sampleHeightDetailed(place, { exclude, lod }) answers
{ height, source: 'tiles' | 'terrain', tileSizeM? } (src/globe/surfaceDetail.js).
On Navara tileSizeM is the extent of the tile that answered and
lod 'finest' takes the finest loaded tile, drawn or not; Cesium answers
tiles without a size, else the globe's terrain. acceptedSurfaceHeight()
turns an answer into a height or a miss: tiles larger than
MAX_FLOOR_TILE_SIZE_M (4 km) are too coarse, terrain is not the mesh.

The mesh floor sampler and the ground snap are engine-only now (a viewer
or scene reaches its engine through engineFromViewer, which also registers
the scene) and treat a coarse answer as a miss, as they treat undefined.
Measured on Navara at Austin: while the tiles stream, a 27.9 km tile reads
143.2 m where the ground is 122.5 m (a 1.8 km tile).

`exclude` takes the engine's own mover sets (MoverSet.id): Cesium hides a
set's primitive for the synchronous sample (Cesium matches excluded objects
per billboard, not per collection); Navara's ray only meets tiles.

"sampleHeight undefined in the app on Navara" did not reproduce: the
startup Austin sample is 121.9 m (tile 889 m) on Navara and 122.4 m on
Cesium; one ModelMesh class is patched.

S2 QA (scripts/qa-surface-heights.mjs, 20 places at JFK, SFO, AUS, roofs
and streets): Navara within 2 m of Cesium at 19/20 from 800 m and 18/20
from 15 km with lod 'finest' (gates 18 and 15); offsets per region
-0.21 / +0.4 / +0.1 m; the Empire State roof differs by 39 m (spire
geometry). Navara tile sizes at 800 m: 112-314 m.
This commit is contained in:
German Khokhlov committed 2026-10-16 20:51:29 +04:00
1 parent f640890cf6
commit 645f042450
20 files changed
+635 -244

No files matched your search

+98 -90
View File
@@ -4,9 +4,10 @@
// The sampler's acceptance rule was previously covered only through
// `reportValidatedMeshFloorCell` directly, which proves the gate but not the
// decision that feeds it. These tests call `sampleMeshFloorCells` with a fake
// scene whose `sampleHeight` returns exactly what Cesium can return — a number,
// `undefined`, NaN, or a throw — and assert that a cell latches if and only if
// a REAL DEM prior exists and the sample fits its window.
// globe engine whose surface answers what an engine can answer — a height,
// `undefined`, NaN, a throw, or a coarse tile — and assert that a cell
// latches if and only if a REAL DEM prior exists, the answer is fine enough
// and the sample fits its window.
//
// That requirement is the load-bearing one: this round built a tier that kept
// the reading when no prior existed, and measured it recording a coarse-LOD
@@ -46,90 +47,8 @@ async function seedDem(cell, ellipsoid) {
}
}
/** A scene the sampler accepts: low camera, one visible tileset reporting
* tilesLoaded, and a `sampleHeight` under the test's control. */
function fakeScene(sampleHeight, { cameraHeightM = 900, tilesLoaded = true, show = true } = {}) {
// instanceof-compatible without running Cesium's constructor; `tilesLoaded` is
// a prototype getter, so it has to be shadowed with an own data property.
const tileset = Object.create(Cesium.Cesium3DTileset.prototype);
Object.defineProperty(tileset, 'tilesLoaded', { value: tilesLoaded, configurable: true });
Object.defineProperty(tileset, 'show', { value: show, configurable: true });
return {
sampleHeight,
camera: { positionCartographic: { height: cameraHeightM } },
primitives: { length: 1, get: () => tileset },
};
}
function reset() {
_clearMeshFloorCellsForTest();
setMeshFloorPreferred(true);
}
test('sampler: a finite sample with NO DEM prior is stored NOWHERE', () => {
reset();
const cell = nextSite();
sampleMeshFloorCells(fakeScene(() => 138.0), [cell], { viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null, 'nothing may latch without a prior');
assert.equal(cachedGroundFloor(cell.lat, cell.lon), null, 'the shared choke point stays clean');
});
test('sampler: a finite sample WITH a fitting DEM prior latches and becomes the shared floor', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
const scene = fakeScene(() => 137.0); // +17 m of mesh over bare earth — in window
sampleMeshFloorCells(scene, [cell], { viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(cachedMeshFloor(cell.lat, cell.lon), 137.0);
assert.equal(cachedGroundFloor(cell.lat, cell.lon), 137.0, 'and it is what every consumer reads');
});
test('sampler: a sample REJECTED against a real prior is stored nowhere', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
const scene = fakeScene(() => 400.0); // a tower hit — far outside the +80 m window
sampleMeshFloorCells(scene, [cell], { viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null);
assert.equal(cachedGroundFloor(cell.lat, cell.lon), 120.0, 'the DEM prior still answers');
});
test('sampler: undefined, NaN and a throwing probe latch nothing and crash nothing', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
for (const bad of [() => undefined, () => Number.NaN, () => { throw new Error('mid-teardown'); }]) {
sampleMeshFloorCells(fakeScene(bad), [cell], { viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null, 'no negative latch, no throw');
}
sampleMeshFloorCells(fakeScene(() => 133.0), [cell], { viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(cachedMeshFloor(cell.lat, cell.lon), 133.0, 'and a later good sample still lands');
});
test('sampler: a high camera or unloaded tiles produce no records at all', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
const opts = { viewerLat: cell.lat, viewerLon: cell.lon };
sampleMeshFloorCells(fakeScene(() => 138.0, { cameraHeightM: 90_000 }), [cell], opts);
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null, 'coarse LOD under a high camera');
sampleMeshFloorCells(fakeScene(() => 138.0, { tilesLoaded: false }), [cell], opts);
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null, 'mid-stream tiles read coarse');
});
test('sampler: outside the google-3d regime nothing is sampled at all', () => {
reset();
const cell = nextSite();
setMeshFloorPreferred(false);
let calls = 0;
sampleMeshFloorCells(fakeScene(() => { calls += 1; return 138.0; }), [cell],
{ viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(calls, 0, 'on a globe stack the DEM IS the rendered surface');
setMeshFloorPreferred(true);
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null);
});
// --- On a globe engine (engine.surface / camera.height / maps.photorealActive)
/** A globe engine the sampler accepts: low camera over the cell, photoreal
* tiles loaded, and a surface under the test's control. */
async function fakeEngineAt(cell, { heightM = 900, tilesLoaded = true, photoreal = true, sample } = {}) {
const { createFakeEngine } = await import('../globe/testing/fakeEngine.js');
@@ -144,6 +63,74 @@ async function fakeEngineAt(cell, { heightM = 900, tilesLoaded = true, photoreal
return engine;
}
function reset() {
_clearMeshFloorCellsForTest();
setMeshFloorPreferred(true);
}
test('sampler: a finite sample with NO DEM prior is stored NOWHERE', async () => {
reset();
const cell = nextSite();
sampleMeshFloorCells(await fakeEngineAt(cell, { sample: () => 138.0 }), [cell], { viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null, 'nothing may latch without a prior');
assert.equal(cachedGroundFloor(cell.lat, cell.lon), null, 'the shared choke point stays clean');
});
test('sampler: a finite sample WITH a fitting DEM prior latches and becomes the shared floor', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
const engine = await fakeEngineAt(cell, { sample: () => 137.0 }); // +17 m of mesh over bare earth — in window
sampleMeshFloorCells(engine, [cell], { viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(cachedMeshFloor(cell.lat, cell.lon), 137.0);
assert.equal(cachedGroundFloor(cell.lat, cell.lon), 137.0, 'and it is what every consumer reads');
});
test('sampler: a sample REJECTED against a real prior is stored nowhere', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
const engine = await fakeEngineAt(cell, { sample: () => 400.0 }); // a tower hit — far outside the +80 m window
sampleMeshFloorCells(engine, [cell], { viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null);
assert.equal(cachedGroundFloor(cell.lat, cell.lon), 120.0, 'the DEM prior still answers');
});
test('sampler: undefined, NaN and a throwing probe latch nothing and crash nothing', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
for (const bad of [() => undefined, () => Number.NaN, () => { throw new Error('mid-teardown'); }]) {
sampleMeshFloorCells(await fakeEngineAt(cell, { sample: bad }), [cell], { viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null, 'no negative latch, no throw');
}
sampleMeshFloorCells(await fakeEngineAt(cell, { sample: () => 133.0 }), [cell], { viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(cachedMeshFloor(cell.lat, cell.lon), 133.0, 'and a later good sample still lands');
});
test('sampler: a high camera or unloaded tiles produce no records at all', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
const opts = { viewerLat: cell.lat, viewerLon: cell.lon };
sampleMeshFloorCells(await fakeEngineAt(cell, { sample: () => 138.0, heightM: 90_000 }), [cell], opts);
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null, 'coarse LOD under a high camera');
sampleMeshFloorCells(await fakeEngineAt(cell, { sample: () => 138.0, tilesLoaded: false }), [cell], opts);
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null, 'mid-stream tiles read coarse');
});
test('sampler: outside the google-3d regime nothing is sampled at all', async () => {
reset();
const cell = nextSite();
setMeshFloorPreferred(false);
let calls = 0;
sampleMeshFloorCells(await fakeEngineAt(cell, { sample: () => { calls += 1; return 138.0; } }), [cell],
{ viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(calls, 0, 'on a globe stack the DEM IS the rendered surface');
setMeshFloorPreferred(true);
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null);
});
test('sampler on a globe engine: samples engine.surface and latches against the prior', async () => {
reset();
const cell = nextSite();
@@ -151,9 +138,30 @@ test('sampler on a globe engine: samples engine.surface and latches against the
const engine = await fakeEngineAt(cell, { sample: () => 137.0 });
sampleMeshFloorCells(engine, [cell], { viewerLat: cell.lat, viewerLon: cell.lon, excludeObjects: ['own'] });
assert.equal(cachedMeshFloor(cell.lat, cell.lon), 137.0);
const [call] = engine.fake.callsOf('surface.sampleHeight');
const [call] = engine.fake.callsOf('surface.sampleHeightDetailed');
assert.ok(Math.abs(Cesium.Math.toDegrees(call.args[0].latitude) - cell.lat) < 1e-9);
assert.deepEqual(call.args[1], ['own']);
assert.deepEqual(call.args[1], { exclude: ['own'], lod: 'visible' });
});
test('sampler: a coarse tile answer is a miss; a fine one latches', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
const opts = { viewerLat: cell.lat, viewerLon: cell.lon };
// Measured on Navara at Austin while the tiles streamed: a 28 km tile read
// 143.2 m where the ground is 122.5 m (a 1.8 km tile).
const engine = await fakeEngineAt(cell);
engine.fake.script('sampleHeightDetailed', () => ({ height: 143.2, source: 'tiles', tileSizeM: 27_914 }));
sampleMeshFloorCells(engine, [cell], opts);
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null, 'coarse: no latch');
engine.fake.script('sampleHeightDetailed', () => ({ height: 122.5, source: 'tiles', tileSizeM: 1_797 }));
sampleMeshFloorCells(engine, [cell], opts);
assert.equal(cachedMeshFloor(cell.lat, cell.lon), 122.5);
const terrainOnly = nextSite();
await seedDem(terrainOnly, 120.0);
engine.fake.script('sampleHeightDetailed', () => ({ height: 121, source: 'terrain' }));
sampleMeshFloorCells(engine, [terrainOnly], { viewerLat: terrainOnly.lat, viewerLon: terrainOnly.lon });
assert.equal(cachedMeshFloor(terrainOnly.lat, terrainOnly.lon), null, 'terrain is not the mesh');
});
test('sampler on a globe engine: a high camera, loading tiles or no photoreal tiles sample nothing', async () => {
@@ -164,7 +172,7 @@ test('sampler on a globe engine: a high camera, loading tiles or no photoreal ti
for (const options of [{ heightM: 90_000 }, { tilesLoaded: false }, { photoreal: false }]) {
const engine = await fakeEngineAt(cell, { ...options, sample: () => 138.0 });
sampleMeshFloorCells(engine, [cell], opts);
assert.equal(engine.fake.callsOf('surface.sampleHeight').length, 0, JSON.stringify(options));
assert.equal(engine.fake.callsOf('surface.sampleHeightDetailed').length, 0, JSON.stringify(options));
}
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null);
});
+15 -1
View File
@@ -26,6 +26,7 @@ import {
FLEET_MODEL_ALT_CEIL_M,
TRACKED_MODEL_EXIT_RATIO,
} from './trackedModelRegime.js';
import { registerViewerEngine } from '../globe/cesium/engineFromViewer.js';
import * as Cesium from 'cesium';
import flightsLayer, {
_setTrackedFlightRefreshStateForTest,
@@ -155,7 +156,7 @@ if (typeof globalThis.window === 'undefined') {
/** A viewer stub whose camera altitude the test can move between evaluations. */
function viewerAtHeight(height, { tilesLoaded = true, sampleHeight = () => undefined } = {}) {
const tileset = { show: true, tilesLoaded };
return {
const viewer = {
camera: {
positionCartographic: { height },
positionWC: Cesium.Cartesian3.fromDegrees(-97.71, 30.21, 5000),
@@ -171,6 +172,19 @@ function viewerAtHeight(height, { tilesLoaded = true, sampleHeight = () => undef
trackedEntity: undefined,
entities: { remove() {} },
};
// The ground snap samples through the viewer's engine (engineFromViewer):
// the engine surface over this stub's tileset and scene.sampleHeight.
registerViewerEngine(viewer, {
isDestroyed: () => false,
surface: {
tilesLoaded: () => viewer.tileset.tilesLoaded === true,
sampleHeightDetailed(place, { exclude } = {}) {
const h = viewer.scene.sampleHeight(place, exclude);
return Number.isFinite(h) ? { height: h, source: 'tiles' } : undefined;
},
},
});
return viewer;
}
/** A billboard with a real position, so the tracked-model driver has somewhere