Files
gods-eye-view/src/globe/cesium/follow.test.mjs
T
German Khokhlov f640890cf6 feat(globe): follow camera on both engines
camera.follow({ position, viewFrom, minRange = 150, native? }) keeps a
moving target centred at an east-north-up offset the user may turn and
zoom; camera.following() and camera.followChanged report it; stop() frees
the camera and a camera command (setView, flyTo, flyToSphere, lookAt,
cancelFlight) ends it.

Probe ruling: Navara 0.2.1's cameraFollow holds the target but ignores the
user's drag and wheel, the aircraft sits ~13 px off centre with 7.6 px of
spread, and calling it without an offset each frame gives a NaN camera.
So Navara (and the fake engine) follow with src/globe/follow.js: each
frame, before Navara draws, the offset is re-read from where the user put
the camera relative to the previous target, kept outside the minimum
range and carried to the new target.

Cesium follows with viewer.trackedEntity: the layer's own Entity
(`native`) or a proxy Entity at position() with a 1 px transparent point,
since EntityView moves the camera only for an entity with a bounding
sphere. applyTrackedCameraFrame and the zoom limits moved to
src/globe/cesium/follow.js; src/data/trackedCamera.js keeps the pure parts
(the range clamp now lives in src/globe/follow.js). following() also
reports an entity the app tracked itself. Camera sensitivity claims made
on a viewer's Cesium camera now share the engine camera's ledger, and the
orientation controls and the world jump read the follow from the engine.

Contract (both engines): a target flying at 250 m/s stays within 3 px of
the centre for 2 s, zoomIn through it stops at 150 m, stop() and setView
end the follow. Cesium 71/71, Navara 77/77; shell 23/25/4.
2026-10-16 20:26:43 +04:00

145 lines
5.4 KiB
JavaScript

import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import * as geo from '../../geo/index.js';
import { createCesiumCamera } from './camera.js';
import { createFakeViewer } from './testing/fakeViewer.mjs';
const TARGET = geo.cartesian3.fromDegrees(-73.78, 40.64, 3000);
function setup() {
const viewer = createFakeViewer();
const { camera, destroy } = createCesiumCamera(viewer);
const changes = [];
camera.followChanged.addEventListener((handle) => changes.push(handle));
const frame = () => viewer.scene.preUpdate.raiseEvent();
return { viewer, camera, destroy, changes, frame };
}
test('follow tracks a native entity: one exact frame, zoom limits, stop restores', () => {
const { viewer, camera, changes, frame } = setup();
const controller = viewer.scene.screenSpaceCameraController;
controller.inertiaZoom = 0.8;
controller.minimumZoomDistance = 1;
const native = new Cesium.Entity({
position: Cesium.Cartesian3.clone(TARGET),
viewFrom: new Cesium.Cartesian3(0, -900, 400),
});
const handle = camera.follow({
native,
position: () => TARGET,
viewFrom: { x: 0, y: -900, z: 400 },
});
assert.equal(viewer.trackedEntity, native);
assert.equal(camera.following(), handle);
assert.equal(handle.native, native);
assert.deepEqual(changes, [handle]);
assert.equal(controller.inertiaZoom, 0);
assert.equal(controller.minimumZoomDistance, 150);
frame();
frame();
const frames = viewer.callsOf('camera.lookAtTransform');
assert.equal(frames.length, 1, 'the tracked frame is applied once');
const [transform, offset] = frames[0].args;
assert.deepEqual([offset.x, offset.y, offset.z], [0, -900, 400]);
const enu = geo.transforms.eastNorthUpToFixedFrame(
TARGET,
geo.ellipsoid.WGS84,
);
for (let i = 0; i < 16; i++)
assert.ok(Math.abs(transform[i] - enu[i]) < 1e-6);
handle.stop();
assert.equal(viewer.trackedEntity, undefined);
assert.equal(camera.following(), null);
assert.deepEqual(changes, [handle, null]);
assert.equal(controller.inertiaZoom, 0.8);
assert.equal(controller.minimumZoomDistance, 1);
});
test('without native the follow tracks a proxy entity at position()', () => {
const { viewer, camera, frame } = setup();
let target = TARGET;
const handle = camera.follow({
position: () => target,
viewFrom: { x: 0, y: -500, z: 200 },
});
const proxy = viewer.trackedEntity;
assert.ok(viewer.entities.contains(proxy));
assert.equal(handle.native, undefined);
const time = viewer.clock.currentTime;
assert.ok(Cesium.Cartesian3.equals(proxy.position.getValue(time), TARGET));
target = geo.cartesian3.fromDegrees(-73.7, 40.6, 3000);
assert.ok(Cesium.Cartesian3.equals(proxy.position.getValue(time), target));
frame();
assert.equal(viewer.callsOf('camera.lookAtTransform').length, 1);
handle.stop();
assert.equal(viewer.entities.contains(proxy), false);
assert.equal(viewer.trackedEntity, undefined);
});
test('a camera command or another tracked entity ends the follow', () => {
const { viewer, camera, changes } = setup();
const options = { position: () => TARGET, viewFrom: { x: 0, y: -500, z: 0 } };
const first = camera.follow(options);
camera.setView({ destination: TARGET });
assert.equal(viewer.trackedEntity, undefined);
assert.equal(camera.following(), null);
assert.equal(viewer.entities.values.length, 0);
camera.follow(options);
const appEntity = new Cesium.Entity({ position: TARGET });
viewer.trackedEntity = appEntity;
assert.equal(viewer.entities.values.length, 0, 'the proxy is gone');
const wrapped = camera.following();
assert.equal(wrapped.native, appEntity);
assert.equal(camera.following(), wrapped, 'one handle per entity');
assert.equal(changes.at(-1), wrapped);
wrapped.stop();
assert.equal(viewer.trackedEntity, undefined);
assert.equal(changes.at(-1), null);
assert.ok(changes.includes(first));
});
test('a programmatic zoom inside the minimum range is pushed back to it', () => {
const { viewer, camera, frame } = setup();
camera.follow({ position: () => TARGET, viewFrom: { x: 0, y: -500, z: 0 } });
frame();
// zoomIn bypasses the controller's minimumZoomDistance.
Cesium.Cartesian3.fromElements(0, -20, 0, viewer.camera.position);
frame();
const range = Cesium.Cartesian3.magnitude(viewer.camera.position);
assert.ok(Math.abs(range - 150) < 1e-6, `range ${range}`);
});
test('retarget switches the tracked entity without ending the follow', () => {
const { viewer, camera, changes } = setup();
const handle = camera.follow({
position: () => TARGET,
viewFrom: { x: 0, y: -500, z: 0 },
});
const proxy = viewer.trackedEntity;
const native = new Cesium.Entity({ position: TARGET });
handle.retarget({ native });
assert.equal(viewer.trackedEntity, native);
assert.equal(viewer.entities.contains(proxy), false);
assert.equal(camera.following(), handle);
assert.deepEqual(changes, [handle, handle]);
});
test('destroy ends an engine follow and leaves an app-tracked entity alone', () => {
const first = setup();
first.camera.follow({
position: () => TARGET,
viewFrom: { x: 0, y: -500, z: 0 },
});
first.destroy();
assert.equal(first.viewer.trackedEntity, undefined);
assert.equal(first.viewer.entities.values.length, 0);
const second = setup();
const appEntity = new Cesium.Entity({ position: TARGET });
second.viewer.trackedEntity = appEntity;
second.destroy();
assert.equal(second.viewer.trackedEntity, appEntity);
});