Files
gods-eye-view/src/layers/streetLevel/view.test.mjs
T
Sameh Khamis a10f3a16e1 Read Street Level's camera and ground through the renderer's ports
The Street Level view maths no longer reads Cesium. The camera's place
comes from the camera port's pose; the visible box and the view focus
cast the query port's screen rays and meet them with the ground, the
WGS84 ellipsoid raised to the ground height, in geo; heights come from
the query port; the horizon cull for the marker and the cones tests
against an ellipsoid 1,000 m below WGS84 in geo and re-culls on the
frame port's pre-render. Ground clicks, the screen-centre aim, the
nearest-image point, photo framing, the coverage refresh and the ground
re-measure read the same ports and convert positions with geo.

geo's ellipsoid functions (toLonLatH, rayEllipsoid and those under them)
and horizonFrom take an optional ellipsoid, made with ellipsoidOf or
offsetEllipsoid; anything else, a map index included, means WGS84. Tests
check them against Cesium on raised and lowered ellipsoids.

view, index, cameraFraming, groundClick and selection leave the Cesium
allow-list. The Street Level entries are Cesium-free callers of the
unbound factories: given a viewer of a caller's own, with no renderer
bound, the caller loads ./render/cesium/unbound first. GhostMaps, which
uses the horizon cull and is still on the list, loads the camera factory
itself.

Differences the contract does not let us avoid:
- The ground under the camera no longer reads whether the globe is shown
  (the globe port has no visibility getter). Where 3D tiles answer under
  the camera they decide, as they did under Google 3D; elsewhere the
  terrain answers, then the drawn surface below the camera. Over 3D tiles
  shown on a map with the globe (and under other primitives at the
  nadir) those now count as ground.
- Without depth-texture support the query port answers no heights, the
  terrain included, so the ground then reads as the ellipsoid.
- selection and groundClick still read the click dispatcher's own pick
  for now; they move to draw-set hits with the coverage lines.
2026-11-07 01:40:32 -08:00

