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

+23 -13
View File
@@ -3,10 +3,12 @@ import { isPickedWorldPosition } from '../data/scenePick.js';
import { isGlobeEngine } from '../globe/contract.js';
import { engineFromViewer } from '../globe/cesium/engineFromViewer.js';
// The camera is the globe engine's. Entity tracking stays on the Cesium viewer
// until phase 1c, so the viewer, when there is one, is only read for its
// tracked entity: callers pass an engine and that viewer, or a viewer whose
// engine is registered (engineFromViewer).
// The camera is the globe engine's, and so is the follow: the followed
// entity is engine.camera.following().native (on Cesium also an entity the
// app put on viewer.trackedEntity). The viewer, when there is one, is read
// only for its clock, and for its tracked entity when the engine reports no
// follow: callers pass an engine and that viewer, or a viewer whose engine
// is registered (engineFromViewer).
const engineOf = (target) => engineFromViewer(target);
const trackerOf = (target, tracker) =>
tracker ?? (target && !isGlobeEngine(target) ? target : null);
@@ -17,13 +19,17 @@ function cubicInOut(amount) {
return 0.5 * ((amount -= 2) * amount * amount + 2);
}
function trackedTarget(viewer) {
const entity = viewer.trackedEntity;
function followedEntity(engine, viewer) {
const handle = engine?.camera.following?.();
return handle ? (handle.native ?? null) : (viewer?.trackedEntity ?? null);
}
function trackedTarget(entity, viewer) {
// Read the visual's sample first; sampling a flight CallbackProperty twice
// can advance dead reckoning ahead of the displayed aircraft.
return (
entity?.gevDisplayPosition?.() ||
entity?.position?.getValue(viewer.clock?.currentTime)
entity?.position?.getValue(viewer?.clock?.currentTime)
);
}
@@ -82,8 +88,9 @@ export function readCameraTargetFrame(target, tracker) {
const engine = engineOf(target);
if (!engine) return null;
const viewer = trackerOf(target, tracker);
const center = viewer?.trackedEntity
? trackedTarget(viewer)
const entity = followedEntity(engine, viewer);
const center = entity
? trackedTarget(entity, viewer)
: pickViewTarget(engine);
const pose = engine.camera.pose();
if (!center || !isPickedWorldPosition(pose.position)) return null;
@@ -127,7 +134,9 @@ export function setCameraTargetFrame(target, frame, tracker) {
const viewer = trackerOf(target, tracker);
const { camera } = engine;
try {
const trackedTransform = viewer?.trackedEntity ? camera.transform() : null;
const trackedTransform = followedEntity(engine, viewer)
? camera.transform()
: null;
camera.lookAt(frame.target, {
heading: normalizedHeading(frame.heading),
pitch: frame.pitch,
@@ -217,20 +226,20 @@ export function createCameraOrientationAnimator(
if (!engine) return false;
if (duration <= 0)
return setCameraTargetFrame(engine, { ...frame, ...destination }, viewer);
const entity = viewer?.trackedEntity;
const entity = followedEntity(engine, viewer);
pending = destination;
const start = now();
const headingDelta = geo.math.negativePiToPi(
destination.heading - frame.heading,
);
remove = engine.frames.preUpdate.addEventListener(() => {
if (engine.isDestroyed() || viewer?.trackedEntity !== entity) {
if (engine.isDestroyed() || followedEntity(engine, viewer) !== entity) {
cancel();
return;
}
const progress = geo.math.clamp((now() - start) / duration, 0, 1);
const eased = cubicInOut(progress);
const center = entity ? trackedTarget(viewer) : frame.target;
const center = entity ? trackedTarget(entity, viewer) : frame.target;
if (
!isPickedWorldPosition(center) ||
!setCameraTargetFrame(
@@ -397,6 +406,7 @@ export function bindCameraOrientationControls({
// The exact tilt state is refreshed once per gesture, not once per frame —
// moveEnd fires when the camera stops, which is where the pick is affordable.
subscribe(engine?.camera.moveEnd, refreshTilt);
subscribe(engine?.camera.followChanged, animator.cancel);
subscribe(viewer?.trackedEntityChanged, animator.cancel);
for (const type of ['pointerdown', 'wheel']) {
const canvas = engine?.host.canvas;
+4 -2
View File
@@ -5,8 +5,9 @@ import { LocationControls } from './location.js';
/**
* Own destination selection, lookup, orbit and world-jump lifetime. The camera
* is the globe `engine`'s; `viewer` is optional and only clears Cesium's
* tracked entity (entity tracking moves to the engine in phase 1c).
* is the globe `engine`'s, and a world jump stops its follow
* (`engine.camera.following()`); `viewer` is optional and only clears a
* Cesium tracked entity that no registered engine reports.
*/
export class LocationNavigation {
constructor({
@@ -355,6 +356,7 @@ export class LocationNavigation {
} catch {
/* best-effort release */
}
this.engine.camera.following()?.stop();
if (this.viewer) this.viewer.trackedEntity = undefined;
this.engine.camera.cancelFlight();
this.engine.camera.release();