Files
gods-eye-view/src/globe/cesium/follow.js
T
German Khokhlov a6c64713ee Stop Navara's memory growth on engine switches, hide polygon zones reliably, and drop the Cesium camera rig
- Navara 0.2.1 never frees pick batch ids, and the mover banks rebuilt
  their instanced meshes on each attach, leaking about 260 KiB of
  WebAssembly memory per switch. A per-view pool hands released ids back
  out; the long soak now asserts native growth of at most 32 KiB per switch.
- Navara 0.2.1 sometimes drops the first show:false update on a new
  vector layer, so a zone turned off right after a switch back stayed
  drawn. Polygon displays hide by deleting their layers and rebuild them
  when shown.
- Camera verbs drive both engines through the globe contract; the Cesium
  viewer rig and the tests of states it can no longer reach are gone.
- Flights and military tracking share src/layers/aircraft/tracking.js.
- The geo import scenario reads movers only where the engine has them.
- Add the Navara section to docs/CURRENT-STATE.md and a changelog fragment.
2026-11-05 21:18:23 +04:00

366 lines
12 KiB
JavaScript

// camera.follow on Cesium: the viewer's trackedEntity (Cesium's EntityView
// owns the continuous follow, the user turns and zooms around the target).
// With `native` the layer's own Entity is tracked; without it an internal
// proxy Entity whose position is the caller's `position()`. Each follow gets
// one exact tracked frame on preUpdate (applyTrackedCameraFrame) and the
// zoom limits that keep the camera outside the minimum range.
// following() also reports a trackedEntity the app set itself, and
// followChanged is viewer.trackedEntityChanged. A handle on an Entity carries
// its `name` (the Entity's name, else its id): what the camera verbs say they
// are following.
import * as Cesium from 'cesium';
import * as geo from '../../geo/index.js';
import { createEngineEvent } from '../contract.js';
import {
MIN_FOLLOW_RANGE_M,
clampTrackedCameraPosition,
normalizeFollowOptions,
} from '../follow.js';
import { toCesium3 } from './convert.js';
const MAX_FRAME_ATTEMPTS = 120;
const entityName = (entity) => (entity ? entity.name || entity.id : undefined);
const ZOOM_INERTIA_STATES = new WeakMap();
function acquireStableTrackedZoom(controller, owner, minRange) {
if (!controller) return () => {};
let state = ZOOM_INERTIA_STATES.get(controller);
if (!state) {
state = {
originalInertiaZoom: controller.inertiaZoom,
originalMinimumZoomDistance: controller.minimumZoomDistance,
owners: new Set(),
};
ZOOM_INERTIA_STATES.set(controller, state);
}
state.owners.add(owner);
controller.inertiaZoom = 0;
controller.minimumZoomDistance = Math.max(
state.originalMinimumZoomDistance ?? 0,
minRange,
);
return () => {
const current = ZOOM_INERTIA_STATES.get(controller);
if (!current) return;
current.owners.delete(owner);
if (current.owners.size > 0) return;
controller.inertiaZoom = current.originalInertiaZoom;
controller.minimumZoomDistance = current.originalMinimumZoomDistance;
ZOOM_INERTIA_STATES.delete(controller);
};
}
// The position the tracked visual already drew (the flight layers' display
// cache), without advancing its CallbackProperty again.
function displayPosition(entity, time, result) {
const displayed = entity?.gevDisplayPosition?.();
return displayed
? geo.cartesian3.clone(displayed, result)
: entity?.position?.getValue(time, result);
}
/**
* Apply an entity's requested follow offset once, then let Cesium's ENU
* EntityView exclusively own continuous following.
*
* Cesium can retain the previous world-space camera position when tracking
* switches across a large distance. The view then only rotates toward the new
* aircraft, and the next zoom can drive the camera through the ellipsoid.
* Applying the exact frame for the handoff makes selection deterministic. We
* deliberately do not rebuild it every frame: Cesium's EntityView already
* follows the same ENU entity, and two writers create sub-pixel camera jitter
* that becomes visible at minimum range.
*
* @param {Cesium.Viewer} viewer Active viewer.
* @param {Cesium.Entity} entity Newly tracked entity.
* @param {Cesium.Cartesian3 | Cesium.Property} viewFrom Desired camera offset
* in the tracked frame.
* @param {{ minRange?: number }} [options]
* @returns {(() => void)|undefined} Disposer for this one tracked-frame owner.
*/
export function applyTrackedCameraFrame(
viewer,
entity,
viewFrom,
{ minRange = MIN_FOLLOW_RANGE_M } = {},
) {
if (!viewer || !entity || !viewFrom) return;
let attempts = 0;
const trackedTransform = geo.matrix4.create();
const trackedPosition = geo.cartesian3.create();
const resolvedViewFrom = geo.cartesian3.create();
const cameraOffset = geo.cartesian3.create();
const previousCameraPosition = geo.cartesian3.create();
let framed = false;
const restoreZoomInertia = acquireStableTrackedZoom(
viewer.scene.screenSpaceCameraController,
entity,
minRange,
);
let stopped = false;
let remove = null;
const stop = () => {
if (stopped) return;
stopped = true;
remove?.();
restoreZoomInertia();
};
// preUpdate is deliberate. preRender fires after Cesium has prepared
// billboard/model draw state, so changing the tracked transform there makes
// the camera and target visual disagree for one frame (visible as a
// front/back oscillation). The controller then enforces the minimum range
// during the same update pass.
remove = viewer.scene.preUpdate.addEventListener(() => {
if (viewer.isDestroyed?.() || viewer.trackedEntity !== entity) {
stop();
return;
}
attempts += framed ? 0 : 1;
// Prefer the display cache exposed by the flight layer. Calling the
// CallbackProperty from preUpdate can advance dead reckoning again while
// Cesium's billboard/label still holds the prior visualizer sample. At a
// 150 m follow range that sub-frame difference becomes visible as the
// label swinging around the icon during an orbit, especially immediately
// after a 2D→3D→2D handoff.
if (!framed) {
const position = displayPosition(
entity,
viewer.clock.currentTime,
trackedPosition,
);
if (!position) {
if (attempts >= MAX_FRAME_ATTEMPTS) stop();
return;
}
const transform = geo.transforms.eastNorthUpToFixedFrame(
position,
geo.ellipsoid.WGS84,
trackedTransform,
);
const offset =
typeof viewFrom.getValue === 'function'
? viewFrom.getValue(viewer.clock.currentTime, resolvedViewFrom)
: geo.cartesian3.clone(viewFrom, resolvedViewFrom);
if (
!offset ||
geo.cartesian3.magnitudeSquared(offset) < geo.math.EPSILON12
) {
stop();
return;
}
viewer.camera.lookAtTransform(transform, offset);
geo.cartesian3.clone(viewer.camera.position, previousCameraPosition);
framed = true;
return;
}
// Normal frames are intentionally read-only: EntityView is the sole
// continuous camera writer. Only a programmatic zoom that bypasses the
// controller's minimumZoomDistance needs correction.
if (
clampTrackedCameraPosition(
viewer.camera,
previousCameraPosition,
minRange,
)
) {
geo.cartesian3.clone(viewer.camera.position, cameraOffset);
viewer.camera.lookAtTransform(viewer.camera.transform, cameraOffset);
}
geo.cartesian3.clone(viewer.camera.position, previousCameraPosition);
});
return stop;
}
/**
* @param {Cesium.Viewer} viewer
* @param {{ commanded: object }} ports The engine camera's commanded event.
*/
export function createCesiumFollow(viewer, { commanded }) {
const followChanged = createEngineEvent();
// The follow this engine started.
let own = null;
// Handles for entities the app tracked itself, one per entity.
const wrapped = new WeakMap();
let switching = false;
const wrap = (entity) => {
let handle = wrapped.get(entity);
if (!handle) {
handle = {
native: entity,
get name() {
return entityName(entity);
},
target: () =>
displayPosition(entity, viewer.clock.currentTime, undefined),
stop() {
if (viewer.trackedEntity === entity) viewer.trackedEntity = undefined;
},
retarget: (next) =>
follow({
native: entity,
position: () =>
displayPosition(entity, viewer.clock.currentTime, undefined),
viewFrom: () =>
entity.viewFrom?.getValue?.(viewer.clock.currentTime) ??
entity.viewFrom,
...next,
}),
};
wrapped.set(entity, handle);
}
return handle;
};
const following = () => {
const entity = viewer.trackedEntity;
if (!entity) return null;
if (own && own.entity === entity) return own.handle;
return wrap(entity);
};
// followChanged rides on trackedEntityChanged, subscribed once something
// listens or follows (creating the engine subscribes nothing).
let removeTracked = null;
const onTracked = () => {
if (switching) return;
if (own && viewer.trackedEntity !== own.entity) release(own);
followChanged.raiseEvent(following());
};
const watchTracking = () => {
if (removeTracked || !viewer.trackedEntityChanged) return;
removeTracked = viewer.trackedEntityChanged.addEventListener(onTracked);
};
const addListener = followChanged.addEventListener;
followChanged.addEventListener = (listener) => {
watchTracking();
return addListener(listener);
};
// Undo what one follow put on the viewer (not trackedEntity itself).
function teardown(state) {
state.stopFrame?.();
state.stopFrame = null;
state.removeCommanded?.();
state.removeCommanded = null;
if (state.proxy) viewer.entities.remove(state.proxy);
state.proxy = null;
}
function release(state) {
if (own !== state) return;
own = null;
teardown(state);
}
function start(state, options) {
state.options = options;
let entity = options.native;
if (!entity) {
const scratch = new Cesium.Cartesian3();
entity = state.proxy = viewer.entities.add({
position: new Cesium.CallbackProperty(() => {
let position;
try {
position = state.options.position();
} catch {
return undefined;
}
return position
? Cesium.Cartesian3.clone(toCesium3(position), scratch)
: undefined;
}, false),
viewFrom: toCesium3(state.options.viewFrom()),
// Cesium's EntityView moves the camera only once the tracked
// entity has a bounding sphere: a 1 px transparent point gives it
// one (an entity without graphics is framed once, then left).
point: { pixelSize: 1, color: Cesium.Color.TRANSPARENT },
});
// Picks skip it (picker.js).
entity.gevFollowProxy = true;
}
state.entity = entity;
state.handle.native = options.native;
state.handle.label = options.label;
viewer.camera.cancelFlight();
viewer.trackedEntity = entity;
const viewFrom =
options.native?.viewFrom ?? toCesium3(state.options.viewFrom());
state.stopFrame =
applyTrackedCameraFrame(viewer, entity, viewFrom, {
minRange: options.minRange,
}) ?? null;
// A command that takes the camera ends the follow; so does another
// tracked entity (Cesium raises commanded for that too).
state.removeCommanded = commanded.addEventListener(() => {
if (switching || own !== state) return;
if (viewer.trackedEntity === state.entity)
viewer.trackedEntity = undefined;
release(state);
});
viewer.scene.requestRender?.();
}
function follow(input) {
const options = normalizeFollowOptions(input);
watchTracking();
if (own) {
const previous = own;
own = null;
teardown(previous);
}
const state = { entity: null, proxy: null, options, handle: null };
state.handle = {
native: options.native,
get name() {
return entityName(state.handle.native);
},
target() {
try {
return state.options.position();
} catch {
return undefined;
}
},
stop() {
if (own !== state) return;
if (viewer.trackedEntity === state.entity)
viewer.trackedEntity = undefined;
release(state);
},
retarget(next) {
if (own !== state) return;
const updated = normalizeFollowOptions({ ...state.options, ...next });
switching = true;
try {
teardown(state);
start(state, updated);
} finally {
switching = false;
}
followChanged.raiseEvent(state.handle);
},
};
own = state;
// Assigning trackedEntity raises followChanged with this handle.
start(state, options);
return state.handle;
}
return {
camera: { follow, following, followChanged },
destroy() {
if (own) {
const state = own;
if (viewer.trackedEntity === state.entity)
viewer.trackedEntity = undefined;
release(state);
}
removeTracked?.();
removeTracked = null;
},
};
}