Fly the camera through the renderer's camera port

The Cesium camera port moves into render/cesium/camera.js, with the
listener list and position conversion shared from common.js. It now
covers flights (flyTo, flyToBounds, cancelFlight, flying), lookAt and
release, command hooks, and a flightEnd event for the flights it starts.

A flight's end that Cesium raises inside one of the port's own calls is
delivered once Cesium's call returns, so its callback sees the flight
let go of. A flight Cesium declines to start, mid scene-mode morph,
ends as cancelled instead of never settling.

Flight traces run in Node on the recorder's headless camera with a
virtual clock; the browser harness keeps the instant traces.

The startup fly-in, landmark and viewport flights, share-link restore
and the shell's camera state now go through the port. camera.js and
sharelink.js leave the Cesium allow-list.
This commit is contained in:
Sameh Khamis committed 2026-11-05 20:15:52 -08:00
1 parent b5900b4178
commit 46a53bb49c
20 files changed
+846 -305

No files matched your search

+210
View File
@@ -0,0 +1,210 @@
/**
* 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,
} from '../conformance/index.js';
import { FRAME_MS, headlessCamera, withVirtualClock } from './cameraGoldens.js';
import { createCesiumCamera } from './camera.js';
import { createCesiumPorts } from './ports.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(['move', 'look', 'rotateAround', 'zoom', 'matrices']);
const runnable = CAMERA_SCRIPTS.filter((script) =>
script.steps.every(
(step) =>
!MISSING.has(step.do) &&
!MISSING.has(step.record) &&
!QUERY_RECORDS.has(step.record),
),
).map((script) => `camera.trace.${script.name}`);
const CHECKS = new Set([...runnable, 'camera.flight.callbacks']);
function headlessHarness(clock) {
return {
name: 'cesium (headless camera)',
async create() {
const { scene } = headlessCamera();
for (const name of ['preUpdate', 'postUpdate', 'preRender', 'postRender'])
scene[name] = new Cesium.Event();
scene.primitives = { add() {}, remove() {} };
scene.requestRender = () => {};
clock.now = 0;
const ports = createCesiumPorts(
{ scene, clock: { currentTime: Cesium.JulianDate.now() } },
{ capabilities: new Set() },
);
return {
camera: ports.camera,
query: ports.query,
destroy: () => ports.dispose(),
frameScene() {
clock.now += FRAME_MS;
scene.tweens.update();
scene.postUpdate.raiseEvent(scene);
},
};
},
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('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);
});