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

+75 -28
View File
@@ -20,6 +20,7 @@ import {
Vector3,
} from 'three';
import * as geo from '../../geo/index.js';
import { normalizeSurfaceOptions } from '../surfaceDetail.js';
const { cartesian3, cartographic, math } = geo;
const WGS84 = geo.ellipsoid.WGS84;
@@ -62,17 +63,22 @@ const hasPositions = (object) =>
object.isMesh && Boolean(object.geometry?.attributes?.position?.array);
// The meshes with CPU positions under `object`, minus `exclude`, into
// `out`; with `shownOnly`, only through visible objects.
function collectMeshes(object, exclude, shownOnly, out) {
// `out`; with `shownOnly`, only through visible objects. `roots` (when
// given) gets the tile root of each mesh, at the same index.
function collectMeshes(object, exclude, shownOnly, out, roots, root) {
if (exclude.has(object) || (shownOnly && !object.visible)) return;
if (hasPositions(object)) out.push(object);
if (hasPositions(object)) {
out.push(object);
roots?.push(root);
}
const children = object.children;
for (let i = 0; i < children.length; i++)
collectMeshes(children[i], exclude, shownOnly, out);
collectMeshes(children[i], exclude, shownOnly, out, roots, root);
}
// Reused between calls (sampleHeight runs per frame in the ground floor).
const shownMeshes = [];
const shownRoots = [];
const tileMeshesScratch = [];
// Nearest hit along worldRay with one mesh, in metres. Not Mesh.raycast: that
@@ -114,25 +120,32 @@ function meshHitDistance(mesh, far) {
}
// Nearest hit over meshes, tried in the order the ray enters their bounding
// spheres; stops once the next sphere starts below the best hit.
function nearestHit(meshes, ray) {
// spheres; stops once the next sphere starts below the best hit. Returns
// the distance and the tile root (from `roots`) of the mesh hit.
function nearestHit(meshes, roots, ray) {
worldRay.origin.set(ray.origin.x, ray.origin.y, ray.origin.z);
worldRay.direction.set(ray.direction.x, ray.direction.y, ray.direction.z);
const candidates = [];
for (const mesh of meshes) {
for (let i = 0; i < meshes.length; i++) {
const mesh = meshes[i];
const geometry = mesh.geometry;
if (!geometry.boundingSphere) geometry.computeBoundingSphere();
sphere.copy(geometry.boundingSphere).applyMatrix4(mesh.matrixWorld);
if (!worldRay.intersectSphere(sphere, entry)) continue;
candidates.push([worldRay.origin.distanceTo(entry), mesh]);
candidates.push([worldRay.origin.distanceTo(entry), i]);
}
candidates.sort((x, y) => x[0] - y[0]);
let nearest = Infinity;
for (const [enter, mesh] of candidates) {
let root = null;
for (const [enter, i] of candidates) {
if (enter > nearest) break;
nearest = Math.min(nearest, meshHitDistance(mesh, ray.far));
const distance = meshHitDistance(meshes[i], ray.far);
if (distance < nearest) {
nearest = distance;
root = roots[i];
}
}
return nearest;
return { distance: nearest, root };
}
// A tile's extent: the bounding sphere around all its meshes, in
@@ -167,20 +180,22 @@ const NO_EXCLUDE = new Set();
// the top one among them. Tiles the ray passes are tried finest first, and
// coarser ones stop being tried once a hit sets the limit, so the coarse
// parents' triangles are never walked.
// With `includeShown` (lod 'finest') the shown tiles take part too.
const hiddenTiles = [];
function finestHiddenHit(roots, exclude, ray) {
function finestHiddenHit(roots, exclude, ray, includeShown = false) {
worldRay.origin.set(ray.origin.x, ray.origin.y, ray.origin.z);
worldRay.direction.set(ray.direction.x, ray.direction.y, ray.direction.z);
hiddenTiles.length = 0;
for (let i = 0; i < roots.length; i++) {
const root = roots[i];
if (root.visible || exclude.has(root)) continue;
if ((root.visible && !includeShown) || exclude.has(root)) continue;
const extent = tileExtent(root);
if (extent && worldRay.intersectsSphere(extent)) hiddenTiles.push(root);
}
hiddenTiles.sort((x, y) => extents.get(x).radius - extents.get(y).radius);
let limit = Infinity;
let nearest = Infinity;
let answered = null;
for (const root of hiddenTiles) {
const radius = extents.get(root).radius;
if (radius > limit) break;
@@ -191,12 +206,21 @@ function finestHiddenHit(roots, exclude, ray) {
hit = Math.min(hit, meshHitDistance(mesh, ray.far));
if (!Number.isFinite(hit)) continue;
if (limit === Infinity) limit = 1.5 * radius;
nearest = Math.min(nearest, hit);
if (hit < nearest) {
nearest = hit;
answered = root;
}
}
hiddenTiles.length = 0;
return nearest;
return { distance: nearest, root: answered };
}
// The size of a tile that answered: its extent's diameter.
const tileSizeOf = (root) => {
const extent = root ? tileExtent(root) : null;
return extent ? 2 * extent.radius : undefined;
};
/**
* @param {{ sampleTerrainHeight: (place: { lat: number, lng: number }) => number | undefined }} view
* @param {{
@@ -221,25 +245,48 @@ export function createNavaraSurface(view, hooks) {
});
return Number.isFinite(height) ? height : undefined;
};
const sampleHeight = (place, exclude) => {
if (!supported) return undefined;
const terrainDetail = (place) => {
const height = terrainHeight(place);
return height === undefined ? undefined : { height, source: 'terrain' };
};
const sampleHeightDetailed = (place, options) => {
const { exclude, lod } = normalizeSurfaceOptions(options);
if (!supported) return terrainDetail(place);
const ray = surfaceRay(place);
const roots = hooks.tileRoots();
const excluded = exclude ? new Set(exclude) : NO_EXCLUDE;
// The tiles on screen first; where they do not reach (the ground under
// a camera looking ahead is outside the frustum), the hidden ones.
shownMeshes.length = 0;
for (let i = 0; i < roots.length; i++)
collectMeshes(roots[i], excluded, true, shownMeshes);
let distance = nearestHit(shownMeshes, ray);
shownMeshes.length = 0;
if (!Number.isFinite(distance))
distance = finestHiddenHit(roots, excluded, ray);
return heightAlongRay(ray, distance) ?? terrainHeight(place);
const excluded = exclude.length ? new Set(exclude) : NO_EXCLUDE;
let hit = { distance: Infinity, root: null };
if (lod === 'visible') {
// The tiles on screen first; where they do not reach (the ground
// under a camera looking ahead is outside the frustum), the hidden
// ones.
shownMeshes.length = 0;
shownRoots.length = 0;
for (let i = 0; i < roots.length; i++)
collectMeshes(
roots[i],
excluded,
true,
shownMeshes,
shownRoots,
roots[i],
);
hit = nearestHit(shownMeshes, shownRoots, ray);
shownMeshes.length = 0;
shownRoots.length = 0;
}
if (!Number.isFinite(hit.distance))
hit = finestHiddenHit(roots, excluded, ray, lod === 'finest');
const height = heightAlongRay(ray, hit.distance);
if (height === undefined) return terrainDetail(place);
return { height, source: 'tiles', tileSizeM: tileSizeOf(hit.root) };
};
const sampleHeight = (place, exclude) =>
sampleHeightDetailed(place, exclude ? { exclude } : undefined)?.height;
return {
surface: {
sampleHeight,
sampleHeightDetailed,
supported,
terrainHeight,
terrainHeightSupported: true,
+40
View File
@@ -215,3 +215,43 @@ test('among hidden tiles the finest tile wins by its extent, not by a small mesh
'the fine tile',
);
});
test('sampleHeightDetailed names the source and the size of the answering tile', () => {
// A shown coarse tile (600 m wide, 3 m high) over a hidden fine one.
const fine = tileAt(10, 45, 40);
const coarse = tileAt(10, 45, 43, 300);
fine.tile.visible = false;
const { surface } = setup({
tiles: [coarse.tile, fine.tile],
terrain: () => 7,
});
const place = cartographic.fromDegrees(10, 45, 0);
const shown = surface.sampleHeightDetailed(place);
assert.equal(shown.source, 'tiles');
near(shown.height, 43, 0.05, 'the shown tile');
near(shown.tileSizeM, 600 * Math.SQRT2, 1, 'its size');
const finest = surface.sampleHeightDetailed(place, { lod: 'finest' });
near(finest.height, 40, 0.05, 'the finest loaded tile');
near(finest.tileSizeM, 200 * Math.SQRT2, 1, 'its size');
assert.deepEqual(
surface.sampleHeightDetailed(place, { exclude: [coarse.tile, fine.tile] }),
{ height: 7, source: 'terrain' },
);
assert.throws(
() => surface.sampleHeightDetailed(place, { lod: 'best' }),
TypeError,
);
const bare = setup({ tiles: [] }).surface;
assert.equal(bare.sampleHeightDetailed(place), undefined);
});
test('a hidden tile answer carries its size too', () => {
const fine = tileAt(10, 45, 40);
fine.tile.visible = false;
const { surface } = setup({ tiles: [fine.tile] });
const detail = surface.sampleHeightDetailed(
cartographic.fromDegrees(10, 45, 0),
);
near(detail.height, 40, 0.05, 'hidden fine');
near(detail.tileSizeM, 200 * Math.SQRT2, 1, 'size');
});