mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
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.
162 lines
6.0 KiB
JavaScript
162 lines
6.0 KiB
JavaScript
/**
|
|
* @module queries/heights
|
|
* @description The one place height queries go: how high the rendered
|
|
* surface or the terrain is under a point, now or after streaming.
|
|
*
|
|
* `now()` answers from what is already loaded and may return `null`: tiles
|
|
* not streamed yet, no depth support, a point off screen. Every caller treats
|
|
* that as a miss, holding its last value or placing first and patching when
|
|
* `batch()` resolves. Cesium answers `now()` synchronously from the scene,
|
|
* so nothing changes on screen; a renderer that can only answer from a cache
|
|
* or asynchronously plugs in here without touching the callers.
|
|
*
|
|
* `against` picks the surface: `'surface'` is what is drawn (3D tiles and the
|
|
* globe), `'terrain'` the loaded terrain tiles alone. `exclude` lists what the
|
|
* query must see through, typically the caller's own markers.
|
|
*/
|
|
import * as Cesium from 'cesium';
|
|
|
|
/** @typedef {'surface'|'terrain'} HeightSurface */
|
|
/**
|
|
* A point in degrees, or a `Cesium.Cartographic` in radians.
|
|
* @typedef {{lon: number, lat: number}|Cesium.Cartographic} HeightPoint
|
|
*/
|
|
/**
|
|
* @typedef {object} HeightOptions
|
|
* @property {HeightSurface} [against] Default `'surface'`.
|
|
* @property {object[]} [exclude] Primitives and entities to see through.
|
|
*/
|
|
|
|
/** @type {WeakMap<object, HeightService>} scene -> service */
|
|
const services = new WeakMap();
|
|
|
|
const scratch = new Cesium.Cartographic();
|
|
|
|
/** `supported()` answers, shared so a per-frame check allocates nothing. */
|
|
const SUPPORT = [
|
|
[
|
|
Object.freeze({ surface: false, clamp: false }),
|
|
Object.freeze({ surface: false, clamp: true }),
|
|
],
|
|
[
|
|
Object.freeze({ surface: true, clamp: false }),
|
|
Object.freeze({ surface: true, clamp: true }),
|
|
],
|
|
];
|
|
|
|
const NO_OPTIONS = Object.freeze({});
|
|
|
|
/** Plain finite metres, or null. */
|
|
const metres = (height) => (Number.isFinite(height) ? height : null);
|
|
|
|
/**
|
|
* The point as a Cartographic in radians at height 0. Degrees go through a
|
|
* shared scratch unless `result` is given; a Cartographic is used as it is.
|
|
* @param {HeightPoint} point
|
|
* @param {Cesium.Cartographic} [result]
|
|
* @returns {Cesium.Cartographic|null}
|
|
*/
|
|
function cartographicOf(point, result = scratch) {
|
|
if (Number.isFinite(point?.longitude) && Number.isFinite(point?.latitude))
|
|
return point;
|
|
const lon = Number(point?.lon);
|
|
const lat = Number(point?.lat);
|
|
if (!Number.isFinite(lon) || !Number.isFinite(lat)) return null;
|
|
return Cesium.Cartographic.fromDegrees(lon, lat, 0, result);
|
|
}
|
|
|
|
/**
|
|
* @typedef {object} HeightService
|
|
* @property {(point: HeightPoint, options?: HeightOptions) => number|null} now
|
|
* Height in metres above the ellipsoid from what is loaded, or null.
|
|
* @property {(position: Cesium.Cartesian3, options?: {exclude?: object[]}) => Cesium.Cartesian3|null} clampNow
|
|
* `position` moved onto the drawn surface along the ellipsoid normal, or null.
|
|
* @property {(points: HeightPoint[], options?: HeightOptions) => Promise<Array<number|null>>} batch
|
|
* Heights once the most detailed tiles have streamed; null per miss. A
|
|
* failed query (a tile request error, a destroyed scene) rejects, so the
|
|
* caller can tell it from points that are merely uncovered.
|
|
* @property {(positions: Cesium.Cartesian3[], options?: {exclude?: object[]}) => Promise<Array<Cesium.Cartesian3|null>>} clampBatch
|
|
* Clamped copies of `positions`; null per miss, rejecting as `batch` does.
|
|
* @property {() => {surface: boolean, clamp: boolean}} supported
|
|
* Whether the drawn surface can be queried at all (Cesium needs depth
|
|
* textures); terrain queries are always attempted.
|
|
*/
|
|
|
|
/**
|
|
* The scene's height service, made on first use.
|
|
* @param {object} scene A Cesium scene (or a test double).
|
|
* @returns {HeightService}
|
|
*/
|
|
export function heightsFor(scene) {
|
|
let service = services.get(scene);
|
|
if (!service) {
|
|
service = createHeights(scene);
|
|
services.set(scene, service);
|
|
}
|
|
return service;
|
|
}
|
|
|
|
function createHeights(scene) {
|
|
const terrainProvider = () =>
|
|
scene.terrainProvider ?? scene.globe?.terrainProvider;
|
|
|
|
return {
|
|
now(point, { against = 'surface', exclude } = NO_OPTIONS) {
|
|
const carto = cartographicOf(point);
|
|
if (!carto) return null;
|
|
try {
|
|
if (against === 'terrain')
|
|
return metres(scene.globe?.getHeight?.(carto));
|
|
// Cesium throws without depth-texture support: that is a miss.
|
|
return metres(scene.sampleHeight?.(carto, exclude));
|
|
} catch {
|
|
return null;
|
|
}
|
|
},
|
|
|
|
clampNow(position, { exclude } = NO_OPTIONS) {
|
|
if (!position) return null;
|
|
try {
|
|
return scene.clampToHeight?.(position, exclude) ?? null;
|
|
} catch {
|
|
return null;
|
|
}
|
|
},
|
|
|
|
async batch(points, { against = 'surface', exclude } = NO_OPTIONS) {
|
|
const cartos = points.map((point) => {
|
|
const carto = cartographicOf(point, new Cesium.Cartographic());
|
|
return (
|
|
carto && new Cesium.Cartographic(carto.longitude, carto.latitude)
|
|
);
|
|
});
|
|
const valid = cartos.filter(Boolean);
|
|
if (!valid.length) return cartos.map(() => null);
|
|
if (against === 'terrain') {
|
|
const provider = terrainProvider();
|
|
if (!provider) return cartos.map(() => null);
|
|
await Cesium.sampleTerrainMostDetailed(provider, valid);
|
|
} else {
|
|
if (typeof scene.sampleHeightMostDetailed !== 'function')
|
|
return cartos.map(() => null);
|
|
await scene.sampleHeightMostDetailed(valid, exclude);
|
|
}
|
|
return cartos.map((carto) => (carto ? metres(carto.height) : null));
|
|
},
|
|
|
|
async clampBatch(positions, { exclude } = NO_OPTIONS) {
|
|
if (typeof scene.clampToHeightMostDetailed !== 'function')
|
|
return positions.map(() => null);
|
|
const clones = positions.map((p) => Cesium.Cartesian3.clone(p));
|
|
const clamped = await scene.clampToHeightMostDetailed(clones, exclude);
|
|
return clamped.map((p) => p ?? null);
|
|
},
|
|
|
|
supported() {
|
|
return SUPPORT[+(scene.sampleHeightSupported === true)][
|
|
+(scene.clampToHeightSupported === true)
|
|
];
|
|
},
|
|
};
|
|
}
|