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.
This commit is contained in:
German Khokhlov committed 2026-10-16 20:26:43 +04:00
1 parent a89719aba9
commit f640890cf6
24 files changed
+1226 -218

No files matched your search

+129
View File
@@ -0,0 +1,129 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import * as geo from '../geo/index.js';
import { createEngineEvent } from './contract.js';
import {
MIN_FOLLOW_RANGE_M,
createFollowController,
enuOffset,
followPose,
} from './follow.js';
const { cartesian3 } = geo;
function harness() {
let pose = {
position: cartesian3.fromDegrees(0, 0, 1e7),
direction: cartesian3.create(-1, 0, 0),
up: cartesian3.create(0, 0, 1),
};
const commanded = createEngineEvent();
const frame = createEngineEvent();
let renders = 0;
const controller = createFollowController({
camera: { pose: () => pose, commanded },
aim: (next) => {
pose = next;
},
frame,
requestRender: () => renders++,
});
return {
controller,
frame: () => frame.raiseEvent(),
pose: () => pose,
move: (next) => {
pose = next;
},
command: () => commanded.raiseEvent(),
renders: () => renders,
};
}
const target0 = cartesian3.fromDegrees(-74, 40.7, 1000);
test('the follow pose looks at the target from its ENU offset', () => {
const pose = followPose(target0, cartesian3.create(0, -400, 300), 150);
assert.ok(Math.abs(cartesian3.distance(pose.position, target0) - 500) < 1e-6);
const back = enuOffset(target0, pose.position);
assert.ok(Math.abs(back.y + 400) < 1e-6 && Math.abs(back.z - 300) < 1e-6);
const toTarget = cartesian3.normalize(
cartesian3.subtract(target0, pose.position, cartesian3.create()),
cartesian3.create(),
);
assert.ok(cartesian3.dot(toTarget, pose.direction) > 1 - 1e-12);
assert.ok(Math.abs(cartesian3.dot(pose.up, pose.direction)) < 1e-12);
// Inside the minimum range: pushed out along the same direction.
const near = followPose(target0, cartesian3.create(0, -30, 40), 150);
assert.ok(Math.abs(cartesian3.distance(near.position, target0) - 150) < 1e-6);
});
test('a follow carries the camera with the target, keeps user changes, ends on a command', () => {
const h = harness();
let target = target0;
const changes = [];
h.controller.followChanged.addEventListener((handle) => changes.push(handle));
const handle = h.controller.follow({
position: () => target,
viewFrom: cartesian3.create(0, -400, 300),
});
assert.equal(h.controller.following(), handle);
h.frame();
assert.ok(
Math.abs(cartesian3.distance(h.pose().position, target) - 500) < 1e-6,
);
// The target moves 250 m east: the camera moves with it.
target = cartesian3.fromDegrees(-74 + 250 / 84_400, 40.7, 1000);
h.frame();
assert.ok(
Math.abs(cartesian3.distance(h.pose().position, target) - 500) < 1e-3,
);
// The user zooms in to 100 m: kept at the minimum range (150 m).
const pose = h.pose();
h.move({
...pose,
position: cartesian3.add(
pose.position,
cartesian3.multiplyByScalar(pose.direction, 400, cartesian3.create()),
cartesian3.create(),
),
});
h.frame();
assert.ok(
Math.abs(
cartesian3.distance(h.pose().position, target) - MIN_FOLLOW_RANGE_M,
) < 1e-3,
);
assert.ok(h.renders() >= 3, 'a follow keeps frames coming');
h.command();
assert.equal(h.controller.following(), null);
assert.deepEqual(changes, [handle, null]);
const before = h.pose();
h.frame();
assert.equal(h.pose(), before, 'no more steps after the end');
});
test('stop ends the follow; a new follow replaces the old one', () => {
const h = harness();
const first = h.controller.follow({
position: () => target0,
viewFrom: () => cartesian3.create(0, -1000, 500),
});
const second = h.controller.follow({
position: () => target0,
viewFrom: cartesian3.create(500, 0, 500),
});
assert.equal(h.controller.following(), second);
first.stop();
assert.equal(
h.controller.following(),
second,
'a stale handle stops nothing',
);
second.stop();
assert.equal(h.controller.following(), null);
assert.throws(
() => h.controller.follow({ position: 1, viewFrom: {} }),
TypeError,
);
});