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

+64
View File
@@ -1475,6 +1475,70 @@ export function createContractSuite(
);
},
],
[
'surface.sampleHeightDetailed: source, tile size, lod and mover-set exclusion',
async () => {
const place = cartographic.fromDegrees(20, 10, 0);
const shape = (detail, label) => {
if (detail === undefined) return;
ensure(Number.isFinite(detail.height), `${label}: height`);
ensure(
detail.source === 'tiles' || detail.source === 'terrain',
`${label}: source ${detail.source}`,
);
ensure(
detail.tileSizeM === undefined ||
(detail.source === 'tiles' && detail.tileSizeM > 0),
`${label}: tileSizeM ${detail.tileSizeM}`,
);
};
const visible = engine.surface.sampleHeightDetailed(place);
shape(visible, 'visible');
shape(
engine.surface.sampleHeightDetailed(place, { lod: 'finest' }),
'finest',
);
if (visible?.source === 'tiles')
near(
engine.surface.sampleHeight(place),
visible.height,
1e-6,
'sampleHeight and the detailed tiles answer',
);
let rejected = null;
try {
engine.surface.sampleHeightDetailed(place, { lod: 'best' });
} catch (error) {
rejected = error;
}
ensure(rejected instanceof TypeError, 'an unknown lod was accepted');
// A mover set in exclude: the sample works and the set stays.
const set = engine.movers.createSet({
id: 'contract-surface-exclude',
kind: 'point',
capacity: 1,
point: { sizePx: 8 },
});
try {
set.set(0, { position: cartesian3.fromDegrees(20, 10, 50) });
set.setCount(1);
set.commit();
shape(
engine.surface.sampleHeightDetailed(place, { exclude: [set] }),
'excluding a set',
);
ensure(set.id === 'contract-surface-exclude', 'the set has no id');
ensure(
engine.movers
.list()
.some(({ id }) => id === 'contract-surface-exclude'),
'the excluded set is gone',
);
} finally {
set.destroy();
}
},
],
[
'surface: flags, tilesLoaded, sampleHeight, terrainHeight and clampToHeight shapes',
async () => {