diff --git a/docs/APPLICATION.md b/docs/APPLICATION.md index dffad7908..026c76432 100644 --- a/docs/APPLICATION.md +++ b/docs/APPLICATION.md @@ -133,35 +133,41 @@ does this and returns the dispatcher as `scene.input`. ## Height queries -`gods-eye-view/queries/heights` exports `heightsFor(scene)`, the one place -height queries go. Layers, tools and the camera ask it instead of calling -`scene.sampleHeight`, `globe.getHeight`, `scene.clampToHeight` or the -`*MostDetailed` variants themselves, so a renderer that answers heights another -way plugs in without touching them. +`gods-eye-view/queries/heights` exports `heightsOf(viewer)`, the one place +height queries go. Layers, tools and the camera ask it instead of asking the +renderer's query port (`sampleHeight`, `sampleHeightNow`, `clampToSurface`) +or the scene themselves, so how the renderer answers heights can change +in without touching them. Pass the viewer the renderer is bound to, not its +scene. A viewer with no renderer bound is answered by the Cesium adapter's +fallback once the caller has loaded `gods-eye-view/render/cesium/unbound`; +until then, every query answers `null`. ```js -import { heightsFor } from 'gods-eye-view/queries/heights'; +import { heightsOf } from 'gods-eye-view/queries/heights'; -const heights = heightsFor(viewer.scene); -const ground = heights.now({ lon, lat }, { exclude: [ownMarkers] }); +const heights = heightsOf(viewer); +const ground = heights.now({ lon, lat }, { exclude: [ownSetId] }); if (ground !== null) place(ground); ``` | Member | What it answers | | ----------------------------- | ------------------------------------------------------------------------- | | `now(point, opts)` | Height in metres from what is loaded, or `null` | -| `clampNow(position, opts)` | The `Cartesian3` moved onto the drawn surface, or `null` | +| `clampNow(position, opts)` | The ECEF `{ x, y, z }` moved onto the drawn surface, or `null` | | `batch(points, opts)` | A promise of heights once the most detailed tiles stream; `null` per miss | -| `clampBatch(positions, opts)` | A promise of clamped copies of the positions; `null` per miss | +| `clampBatch(positions, opts)` | A promise of clamped `{ x, y, z }` copies; `null` per miss | | `supported()` | `{ surface, clamp }`: whether the drawn surface can be queried at all | -A point is `{ lon, lat }` in degrees or a `Cesium.Cartographic` in radians. +A point is `{ lon, lat }` in degrees or `{ longitude, latitude }` in radians. `against: 'surface'` (the default) reads what is drawn, 3D tiles and globe; -`against: 'terrain'` reads the loaded terrain tiles alone. `exclude` lists the -primitives and entities a query sees through. Every miss is `null`, including -a Cesium throw for missing depth-texture support, and every caller treats it -as one. Cesium answers `now()` synchronously from the scene, so it costs what -the direct call did. +`against: 'terrain'` reads the loaded terrain alone; `against: 'tiles'` the +tiles without the globe. Both `surface` and `tiles` include draw sets drawn +with `includeInHeightQueries`; `clampNow` and `clampBatch` always clamp to +the surface. `exclude` lists draw set ids to see through, of those drawn with +`includeInHeightQueries`; every other draw set is seen through already. Every +miss is `null`, and every caller treats it as one; `batch` and `clampBatch` +reject when the query itself fails. The Cesium renderer answers no height, +terrain included, without depth-texture support. ## Cesium internals diff --git a/src/queries/heights.js b/src/queries/heights.js index 09fde456a..eddb525e0 100644 --- a/src/queries/heights.js +++ b/src/queries/heights.js @@ -167,13 +167,24 @@ function createHeights(host) { }, async clampBatch(positions, { exclude } = NO_OPTIONS) { + // Copies taken now, so a caller changing its positions while the + // query runs cannot shift the answers. + const at = positions.map((p) => + finite(p) ? { x: p.x, y: p.y, z: p.z } : null, + ); + const valid = at.filter(Boolean); const port = asyncQuery(); - if (!port) return positions.map(() => null); + if (!valid.length || !port) return at.map(() => null); const clamped = await port.clampToSurface( - positions.map((p) => ({ x: p.x, y: p.y, z: p.z })), + valid, portOptions({ exclude }), ); - return clamped.map((p) => (finite(p) ? p : null)); + let next = 0; + return at.map((p) => { + if (!p) return null; + const result = clamped[next++]; + return finite(result) ? result : null; + }); }, supported() { diff --git a/src/queries/heights.test.mjs b/src/queries/heights.test.mjs index 91d3e3f88..2549bba82 100644 --- a/src/queries/heights.test.mjs +++ b/src/queries/heights.test.mjs @@ -183,6 +183,37 @@ test('clampBatch clamps copies and misses per position', async () => { ); }); +test('clampBatch answers null for a malformed position, sending only the rest', async () => { + const { viewer, calls } = bound({ + height: (point) => (point.lon > 0 ? 20 : 150), + }); + const result = await heightsOf(viewer).clampBatch([ + null, + fromDegrees(AUSTIN.lon, AUSTIN.lat, 0), + { x: Number.NaN, y: 0, z: 0 }, + fromDegrees(10, 10, 0), + ]); + assert.equal(result.length, 4); + assert.equal(result[0], null); + assert.ok(near(toLonLatH(result[1]).height, 150)); + assert.equal(result[2], null); + assert.ok(near(toLonLatH(result[3]).height, 20)); + assert.equal(calls.at(-1)[1].length, 2); +}); + +test('clampBatch keeps its answers in place when the caller changes its positions meanwhile', async () => { + const { viewer } = bound({ height: (point) => (point.lon > 0 ? 20 : 150) }); + const positions = [ + fromDegrees(AUSTIN.lon, AUSTIN.lat, 0), + fromDegrees(10, 10, 0), + ]; + const pending = heightsOf(viewer).clampBatch(positions); + positions[0].x = Number.NaN; + const [first, second] = await pending; + assert.ok(near(toLonLatH(first).height, 150)); + assert.ok(near(toLonLatH(second).height, 20)); +}); + test('supported reports the renderer’s sampleHeight capability', () => { assert.deepEqual(heightsOf(bound().viewer).supported(), { surface: true, @@ -214,11 +245,26 @@ test('height queries go through the service', () => { // that implement and call them: the Cesium adapter answers them through // this service. const CONTRACT = /^src\/render\/(contract|stub|conformance|cesium)\//; + // Sites that asked the query port's height members before this service + // went onto the port; each is to move onto `heightsOf`, and none is to be + // added. + const KNOWN = new Set([ + 'src/layers/alpr/overlay.js', + 'src/layers/alpr/presentation.js', + 'src/layers/streetLevel/cameraFraming.js', + 'src/layers/streetLevel/view.js', + ]); const NAMES = - 'sampleHeight|clampToHeight|sampleHeightMostDetailed|clampToHeightMostDetailed|getHeight'; + 'sampleHeight|sampleHeightNow|sampleHeightNowMany|clampToSurface|clampToHeight|sampleHeightMostDetailed|clampToHeightMostDetailed|getHeight'; const direct = new RegExp( `\\.(${NAMES})\\b|\\[\\s*['"\`](${NAMES})['"\`]\\s*\\]|\\bsampleTerrain(MostDetailed)?\\b`, ); + /** A file's code without its comments. */ + const codeOf = (file) => + fs + .readFileSync(path.join(ROOT, file), 'utf8') + .replace(/\/\*[\s\S]*?\*\//g, '') + .replace(/^\s*\/\/.*$/gm, ''); const walk = (dir) => fs .readdirSync(path.join(ROOT, dir), { withFileTypes: true }) @@ -228,13 +274,13 @@ test('height queries go through the service', () => { return /\.(js|vue)$/.test(entry.name) ? [rel] : []; }); const offenders = walk('src').filter((file) => { - if (file === SERVICE || CONTRACT.test(file.split(path.sep).join('/'))) + const posix = file.split(path.sep).join('/'); + if (file === SERVICE || CONTRACT.test(posix) || KNOWN.has(posix)) return false; - const code = fs - .readFileSync(path.join(ROOT, file), 'utf8') - .replace(/\/\*[\s\S]*?\*\//g, '') - .replace(/^\s*\/\/.*$/gm, ''); - return direct.test(code); + return direct.test(codeOf(file)); }); assert.deepEqual(offenders, []); + // A known site that has moved onto the service leaves the list. + const stale = [...KNOWN].filter((file) => !direct.test(codeOf(file))); + assert.deepEqual(stale, []); }); diff --git a/src/render/unboundCamera.test.mjs b/src/render/unboundCamera.test.mjs index 60d29df85..cedba7be8 100644 --- a/src/render/unboundCamera.test.mjs +++ b/src/render/unboundCamera.test.mjs @@ -84,6 +84,8 @@ const DRAW_FROM_CALLER = new Set([ './layers/street-level/kartaview', './layers/street-level/panoramax', './layers/air-quality', + // Asks `findQuery` instead, and answers null rather than throw until the + // caller has loaded the factory. './queries/heights', ]);