Files
gods-eye-view/src/render/cesium/cameraPort.test.mjs
T
manjunath22466 0a8899d439 test(camera): compare recorded camera traces within platform roundoff
The camera golden test compared the recorded traces byte for byte, so it
failed on arm64, where trigonometry differs from the committed traces in the
last bits (at most 2.1e-9 m on a height, 33 of 1,530 numbers). Compare
structure, keys, array lengths, counters and the viewport exactly, and other
numbers within 1e-8 m for positions and heights and 1e-14 otherwise; a
self-test rejects larger errors, NaN, null, strings and missing or extra
keys. The pose test compares pitch by its sine within 1e-12, as the
conformance suite does, and checks the canonical range. The golden file and
production camera code are unchanged.
2026-11-16 19:47:06 +05:30

527 lines
17 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.
/**
* The Cesium port's camera commands against the reference traces: the
* conformance camera checks run on the port over the same headless camera
* and virtual clock the traces were recorded with, so a mapping of the
* contract onto Cesium that differs from the recorder's shows.
*/
import assert from 'node:assert/strict';
import test from 'node:test';
import * as Cesium from 'cesium';
import {
CAMERA_SCRIPTS,
DEFAULT_TOLERANCE,
runConformance,
usesInput,
} from '../conformance/index.js';
import {
FRAME_MS,
dispatchPointer,
headlessCamera,
withVirtualClock,
} from './cameraGoldens.js';
import { createCesiumCamera } from './camera.js';
import { createCesiumPorts } from './ports.js';
import { bindRenderer, cameraOf } from '../rendererOf.js';
/** Records the headless scene cannot answer: they need the query port. */
const QUERY_RECORDS = new Set([
'project',
'pickEllipsoid',
'pickRay',
'occluded',
]);
/** Commands and records the port does not have yet. */
const MISSING = new Set([]);
const runnable = CAMERA_SCRIPTS.filter(
(script) =>
!usesInput(script) &&
script.steps.every(
(step) =>
!MISSING.has(step.do) &&
!MISSING.has(step.record) &&
!QUERY_RECORDS.has(step.record),
),
).map((script) => `camera.trace.${script.name}`);
/** The scripts that drive the camera by pointer and wheel. */
const INPUT_CHECKS = new Set(
CAMERA_SCRIPTS.filter(usesInput).map((s) => `camera.trace.${s.name}`),
);
const CHECKS = new Set([
...runnable,
'camera.flight.callbacks',
'camera.controls.settings',
]);
function headlessHarness(clock, { input = false } = {}) {
return {
name: 'cesium (headless camera)',
async create() {
const { scene } = headlessCamera({ input });
for (const name of ['preUpdate', 'postUpdate', 'preRender', 'postRender'])
scene[name] = new Cesium.Event();
scene.primitives = { add() {}, remove() {} };
scene.requestRender = () => {};
clock.now = 0;
const capabilities = new Set(['cameraChangeThreshold']);
const ports = createCesiumPorts(
{ scene, clock: { currentTime: Cesium.JulianDate.now() } },
{ capabilities },
);
return {
capabilities,
camera: ports.camera,
query: ports.query,
destroy: () => ports.dispose(),
frameScene() {
clock.now += FRAME_MS;
scene.tweens.update();
if (input) scene.screenSpaceCameraController.update();
scene.preUpdate.raiseEvent(scene);
scene.postUpdate.raiseEvent(scene);
},
scene,
};
},
...(input
? {
cameraInput: true,
// The contract's event back as the DOM's, a wheel in lines: at 40
// px a line, Cesium reads the pixels the script scrolled.
pointer: (r, type, x, y, extra) =>
dispatchPointer(r.scene, {
type,
position: { x, y },
endPosition: extra.endPosition,
button: extra.button ?? 0,
modifiers: extra.modifiers,
...(type === 'wheel'
? { wheel: { deltaY: extra.delta, deltaMode: 1 } }
: {}),
}),
}
: {}),
frame: async (r) => r.frameScene(),
now: () => clock.now,
toEcef: (p) => {
const e =
'lon' in p
? Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height ?? 0)
: p;
return { x: e.x, y: e.y, z: e.z };
},
tolerance: DEFAULT_TOLERANCE,
flightPaths: 'trace',
};
}
test('the camera port retraces the reference flights, views and frames', async () => {
assert.ok(runnable.length >= 10, `only ${runnable.length} scripts run`);
const report = await withVirtualClock((clock) =>
runConformance(headlessHarness(clock), { only: (id) => CHECKS.has(id) }),
);
const failed = report.results.filter((r) => r.status === 'fail');
assert.deepEqual(
failed.map((r) => `${r.id}: ${r.detail}`),
[],
);
assert.equal(report.passed, CHECKS.size);
});
test('Cesium’s own controls under the camera port retrace the drags and wheels, each wheel sent back in the input port’s lines', async () => {
assert.ok(INPUT_CHECKS.size >= 4, `only ${INPUT_CHECKS.size} input scripts`);
const report = await withVirtualClock((clock) =>
runConformance(headlessHarness(clock, { input: true }), {
only: (id) => INPUT_CHECKS.has(id),
}),
);
assert.deepEqual(
report.results
.filter((r) => r.status !== 'pass')
.map((r) => `${r.id}: ${r.status} ${r.detail}`),
[],
);
assert.equal(report.passed, INPUT_CHECKS.size);
});
test('a cancelled flight has let go before its callbacks, so they can fly again', async () => {
await withVirtualClock(async (clock) => {
const { scene, camera } = headlessCamera();
scene.postUpdate = new Cesium.Event();
scene.requestRender = () => {};
const port = createCesiumCamera({
scene,
camera,
report: (error) => {
throw error;
},
}).port;
const seen = [];
let replacement = null;
port.flyTo(
{ lon: 0, lat: 0, height: 1e6 },
{
durationS: 1,
onCancel: () => {
seen.push(['cancelled, flying', port.flying]);
replacement = port.flyTo(
{ lon: 1, lat: 1, height: 1e6 },
{ durationS: 0.2, onComplete: () => seen.push(['replaced']) },
);
},
},
);
port.cancelFlight();
assert.deepEqual(seen, [['cancelled, flying', false]]);
assert.ok(port.flying, 'the replacement flies');
for (let i = 0; i < 30 && port.flying; i++) {
clock.now += FRAME_MS;
scene.tweens.update();
}
assert.equal(await replacement.done, 'complete');
assert.deepEqual(seen.at(-1), ['replaced']);
// Superseded by a new flyTo: the old one's onCancel still runs inside
// that call, and sees the new flight flying.
const order = [];
port.flyTo(
{ lon: 2, lat: 2, height: 1e6 },
{
durationS: 1,
onCancel: () => order.push(['old cancelled', port.flying]),
},
);
port.flyTo({ lon: 3, lat: 3, height: 1e6 }, { durationS: 1 });
assert.deepEqual(order, [['old cancelled', true]]);
});
});
function headlessPort() {
const { scene, camera } = headlessCamera();
scene.postUpdate = new Cesium.Event();
scene.requestRender = () => {};
const port = createCesiumCamera({
scene,
camera,
report: (error) => {
throw error;
},
}).port;
return { scene, camera, port };
}
test('commands announce themselves first; flights raise flightEnd once each', () => {
const { port } = headlessPort();
const seen = [];
const off = port.onCommand((c) => seen.push(c.kind));
port.on('flightEnd', () => seen.push('flightEnd'));
const target = Cesium.Cartesian3.fromDegrees(0, 0, 0);
port.setView({ destination: { lon: 0, lat: 0, height: 1e6 } });
port.lookAt(target, { heading: 0, pitch: -0.5, range: 1000 });
port.release();
port.flyTo({ lon: 1, lat: 1, height: 1e6 }, { durationS: 1 });
port.flyToBounds({ center: target, radius: 10 }, { durationS: 1 });
port.cancelFlight();
off();
port.setView({ destination: { lon: 0, lat: 0, height: 1e6 } });
assert.deepEqual(seen, [
'setView',
'lookAt',
'release',
'flyTo',
'flyToBounds',
'flightEnd',
'cancelFlight',
'flightEnd',
]);
});
test('endFrame world ends a flight out of a lookAt frame', async () => {
await withVirtualClock(async (clock) => {
const { scene, port } = headlessPort();
const target = Cesium.Cartesian3.fromDegrees(0, 0, 0);
port.lookAt(target, { heading: 0, pitch: -0.5, range: 1000 });
assert.equal(port.pose().frameIsIdentity, false);
const flight = port.flyTo(
{ lon: 1, lat: 1, height: 5000 },
{ durationS: 0.2, endFrame: 'world' },
);
for (let i = 0; i < 30 && port.flying; i++) {
clock.now += FRAME_MS;
scene.tweens.update();
}
assert.equal(await flight.done, 'complete');
assert.equal(port.pose().frameIsIdentity, true);
});
});
test('a flight Cesium does not start ends cancelled rather than never', async () => {
const { camera, port } = headlessPort();
// Mid scene-mode morph Cesium returns without flying or calling back.
camera._mode = Cesium.SceneMode.MORPHING;
const flight = port.flyTo({ lon: 1, lat: 1, height: 1e6 }, { durationS: 1 });
assert.equal(await flight.done, 'cancelled');
assert.equal(port.flying, false);
});
test('a Cesium viewer with no renderer bound gets a camera port over its own camera', async () => {
await withVirtualClock(async () => {
const { scene, camera } = headlessCamera();
scene.postUpdate = new Cesium.Event();
scene.requestRender = () => {};
const viewer = { scene, camera };
const port = cameraOf(viewer);
assert.equal(cameraOf(viewer), port, 'one port per viewer');
let outcome = null;
port.flyTo(
{ lon: 2.35, lat: 48.86, height: 1500 },
{ durationS: 0, onComplete: () => (outcome = 'complete') },
);
assert.equal(outcome, 'complete');
const pose = port.pose();
assert.ok(
Math.abs(pose.lon - 2.35) < 1e-9 && Math.abs(pose.lat - 48.86) < 1e-9,
);
assert.ok(Math.abs(pose.height - 1500) < 1e-6);
assert.throws(() => cameraOf({ scene, camera: {} }), /no renderer camera/);
});
});
test('the camera port gives the clock its own tick back as it goes', () => {
const ownTick = Cesium.Clock.prototype.tick;
// A viewer with no renderer bound: its port goes when a renderer is bound.
{
const { scene, camera } = headlessCamera();
scene.postUpdate = new Cesium.Event();
scene.requestRender = () => {};
const viewer = { scene, camera, clock: new Cesium.Clock() };
cameraOf(viewer);
assert.notEqual(viewer.clock.tick, ownTick, 'measured as the tick starts');
bindRenderer(viewer, {});
assert.equal(viewer.clock.tick, ownTick, 'its own tick once unbound');
assert.equal(Object.hasOwn(viewer.clock, 'tick'), false);
}
// Wrapped again after the port: disposing leaves the later wrapper, and
// the port's own part of the tick measures nothing more.
{
const { scene, camera } = headlessCamera();
scene.postUpdate = new Cesium.Event();
scene.requestRender = () => {};
const clock = new Cesium.Clock();
const part = createCesiumCamera({
scene,
camera,
report: () => {},
widget: { clock },
});
const wrapped = clock.tick;
let later = 0;
clock.tick = function (...args) {
later += 1;
return wrapped.apply(this, args);
};
part.dispose();
let reads = 0;
const frustum = camera.frustum;
Object.defineProperty(camera, 'frustum', {
get: () => {
reads += 1;
return frustum;
},
configurable: true,
});
clock.tick();
assert.equal(later, 1, 'the later wrapper still runs');
assert.equal(reads, 0, 'the disposed port reads nothing');
}
});
test('setFov holds the vertical angle across resizes, and waits for a first one', () => {
const { scene, camera } = headlessCamera();
scene.postUpdate = new Cesium.Event();
scene.requestRender = () => {};
camera.frustum.aspectRatio = NaN;
const { port } = createCesiumCamera({ scene, camera, report: () => {} });
port.setFov({ vertical: 0.5 });
for (const aspect of [16 / 9, 0.6, 4 / 3]) {
camera.frustum.aspectRatio = aspect;
scene.postUpdate.raiseEvent(scene);
assert.ok(Math.abs(camera.frustum.fovy - 0.5) < 1e-12, `aspect ${aspect}`);
}
camera.switchToOrthographicFrustum();
assert.doesNotThrow(() => port.setFov({ vertical: 0.4 }));
assert.throws(() => port.setFov({ vertical: Math.PI }), RangeError);
assert.throws(() => port.setFov({ vertical: NaN }), RangeError);
});
test('setFov(null) gives the angle back: Cesium’s own fov again, kept as Cesium keeps it', () => {
const { scene, camera } = headlessCamera();
scene.postUpdate = new Cesium.Event();
scene.requestRender = () => {};
camera.frustum.aspectRatio = 16 / 9;
const own = camera.frustum.fov;
const { port } = createCesiumCamera({ scene, camera, report: () => {} });
port.setFov({ vertical: 0.5 });
port.setFov({ vertical: 0.3 });
scene.postUpdate.raiseEvent(scene);
port.setFov(null);
assert.equal(camera.frustum.fov, own, 'the fov it had before the first hold');
// Rotated to portrait: Cesium keeps its fov, which is now the vertical
// angle, rather than the held one.
camera.frustum.aspectRatio = 9 / 16;
scene.postUpdate.raiseEvent(scene);
assert.equal(camera.frustum.fov, own);
assert.ok(Math.abs(camera.frustum.fovy - own) < 1e-12);
});
test('a pose measures heading, pitch and roll as Cesium does, and leaves the camera as it was', () => {
const { camera, port } = headlessPort();
const bits = () =>
[
camera.positionWC,
camera.directionWC,
camera.upWC,
camera.rightWC,
camera.position,
camera.direction,
camera.up,
].flatMap((v) => [v.x, v.y, v.z]);
const views = [
{ heading: 0.3, pitch: -0.7, roll: 0 },
{ heading: 5.9, pitch: -Math.PI / 2, roll: 0 },
{ heading: 2.1, pitch: -0.05, roll: 0.4 },
{ heading: 0, pitch: Math.PI / 2 - 1e-5, roll: 0 },
{ heading: 4, pitch: 0.6, roll: 6 },
];
for (const [k, orientation] of views.entries()) {
port.setView({
destination: {
lon: -170 + 70 * k,
lat: -80 + 40 * k,
height: 3e3 * 10 ** k,
},
orientation,
});
if (k === 4)
camera.lookAtTransform(
Cesium.Transforms.eastNorthUpToFixedFrame(camera.positionWC),
);
const before = bits();
const pose = port.pose();
assert.deepEqual(bits(), before, 'the camera is not moved to measure it');
// Cesium's own reads move the camera there and back three times; the
// first, heading, is read as the pose reads it.
const heading = camera.heading;
const pitch = camera.pitch;
const roll = camera.roll;
assert.equal(pose.heading, heading, `heading ${k}`);
assert.ok(
pose.pitch >= -Math.PI / 2 && pose.pitch <= Math.PI / 2,
`canonical pitch ${k}`,
);
// Near vertical, acos amplifies last-bit direction differences. Match
// the conformance suite's well-conditioned pitch comparison.
assert.ok(
Math.abs(Math.sin(pose.pitch) - Math.sin(pitch)) < 1e-12,
`pitch ${k}`,
);
const turn = Math.abs(pose.roll - roll);
assert.ok(Math.min(turn, 2 * Math.PI - turn) < 1e-12, `roll ${k}`);
}
});
test('an unmoved camera answers its pose from the last read; any change reads it anew', () => {
const { camera, port } = headlessPort();
port.setView({
destination: { lon: 10, lat: 20, height: 5e5 },
orientation: { heading: 0.3, pitch: -0.7, roll: 0 },
});
// Read as Cesium answers now, without the memo. (Cesium measures heading,
// pitch and roll by moving the camera there and back, which can change
// its last bits, so the two are compared to within a whisker.)
const fresh = () => {
const carto = cartographic.get.call(camera);
return {
lon: Cesium.Math.toDegrees(carto.longitude),
lat: Cesium.Math.toDegrees(carto.latitude),
height: carto.height,
heading: camera.heading,
pitch: camera.pitch,
roll: camera.roll,
fovy: camera.frustum.fovy,
x: camera.positionWC.x,
};
};
const near = (pose) => {
const want = fresh();
const got = { ...pose, x: pose.position.x };
for (const [name, value] of Object.entries(want))
assert.ok(
Math.abs(got[name] - value) < 1e-6,
`${name}: ${got[name]} vs ${value}`,
);
};
// Counts the camera's cartographic position read: an answer from the
// memo reads none.
let reads = 0;
const cartographic = Object.getOwnPropertyDescriptor(
Cesium.Camera.prototype,
'positionCartographic',
);
Object.defineProperty(camera, 'positionCartographic', {
get() {
reads += 1;
return cartographic.get.call(this);
},
});
const a = port.pose();
reads = 0;
// A caller's own objects: changing them changes no later pose.
a.position.x = 0;
a.heading = 99;
const b = port.pose();
assert.equal(reads, 0, 'answered from the memo');
assert.notEqual(b, a);
assert.notEqual(b.position, a.position);
assert.notEqual(b.heading, 99);
near(b);
camera.moveRight(1000);
near(port.pose());
camera.twistRight(0.2);
near(port.pose());
// Cesium lets right drift a little from direction × up.
const right = port.pose().right;
camera.right = Cesium.Cartesian3.add(
camera.right,
Cesium.Cartesian3.multiplyByScalar(
camera.up,
0.05,
new Cesium.Cartesian3(),
),
new Cesium.Cartesian3(),
);
const drifted = camera.rightWC.x;
const after = port.pose().right.x;
assert.notEqual(after, right.x);
assert.equal(after, drifted);
camera.frustum.fov = 0.4;
assert.ok(Math.abs(port.pose().fovy - camera.frustum.fovy) < 1e-12);
assert.notEqual(port.pose().fovy, b.fovy);
camera.lookAtTransform(
Cesium.Transforms.eastNorthUpToFixedFrame(camera.positionWC),
);
assert.equal(port.pose().frameIsIdentity, false);
near(port.pose());
});
test('followFrame is there only with its capability', () => {
const { scene, camera } = headlessCamera();
scene.postUpdate = new Cesium.Event();
const make = (capabilities) =>
createCesiumCamera({ scene, camera, report: () => {}, capabilities }).port;
assert.equal(make(new Set()).followFrame, undefined);
assert.equal(typeof make(new Set(['followFrame'])).followFrame, 'function');
assert.equal(typeof make(undefined).followFrame, 'function');
});