430 lines
14 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import assert from 'node:assert/strict';
import test from 'node:test';
import * as Cesium from 'cesium';
import {
cameraNadir,
createHorizonCull,
groundUnderCamera,
metresBetween,
viewFocus,
visibleBbox,
} from './view.js';
import { latToTileY, lonToTileX, tilesForBbox } from './tileMath.js';
import { rayCamera, streetPorts } from '../../testSupport/streetLevelFakes.mjs';
import { bindFakeCesiumCamera } from '../../testSupport/fakeCameraPort.mjs';
import { bindRenderer } from '../../render/rendererOf.js';
const RAD = Math.PI / 180;
/** A viewer 300 m above a street 1,600 m up (Denver-like). */
function viewer({ globeShown, globeHeight }) {
const view = {
camera: {
positionCartographic: {
longitude: -104.99 * RAD,
latitude: 39.74 * RAD,
height: 1900,
},
},
scene: { globe: { show: globeShown, getHeight: () => globeHeight } },
};
return bindFakeCesiumCamera(view, streetPorts(view));
}
test('a shown globe answers the ground under the camera', () => {
assert.equal(
groundUnderCamera(viewer({ globeShown: true, globeHeight: 1600 })),
1600,
);
});
test('without 3D tiles under the camera the terrain answers; a missing sample gives no ground', () => {
// No tiles drawn there: the terrain answers, globe shown or hidden.
assert.equal(
groundUnderCamera(viewer({ globeShown: false, globeHeight: 0 })),
0,
);
assert.equal(
groundUnderCamera(viewer({ globeShown: true, globeHeight: undefined })),
null,
);
assert.equal(groundUnderCamera({}), null);
assert.equal(groundUnderCamera(null), null);
});
/** The Denver viewer with Google 3D: no globe, a sampleable rendered surface. */
function google3d(sample) {
const view = viewer({ globeShown: false, globeHeight: undefined });
view.scene.sampleHeightSupported = true;
view.scene.sampleHeight = () => sample;
return view;
}
test('on Google 3D the rendered surface answers the ground under the camera', () => {
assert.equal(groundUnderCamera(google3d(1612)), 1612);
});
test('where the 3D tiles answer, they decide, whatever the terrain says', () => {
const view = google3d(1612);
// A hidden globe's terrain can be stale (or the bare ellipsoid's 0).
view.scene.globe.getHeight = () => 0;
assert.equal(groundUnderCamera(view), 1612);
// A roof above the camera is not the ground, and tiles still loading
// (kilometres underground) are not either: unknown, so measured again.
view.scene.sampleHeight = () => 1950;
assert.equal(groundUnderCamera(view), null);
view.scene.sampleHeight = () => -14_886;
assert.equal(groundUnderCamera(view), null);
// No tiles there at all: the terrain answers.
view.scene.sampleHeight = () => undefined;
assert.equal(groundUnderCamera(view), 0);
});
test('an implausible or above-camera surface sample gives no ground', () => {
// Before tiles stream in, sampleHeight can read kilometres underground.
assert.equal(groundUnderCamera(google3d(-14_886)), null);
// A roof above the camera (1,900 m) would put the camera underground.
assert.equal(groundUnderCamera(google3d(1950)), null);
assert.equal(groundUnderCamera(google3d(undefined)), null);
});
/** A camera whose screen rays land on a grid of lon/lat points. */
function gridViewer(lons, lats) {
const points = [];
for (const lat of lats) for (const lon of lons) points.push([lon, lat]);
let next = 0;
const viewer = {};
bindRenderer(viewer, {
canvas: { clientWidth: 100, clientHeight: 100 },
camera: {
pose: () => ({ lon: 0, lat: 0, height: 1000 }),
},
query: {
// Straight down onto the next grid point, from 1 km above it.
pickRay() {
const [lon, lat] = points[next++ % points.length];
const origin = Cesium.Cartesian3.fromDegrees(lon, lat, 1000);
const ground = Cesium.Cartesian3.fromDegrees(lon, lat);
const direction = Cesium.Cartesian3.normalize(
Cesium.Cartesian3.subtract(ground, origin, new Cesium.Cartesian3()),
new Cesium.Cartesian3(),
);
return { origin, direction };
},
},
});
return viewer;
}
test('a view across the date line is a narrow box with west > east', () => {
const viewer = gridViewer([178, 179, -179, -178], [-1, 0, 1]);
const bbox = visibleBbox(viewer);
assert.ok(bbox[0] > 177 && bbox[0] < 179, `west ${bbox[0]}`);
assert.ok(bbox[2] < -177 && bbox[2] > -179, `east ${bbox[2]}`);
});
test('an ordinary view keeps west < east', () => {
const bbox = visibleBbox(gridViewer([10, 11, 12], [50, 51]));
assert.ok(bbox[0] < bbox[2]);
});
/** A pinhole viewer `agl` m above ground `ground` m up, looking north. */
function pinhole({ lon, lat, ground, agl, pitch, w = 1600, h = 900 }) {
const view = {
scene: {
canvas: { clientWidth: w, clientHeight: h },
globe: { show: false, ellipsoid: Cesium.Ellipsoid.WGS84 },
},
camera: rayCamera({
lon,
lat,
altitude: ground + agl,
pitch,
width: w,
height: h,
}),
};
return bindFakeCesiumCamera(view, streetPorts(view));
}
test('a tilted street view over high ground boxes the streets it looks at, not the horizon', () => {
// Denver, 600 m above a street 1,610 m up, looking 20° down: the centre of
// the screen meets the street about 1.65 km north of the camera.
const view = pinhole({
lon: -104.99,
lat: 39.74,
ground: 1610,
agl: 600,
pitch: -20,
});
const ahead = 39.74 + 1648 / 111_000;
const unranged = visibleBbox(view);
// Without options, rays to the bare ellipsoid travel 1.6 km further down:
// the box is 20 km wide and starts past the street at the screen centre.
assert.ok(unranged[2] - unranged[0] > 0.2);
assert.ok(unranged[1] > ahead, 'the old box missed the street in view');
const options = { groundHeight: 1610, maxRange: 6000 };
const [west, south, east, north] = visibleBbox(view, options);
assert.ok(north - south < 0.08 && east - west < 0.08, 'a street-sized box');
assert.ok(south < ahead && north > ahead, 'the screen centre is inside');
assert.ok(
south > 39.74,
'it starts ahead of the camera, where the view does',
);
assert.ok(west < -104.99 && east > -104.99);
const nadir = cameraNadir(view);
assert.ok(
Math.abs(nadir.lat - 39.74) < 1e-9 && Math.abs(nadir.lon + 104.99) < 1e-9,
);
});
test('a tilted view from 3 km loads the tile at the centre of the screen', () => {
// 3 km up, 70° from straight down: the screen centre meets the ground
// 8.2 km ahead, past the 3 × 3 z13 tiles around the camera's ground point.
const lon = -121.49;
const lat = 38.58;
const view = pinhole({ lon, lat, ground: 10, agl: 3000, pitch: -20 });
const ranged = { groundHeight: 10, maxRange: 30_000 };
const bbox = visibleBbox(view, ranged);
const ahead = lat + 3000 / Math.tan((20 * Math.PI) / 180) / 110_540;
const centreTile = `${lonToTileX(lon, 13)}/${latToTileY(ahead, 13)}`;
const chosen = (from) =>
tilesForBbox(bbox, 13, { limit: 9, from }).map(
(tile) => `${tile.x}/${tile.y}`,
);
assert.ok(
!chosen(cameraNadir(view)).includes(centreTile),
'ranked from the nadir alone, the screen centre is left out',
);
const focus = viewFocus(view, ranged);
assert.ok(focus.lat > lat && focus.lat < ahead, 'between camera and centre');
assert.ok(chosen(focus).includes(centreTile), 'the screen centre is loaded');
// The bottom edge of the screen (50° down) meets the ground 2.5 km ahead.
const nearest = lat + 3000 / Math.tan((50 * Math.PI) / 180) / 110_540;
assert.ok(
chosen(focus).includes(`${lonToTileX(lon, 13)}/${latToTileY(nearest, 13)}`),
'and so is the nearest ground in view',
);
});
test('looking straight down or at the sky, the focus is the ground under the camera', () => {
const lon = -121.49;
const lat = 38.58;
const down = viewFocus(
pinhole({ lon, lat, ground: 10, agl: 500, pitch: -90 }),
{ groundHeight: 10, maxRange: 5000 },
);
assert.ok(Math.abs(down.lat - lat) < 1e-4 && Math.abs(down.lon - lon) < 1e-4);
const sky = viewFocus(pinhole({ lon, lat, ground: 10, agl: 2, pitch: 60 }), {
groundHeight: 10,
maxRange: 2500,
});
assert.ok(Math.abs(sky.lat - lat) < 1e-9 && Math.abs(sky.lon - lon) < 1e-9);
});
test('looking at the horizon from eye height boxes the near ground, not the horizon', () => {
const view = pinhole({
lon: -121.4944,
lat: 38.5816,
ground: 10,
agl: 2,
pitch: -5,
});
const [west, south, east, north] = visibleBbox(view, {
groundHeight: 10,
maxRange: 2500,
});
assert.ok(south > 38.5816 && south - 38.5816 < 0.001, 'from just ahead');
assert.ok(north - 38.5816 < 2500 / 111_000, 'no further than the range');
assert.ok(west < -121.4944 && east > -121.4944);
// Looking at the sky, nothing is in range: no box, never the horizon's.
const sky = pinhole({
lon: -121.4944,
lat: 38.5816,
ground: 10,
agl: 2,
pitch: 60,
});
assert.equal(visibleBbox(sky, { groundHeight: 10, maxRange: 2500 }), null);
});
test('metresBetween measures the short way round the date line', () => {
const east = { lon: 179.9999, lat: 0 };
const west = { lon: -179.9999, lat: 0 };
// 0.0002° of longitude at the equator, not 40,000 km round the other way.
assert.ok(Math.abs(metresBetween(east, west) - 22.264) < 1e-6);
assert.ok(Math.abs(metresBetween(west, east) - 22.264) < 1e-6);
assert.ok(
Math.abs(
metresBetween({ lon: 180, lat: 0 }, { lon: -180, lat: 0.0001 }) - 11.054,
) < 1e-6,
'the two names of the same meridian',
);
// Away from the date line nothing changes.
assert.ok(
Math.abs(
metresBetween({ lon: 10, lat: 0 }, { lon: 10.001, lat: 0 }) - 111.32,
) < 1e-9,
);
});
/**
* A horizon cull over `items` for a camera the test moves, with the frame's
* pre-render listeners and a count of the camera poses read.
*/
function cullHarness(t, items) {
const preRender = new Set();
let eye = Cesium.Cartesian3.fromDegrees(0, 0, 1e7);
let poses = 0;
const viewer = {};
bindRenderer(viewer, {
camera: {
pose: () => {
poses++;
return { lon: 0, lat: 0, height: 1e7, position: { ...eye } };
},
},
frame: {
on(phase, listener) {
assert.equal(phase, 'preRender');
preRender.add(listener);
return () => preRender.delete(listener);
},
},
});
// Items handed to a cull pass: what a still camera must not test again.
const tested = { count: 0 };
let changes = 0;
const cull = createHorizonCull({
getViewer: () => viewer,
items: () => {
tested.count += items.length;
return items;
},
onChange: () => changes++,
});
return {
cull,
preRender,
poses: () => poses,
tested: () => tested.count,
changes: () => changes,
frame: () => {
for (const listener of [...preRender]) listener();
},
moveTo: (lon, lat) => (eye = Cesium.Cartesian3.fromDegrees(lon, lat, 1e7)),
};
}
const point = (lon, lat) => ({
position: Cesium.Cartesian3.fromDegrees(lon, lat),
show: true,
});
test('the horizon cull does no work while the camera stands still', (t) => {
const near = point(0, 0);
const far = point(180, 0);
const h = cullHarness(t, [near, far]);
h.cull.update();
assert.equal(h.tested(), 2);
assert.deepEqual([near.show, far.show], [true, false]);
assert.equal(h.preRender.size, 1, 'listening for camera moves');
for (let i = 0; i < 5; i++) h.frame();
assert.equal(h.tested(), 2, 'a still camera re-culls nothing');
h.moveTo(180, 0);
h.frame();
assert.equal(h.tested(), 4, 'a moved camera re-culls everything once');
assert.deepEqual([near.show, far.show], [false, true]);
h.frame();
h.frame();
assert.equal(h.tested(), 4, 'and then rests again');
h.cull.stop();
assert.equal(h.preRender.size, 0);
});
test('the horizon cull stops listening once nothing is left, and starts again for new items', (t) => {
const items = [point(0, 0)];
const h = cullHarness(t, items);
h.cull.update();
assert.equal(h.preRender.size, 1);
// Every item goes (the tiles are dropped); the next camera move finds none.
items.length = 0;
h.moveTo(10, 0);
h.frame();
assert.equal(h.preRender.size, 0, 'the listener is removed');
// New items arrive: they are culled now, and camera moves are watched again.
const far = point(-170, 0);
items.push(far);
h.cull.update([far]);
assert.equal(far.show, false, 'culled on arrival');
assert.equal(h.preRender.size, 1, 'the listener is back');
h.moveTo(-170, 0);
h.frame();
assert.equal(far.show, true, 're-culled when the camera moves');
assert.equal(h.changes(), 2, 'a redraw for each change');
h.cull.stop();
});
/** A cull over `points` ([lon, lat, height]) seen from a camera at `camera`. */
function cullFrom(camera, points) {
const items = points.map(([lon, lat, height]) => ({
position: Cesium.Cartesian3.fromDegrees(lon, lat, height),
show: true,
}));
const viewer = {};
bindRenderer(viewer, {
camera: {
pose: () => ({
lon: camera[0],
lat: camera[1],
height: camera[2],
position: Cesium.Cartesian3.fromDegrees(...camera),
}),
},
frame: { on: () => () => {} },
});
const horizon = createHorizonCull({
getViewer: () => viewer,
items: () => items,
});
horizon.update();
horizon.stop();
return items.map((item) => item.show);
}
test('cones and the marker stay visible on ground below the WGS84 ellipsoid', () => {
// NYC at street level: eye 2.4 m above ground at -22 m, a cone 10 m away.
assert.deepEqual(
cullFrom([-74.006, 40.7128, -19.6], [[-74.006, 40.71289, -22]]),
[true],
);
// Colombo framing view: camera at -21 m, cones at -95 m about 80 m away.
assert.deepEqual(
cullFrom(
[79.8612, 6.9271, -21],
[
[79.8612, 6.92782, -95],
[79.86192, 6.9271, -95],
],
),
[true, true],
);
// Austin, ground well above the ellipsoid.
assert.deepEqual(
cullFrom([-97.7431, 30.2672, 132], [[-97.7431, 30.2681, 130]]),
[true],
);
});
test('the horizon cull still hides the far side of the Earth from orbit', () => {
assert.deepEqual(
cullFrom(
[0, 0, 20_000_000],
[
[10, 10, 0],
[180, 0, 0],
],
),
[true, false],
);
});