mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
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.
This commit is contained in:
1 parent
dd4f19967d
commit
ed8f89db74
4 files changed
+91
-26
No files matched your search
+22
-16
@@ -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
|
||||
|
||||
|
||||
+14
-3
@@ -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() {
|
||||
|
||||
@@ -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, []);
|
||||
});
|
||||
@@ -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',
|
||||
]);
|
||||
|
||||
|
||||
Reference in new issue
Block a user