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

+67 -16
View File
@@ -1,42 +1,93 @@
// GlobeSurface on a Cesium scene: the rendered-surface queries that
// services/groundSnap and services/meshFloorSampler make today.
// services/groundSnap and services/meshFloorSampler make.
//
// `exclude` takes the engine's own mover sets (engine.movers) as well as
// Cesium objects: Cesium's sampleHeight matches excluded objects by the
// picked primitive, which for a set is each billboard, point or model, so a
// set is hidden for the sample instead (synchronous: nothing draws in
// between) and shown again after it.
import { firstVisibleTileset } from '../../services/groundSnap.js';
import { normalizeSurfaceOptions } from '../surfaceDetail.js';
import { toGeo3 } from './convert.js';
const finite = (value) => (Number.isFinite(value) ? value : undefined);
/**
* @param {Cesium.Viewer} viewer
* @param {{ engineExclude?: (entry: any) => ({ show: boolean } | null) }} [options]
* `engineExclude` maps an engine object (a mover set) to the Cesium
* primitive that draws it, or null for a Cesium object.
* @returns {{ surface: import('../contract.js').GlobeSurface, destroy: () => void }}
*/
export function createCesiumSurface(viewer) {
export function createCesiumSurface(
viewer,
{ engineExclude = () => null } = {},
) {
const { scene } = viewer;
const surface = {
sampleHeight(cartographic, exclude) {
if (!scene.sampleHeightSupported) return undefined;
try {
// Throws when unsupported (no depth textures); that is a miss.
return finite(scene.sampleHeight(cartographic, exclude));
} catch {
return undefined;
// Runs `query(nativeExclude)` with the engine objects in `exclude` hidden.
function excluding(exclude, query) {
if (!exclude?.length) return query(exclude);
let native = exclude;
const hidden = [];
for (const entry of exclude) {
const primitive = engineExclude(entry);
if (!primitive) continue;
if (native === exclude)
native = exclude.filter((other) => !engineExclude(other));
if (primitive.show) {
primitive.show = false;
hidden.push(primitive);
}
}
try {
return query(native);
} finally {
for (const primitive of hidden) primitive.show = true;
}
}
const sampleHeight = (cartographic, exclude) => {
if (!scene.sampleHeightSupported) return undefined;
try {
// Throws when unsupported (no depth textures); that is a miss.
return excluding(exclude, (native) =>
finite(scene.sampleHeight(cartographic, native)),
);
} catch {
return undefined;
}
};
const terrainHeight = (cartographic) =>
scene.globe ? finite(scene.globe.getHeight(cartographic)) : undefined;
const surface = {
sampleHeight,
// Cesium samples the tiles it has loaded (lod 'finest' cannot do better
// synchronously) and does not say which tile answered.
sampleHeightDetailed(cartographic, options) {
const { exclude } = normalizeSurfaceOptions(options);
const height = sampleHeight(cartographic, exclude);
if (height !== undefined) return { height, source: 'tiles' };
const terrain = terrainHeight(cartographic);
return terrain === undefined
? undefined
: { height: terrain, source: 'terrain' };
},
get supported() {
return Boolean(scene.sampleHeightSupported);
},
terrainHeight(cartographic) {
return scene.globe
? finite(scene.globe.getHeight(cartographic))
: undefined;
},
terrainHeight,
get terrainHeightSupported() {
return Boolean(scene.globe);
},
clampToHeight(position, exclude) {
if (!scene.clampToHeightSupported) return undefined;
try {
return toGeo3(scene.clampToHeight(position, exclude));
return excluding(exclude, (native) =>
toGeo3(scene.clampToHeight(position, native)),
);
} catch {
return undefined;
}