From ed8f89db74831026f24215dc9bcecc776ddc8651 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 7 Nov 2026 03:04:28 -0800 Subject: [PATCH] Document the height gateway on the query port and tighten its scan The application guide now describes heightsOf(viewer): draw set ids to see through, plain ECEF results, the surfaces each option reads, and that the Cesium renderer answers no height without depth textures. clampBatch answers null for a malformed position instead of throwing, and copies the positions before the query runs so the answers stay in place. The source scan also flags the query port's sampleHeightNow, sampleHeightNowMany and clampToSurface outside the gateway; the four sites that already asked the port directly are listed, and the list fails once one of them no longer needs it. --- docs/APPLICATION.md | 38 +++++++++++--------- src/queries/heights.js | 17 +++++++-- src/queries/heights.test.mjs | 60 +++++++++++++++++++++++++++---- src/render/unboundCamera.test.mjs | 2 ++ 4 files changed, 91 insertions(+), 26 deletions(-) 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', ]);