mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
FollowHandle.target() returns the followed point, checked by the contract on both engines. The contract's model check now waits for ready() before looking for the model's pixels: the magenta point and sprites could fill the region before the glTF loaded (qa-globe-contract cesium 73/73, navara 79/79).
357 lines
12 KiB
JavaScript
357 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.
|
|
|
|
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 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,
|
|
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,
|
|
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;
|
|
},
|
|
};
|
|
}
|