Files
gods-eye-view/src/render/cesium/follow.test.mjs
T
Sameh Khamis e3a850bc9c Follow aircraft and satellites through the camera port
Flights and military follow their tracked aircraft with an
entityFollowTarget: framed in ENU from viewFrom, never closer than
150 m, presentation read from the drawn entity's record. Satellites
follow in Cesium's autodetect frame. The layers' own framing
(applyTrackedCameraFrame) goes; the port's follow has the same
close-range rules, and trackedCamera.js no longer imports Cesium.

The port's helper entity draws nothing: its point's outline is
transparent too, and click and voice picks of it count as picks of
the target's drawn entity. The fake camera binder follows when the
fake has Cesium's entity tracking.
2026-11-06 16:10:48 -08:00

273 lines
9.7 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 follow over a widget-shaped host: Cesium's own
* `trackedEntity` setter semantics (one change event per value, release to
* the world frame) on a headless camera, with `preUpdate` stepped by hand.
* The follow itself, frame after frame, is the browser conformance run's.
*/
import assert from 'node:assert/strict';
import test from 'node:test';
import * as Cesium from 'cesium';
import { headlessCamera } from './cameraGoldens.js';
import { createCesiumCamera } from './camera.js';
import { holdFollowZoom, pickThroughFollowHelper } from './follow.js';
function trackingHost() {
const { scene, camera } = headlessCamera();
for (const name of ['preUpdate', 'postUpdate', 'preRender', 'postRender'])
scene[name] = new Cesium.Event();
scene.requestRender = () => {};
scene.screenSpaceCameraController = {
inertiaZoom: 0.8,
minimumZoomDistance: 1,
};
const entities = new Cesium.EntityCollection();
const changed = new Cesium.Event();
let tracked;
const widget = {
scene,
camera,
entities,
clock: { currentTime: Cesium.JulianDate.fromDate(new Date(0)) },
trackedEntityChanged: changed,
get trackedEntity() {
return tracked;
},
// Cesium's setter: a change event per new value, and a release to the
// world frame without moving the eye.
set trackedEntity(value) {
if (tracked === value) return;
tracked = value;
if (!value) camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
changed.raiseEvent(value);
},
};
// Removing the tracked entity ends the tracking, as Cesium's does.
entities.collectionChanged.addEventListener((_c, _added, removed) => {
if (removed.includes(tracked)) widget.trackedEntity = undefined;
});
const part = createCesiumCamera({
scene,
camera,
widget,
report: (error) => {
throw error;
},
});
return { widget, scene, camera, port: part.port, dispose: part.dispose };
}
const AUSTIN = Cesium.Cartesian3.fromDegrees(-97.74, 30.27, 1000);
const target = (key, extra = {}) => ({
key,
position: () => ({ x: AUSTIN.x, y: AUSTIN.y, z: AUSTIN.z }),
frame: 'enu',
viewFrom: { x: 0, y: -800, z: 400 },
...extra,
});
test('follow announces each change once and keeps one helper entity', () => {
const h = trackingHost();
const seen = [];
h.port.on('followChanged', () => seen.push(h.port.followed?.key ?? null));
const a = target('a');
const b = target('b');
h.port.follow(a);
assert.equal(h.port.followed, a);
h.port.follow(b);
assert.equal(h.port.followed, b);
assert.equal(h.widget.entities.values.length, 1, 'the old helper is gone');
h.port.follow(null);
assert.equal(h.port.followed, null);
assert.equal(h.widget.entities.values.length, 0);
assert.deepEqual(seen, ['a', 'b', null]);
h.dispose();
});
test('tracking set elsewhere ends the follow', () => {
const h = trackingHost();
h.port.follow(target('a'));
const other = h.widget.entities.add({ position: AUSTIN });
h.widget.trackedEntity = other;
assert.equal(h.port.followed, null);
assert.deepEqual(
h.widget.entities.values,
[other],
'the helper went with it',
);
h.dispose();
});
test('an ENU follow frames exactly at viewFrom, scaled up to its minimum range', () => {
const h = trackingHost();
h.port.follow(
target('a', { viewFrom: { x: 0, y: -60, z: 80 }, minRange: 150 }),
);
assert.equal(h.port.followFramed, false);
assert.equal(h.port.followOffset.get(), null);
h.scene.preUpdate.raiseEvent(h.scene);
assert.equal(h.port.followFramed, true);
const offset = h.port.followOffset.get();
assert.ok(Math.abs(Math.hypot(offset.x, offset.y, offset.z) - 150) < 1e-6);
assert.ok(Math.abs(offset.y / offset.z - -60 / 80) < 1e-9, 'same bearing');
const eye = h.camera.positionWC;
assert.ok(Math.abs(Cesium.Cartesian3.distance(eye, AUSTIN) - 150) < 1e-6);
h.dispose();
});
test('within minRange the eye is put back, and the offset can be set', () => {
const h = trackingHost();
h.port.follow(target('a', { minRange: 150 }));
h.scene.preUpdate.raiseEvent(h.scene);
// A programmatic zoom past the floor, as the controller's would not.
h.camera.zoomIn(Cesium.Cartesian3.magnitude(h.camera.position) - 20);
h.scene.preUpdate.raiseEvent(h.scene);
const range = Cesium.Cartesian3.magnitude(h.camera.position);
assert.ok(Math.abs(range - 150) < 1e-6, `range ${range}`);
h.port.followOffset.set({ x: 0, y: -2000, z: 1000 });
const offset = h.port.followOffset.get();
assert.deepEqual(
[offset.x, offset.y, offset.z].map(Math.round),
[0, -2000, 1000],
);
h.dispose();
});
test('a follow with a minimum range holds the zoom floor and stops coasting', () => {
const h = trackingHost();
const controller = h.scene.screenSpaceCameraController;
h.port.follow(target('a', { minRange: 150 }));
assert.equal(controller.inertiaZoom, 0);
assert.equal(controller.minimumZoomDistance, 150);
h.port.follow(target('b'));
assert.equal(controller.inertiaZoom, 0.8, 'restored for a follow without');
assert.equal(controller.minimumZoomDistance, 1);
h.dispose();
});
test('zoom floors from several owners take the highest, and restore last', () => {
const controller = { inertiaZoom: 0.5, minimumZoomDistance: 10 };
const a = {};
const b = {};
const releaseA = holdFollowZoom(controller, a, 150);
const releaseB = holdFollowZoom(controller, b, 400);
assert.equal(controller.minimumZoomDistance, 400);
releaseB();
assert.equal(controller.minimumZoomDistance, 150);
assert.equal(controller.inertiaZoom, 0);
releaseA();
releaseA();
assert.deepEqual(controller, { inertiaZoom: 0.5, minimumZoomDistance: 10 });
});
test('dispose ends a follow it still has', () => {
const h = trackingHost();
h.port.follow(target('a'));
h.dispose();
assert.equal(h.widget.trackedEntity, undefined);
assert.equal(h.widget.entities.values.length, 0);
});
test('a camera without entity tracking cannot follow', () => {
const { scene, camera } = headlessCamera();
for (const name of ['postUpdate']) scene[name] = new Cesium.Event();
const { port } = createCesiumCamera({ scene, camera, report: () => {} });
assert.throws(() => port.follow(target('a')), /cannot follow/);
assert.equal(port.followed, null);
assert.equal(port.followOffset.get(), null);
});
test('Cesium frames from viewFrom put out to the minimum range too', () => {
const h = trackingHost();
h.port.follow(
target('a', { viewFrom: { x: 0, y: -60, z: 80 }, boundingRadius: 500 }),
);
const [helper] = h.widget.entities.values;
const v = helper.viewFrom.getValue(h.widget.clock.currentTime);
assert.ok(Math.abs(Cesium.Cartesian3.magnitude(v) - 500) < 1e-6);
h.dispose();
});
test('targets are asked for their position at sub-millisecond scene time', () => {
const h = trackingHost();
const asked = [];
h.port.follow(
target('a', {
position: (t) => {
asked.push(t);
return { x: AUSTIN.x, y: AUSTIN.y, z: AUSTIN.z };
},
}),
);
const [helper] = h.widget.entities.values;
const at = Cesium.JulianDate.fromDate(new Date(Date.UTC(2026, 10, 6)));
helper.position.getValue(at);
helper.position.getValue(Cesium.JulianDate.addSeconds(at, 0.0005, at));
assert.equal(asked.at(-2), Date.UTC(2026, 10, 6));
assert.ok(Math.abs(asked.at(-1) - asked.at(-2) - 0.5) < 1e-6);
h.dispose();
});
test('a target without a position gives up framing after 120 frames', () => {
const h = trackingHost();
const controller = h.scene.screenSpaceCameraController;
h.port.follow(target('a', { position: () => null, minRange: 150 }));
for (let i = 0; i < 119; i++) h.scene.preUpdate.raiseEvent(h.scene);
assert.equal(controller.inertiaZoom, 0, 'still waiting');
h.scene.preUpdate.raiseEvent(h.scene);
assert.equal(h.port.followFramed, false);
assert.equal(controller.inertiaZoom, 0.8, 'the zoom hold let go');
assert.equal(h.port.followed?.key, 'a', 'Cesium still tracks it');
h.dispose();
});
test('followChanged fires only when what is followed changes', () => {
const h = trackingHost();
let count = 0;
h.port.on('followChanged', () => (count += 1));
h.port.follow(null);
// A layer tracking an entity of its own, while the port follows nothing.
const other = h.widget.entities.add({ position: AUSTIN });
h.widget.trackedEntity = other;
h.widget.trackedEntity = undefined;
assert.equal(count, 0);
h.port.follow(target('a'));
assert.equal(count, 1);
// The helper removed from outside ends the follow, announced once.
h.widget.entities.removeAll();
assert.equal(h.port.followed, null);
assert.equal(count, 2);
h.dispose();
});
test('an autodetected follow is framed once Cesium tracks its helper', () => {
const h = trackingHost();
h.port.follow(target('a', { frame: 'autodetect' }));
h.scene.preUpdate.raiseEvent(h.scene);
assert.equal(h.port.followFramed, false);
const [helper] = h.widget.entities.values;
// Cesium's EntityView, as CesiumWidget builds it once the sphere is ready.
h.widget._entityView = { entity: helper };
h.scene.preUpdate.raiseEvent(h.scene);
assert.equal(h.port.followFramed, true);
h.dispose();
});
test('a pick of the helper is a pick of the target’s drawn entity', () => {
const h = trackingHost();
const drawn = h.widget.entities.add({ position: AUSTIN });
h.port.follow(target('a', { entity: drawn }));
const helper = h.widget.entities.values.find((e) => e !== drawn);
const primitive = {};
assert.deepEqual(pickThroughFollowHelper({ id: helper, primitive }), {
id: drawn,
primitive,
});
h.port.follow(target('b'));
const bare = h.widget.entities.values.find((e) => e !== drawn);
assert.equal(pickThroughFollowHelper({ id: bare }), undefined);
const other = { id: drawn };
assert.equal(pickThroughFollowHelper(other), other);
assert.equal(pickThroughFollowHelper(undefined), undefined);
h.dispose();
});