mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
Follow on the Cesium camera port
The Cesium camera port follows a target with Cesium's own entity tracking, on a hidden helper entity per target, and gains followed, followFramed, followOffset and followChanged. A target with a minimum range gets GEV's close-range rules, moved here from trackedCamera.js: an exact first framing, no zoom coasting, a zoom floor, and an eye that never crosses through the target. followChanged now fires only when what is followed changes, on the stub too. No layer follows through the port yet.
This commit is contained in:
1 parent
21d23034ec
commit
6c215f93a9
13 files changed
+690
-66
No files matched your search
@@ -0,0 +1,337 @@
|
||||
/**
|
||||
* @module render/cesium/follow
|
||||
* @description The Cesium camera port's follow. It is Cesium's own entity
|
||||
* tracking (`trackedEntity` and its EntityView) on a hidden helper entity
|
||||
* per target, so the camera behaves as it does for any tracked entity:
|
||||
* the user orbits and zooms around the target, tilt is off, and `moveEnd`
|
||||
* waits. On top of it, a target with a `minRange` gets GEV's close-range
|
||||
* rules: an exact first framing, no zoom coasting, a zoom floor, and an eye
|
||||
* that never crosses through the target.
|
||||
*
|
||||
* Whatever sets Cesium's `trackedEntity` takes the camera, so a follow ends
|
||||
* when anything else is tracked, and `follow(null)` ends any tracking.
|
||||
* `autodetect` is Cesium's AUTODETECT frame: a frame from inertial motion
|
||||
* (x forward, y left, z up) for a fast target such as a satellite, ENU for
|
||||
* a slow or still one. It is not the stub's frame along the ground track,
|
||||
* so an autodetect `viewFrom` is renderer-specific.
|
||||
*/
|
||||
import * as Cesium from 'cesium';
|
||||
import { toCartesian } from './common.js';
|
||||
import { trackedEntityViewEntity } from './internals.js';
|
||||
|
||||
/** Frames to wait for a target's first position before giving up framing. */
|
||||
const MAX_FRAME_ATTEMPTS = 120;
|
||||
const TRANSPARENT = new Cesium.Color(0, 0, 0, 0);
|
||||
const ZOOM_STATES = new WeakMap();
|
||||
|
||||
/**
|
||||
* Turn zoom coasting off and raise the zoom floor to `minRange` while any
|
||||
* owner holds it; the last release restores the controller's own values.
|
||||
* @param {object|undefined} controller A ScreenSpaceCameraController.
|
||||
* @param {object} owner
|
||||
* @param {number} minRange
|
||||
* @returns {() => void} Release.
|
||||
*/
|
||||
export function holdFollowZoom(controller, owner, minRange) {
|
||||
if (!controller) return () => {};
|
||||
let state = ZOOM_STATES.get(controller);
|
||||
if (!state) {
|
||||
state = {
|
||||
inertiaZoom: controller.inertiaZoom,
|
||||
minimumZoomDistance: controller.minimumZoomDistance,
|
||||
owners: new Map(),
|
||||
};
|
||||
ZOOM_STATES.set(controller, state);
|
||||
}
|
||||
state.owners.set(owner, minRange);
|
||||
const apply = (current) => {
|
||||
controller.inertiaZoom = 0;
|
||||
controller.minimumZoomDistance = Math.max(
|
||||
current.minimumZoomDistance,
|
||||
...current.owners.values(),
|
||||
);
|
||||
};
|
||||
apply(state);
|
||||
return () => {
|
||||
const current = ZOOM_STATES.get(controller);
|
||||
if (!current?.owners.delete(owner)) return;
|
||||
if (current.owners.size > 0) {
|
||||
apply(current);
|
||||
return;
|
||||
}
|
||||
controller.inertiaZoom = current.inertiaZoom;
|
||||
controller.minimumZoomDistance = current.minimumZoomDistance;
|
||||
ZOOM_STATES.delete(controller);
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Keep a follow-frame eye on the same side of its target and at least
|
||||
* `minimumRangeM` from it, in front and in all.
|
||||
* @param {{position: Cesium.Cartesian3, direction: Cesium.Cartesian3}} camera
|
||||
* Eye in the follow frame; corrected in place.
|
||||
* @param {Cesium.Cartesian3} previousPosition The eye's last frame.
|
||||
* @param {number} minimumRangeM
|
||||
* @returns {boolean} Whether the eye was corrected.
|
||||
*/
|
||||
export function clampFollowEye(camera, previousPosition, minimumRangeM) {
|
||||
const crossedOrigin =
|
||||
Cesium.Cartesian3.dot(camera.position, previousPosition) <= 0;
|
||||
const forwardDistance = -Cesium.Cartesian3.dot(
|
||||
camera.position,
|
||||
camera.direction,
|
||||
);
|
||||
const rangeSquared = Cesium.Cartesian3.magnitudeSquared(camera.position);
|
||||
if (crossedOrigin) {
|
||||
Cesium.Cartesian3.normalize(previousPosition, camera.position);
|
||||
Cesium.Cartesian3.multiplyByScalar(
|
||||
camera.position,
|
||||
minimumRangeM,
|
||||
camera.position,
|
||||
);
|
||||
return true;
|
||||
}
|
||||
if (
|
||||
forwardDistance < minimumRangeM ||
|
||||
rangeSquared < minimumRangeM * minimumRangeM
|
||||
) {
|
||||
Cesium.Cartesian3.multiplyByScalar(
|
||||
camera.direction,
|
||||
-minimumRangeM,
|
||||
camera.position,
|
||||
);
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
const gregorianScratch = new Cesium.GregorianDate();
|
||||
/**
|
||||
* Scene time in epoch ms, sub-millisecond included: `JulianDate.toDate`
|
||||
* drops the fraction, and EntityView samples motion 1 ms apart.
|
||||
*/
|
||||
function msOf(time) {
|
||||
const g = Cesium.JulianDate.toGregorianDate(time, gregorianScratch);
|
||||
const second = g.isLeapSecond ? g.second - 1 : g.second;
|
||||
return (
|
||||
Date.UTC(g.year, g.month - 1, g.day, g.hour, g.minute, second) +
|
||||
g.millisecond
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* The eye's starting offset: `viewFrom`, put out to the target's minimum
|
||||
* range. Cesium's EntityView frames from it too, so the two agree.
|
||||
*/
|
||||
function startOffset(target, viewFrom, result) {
|
||||
const offset = Cesium.Cartesian3.fromElements(
|
||||
viewFrom.x,
|
||||
viewFrom.y,
|
||||
viewFrom.z,
|
||||
result,
|
||||
);
|
||||
const range = Cesium.Cartesian3.magnitude(offset);
|
||||
const minRange = Math.max(target.minRange ?? 0, target.boundingRadius ?? 0);
|
||||
if (range >= Cesium.Math.EPSILON6 && range < minRange)
|
||||
Cesium.Cartesian3.multiplyByScalar(offset, minRange / range, offset);
|
||||
return offset;
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {{widget: object, scene: object, camera: object,
|
||||
* onChanged: () => void}} options `widget` is the Viewer or CesiumWidget
|
||||
* whose `trackedEntity` this follows with; `onChanged` runs on every
|
||||
* change of what it tracks.
|
||||
*/
|
||||
export function createCesiumFollow({ widget, scene, camera, onChanged }) {
|
||||
/** @type {null | {target: object, helper: object, framed: boolean,
|
||||
* attempts: number, previous: Cesium.Cartesian3, releaseZoom: () => void}} */
|
||||
let current = null;
|
||||
let removePreUpdate = null;
|
||||
/** What `followChanged` last announced: it fires only when that changes. */
|
||||
let announced = null;
|
||||
const followed = () =>
|
||||
current && widget.trackedEntity === current.helper ? current.target : null;
|
||||
|
||||
function release(entry) {
|
||||
if (!entry) return;
|
||||
entry.releaseZoom();
|
||||
if (!widget.isDestroyed?.()) widget.entities.remove(entry.helper);
|
||||
if (!current && removePreUpdate) {
|
||||
removePreUpdate();
|
||||
removePreUpdate = null;
|
||||
}
|
||||
}
|
||||
|
||||
// Anything that changes what Cesium tracks (a follow, `trackedEntity`
|
||||
// set elsewhere, the helper removed) ends a follow it replaced.
|
||||
const removeChanged = widget.trackedEntityChanged.addEventListener(
|
||||
(value) => {
|
||||
if (current && value !== current.helper) {
|
||||
const ended = current;
|
||||
current = null;
|
||||
release(ended);
|
||||
}
|
||||
const now = followed();
|
||||
if (now !== announced) {
|
||||
announced = now;
|
||||
onChanged();
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
const viewFromAt = (target, time) =>
|
||||
typeof target.viewFrom === 'function'
|
||||
? target.viewFrom(msOf(time))
|
||||
: target.viewFrom;
|
||||
|
||||
function helperFor(target) {
|
||||
return widget.entities.add({
|
||||
position: new Cesium.CallbackProperty((time, result) => {
|
||||
const p = target.position(msOf(time));
|
||||
return p ? Cesium.Cartesian3.fromElements(p.x, p.y, p.z, result) : p;
|
||||
}, false),
|
||||
// EntityView tracks an entity only once its bounding sphere is
|
||||
// ready, and an entity without graphics has none.
|
||||
point: { pixelSize: 1, color: TRANSPARENT },
|
||||
viewFrom: new Cesium.CallbackProperty((time, result) => {
|
||||
const v = viewFromAt(target, time);
|
||||
return v ? startOffset(target, v, result) : v;
|
||||
}, false),
|
||||
trackingReferenceFrame:
|
||||
target.frame === 'autodetect'
|
||||
? Cesium.TrackingReferenceFrame.AUTODETECT
|
||||
: Cesium.TrackingReferenceFrame.ENU,
|
||||
});
|
||||
}
|
||||
|
||||
// preUpdate on purpose: in preRender the target's drawing is already
|
||||
// prepared, so moving the eye there parts it from the target for a frame.
|
||||
function step() {
|
||||
const entry = current;
|
||||
if (!entry || entry.gaveUp || widget.trackedEntity !== entry.helper) return;
|
||||
if (!entry.framed) frame(entry);
|
||||
else if (
|
||||
entry.target.minRange > 0 &&
|
||||
clampFollowEye(camera, entry.previous, entry.target.minRange)
|
||||
)
|
||||
camera.lookAtTransform(
|
||||
camera.transform,
|
||||
Cesium.Cartesian3.clone(camera.position),
|
||||
);
|
||||
if (entry.framed) Cesium.Cartesian3.clone(camera.position, entry.previous);
|
||||
}
|
||||
|
||||
/**
|
||||
* The first framing. Cesium's EntityView keeps the old eye when tracking
|
||||
* switches across a large distance, so an ENU follow places it exactly;
|
||||
* an autodetected frame is Cesium's own to place.
|
||||
*/
|
||||
function frame(entry) {
|
||||
const { target } = entry;
|
||||
entry.attempts += 1;
|
||||
const time = widget.clock.currentTime;
|
||||
const at = target.position(msOf(time));
|
||||
if (target.frame !== 'enu') {
|
||||
// Framed once Cesium's EntityView has taken the helper on: until
|
||||
// then the camera may still ride the previous tracking's frame.
|
||||
entry.framed = trackedEntityViewEntity(widget) === entry.helper;
|
||||
if (!entry.framed) giveUpAfterWaiting(entry);
|
||||
return;
|
||||
}
|
||||
const viewFrom = at && viewFromAt(target, time);
|
||||
if (!at || !viewFrom) {
|
||||
giveUpAfterWaiting(entry);
|
||||
return;
|
||||
}
|
||||
const offset = startOffset(target, viewFrom);
|
||||
if (Cesium.Cartesian3.magnitude(offset) < Cesium.Math.EPSILON6) {
|
||||
// No offset to frame at: Cesium's own framing stands, unpoliced.
|
||||
giveUp(entry);
|
||||
return;
|
||||
}
|
||||
camera.lookAtTransform(
|
||||
Cesium.Transforms.eastNorthUpToFixedFrame(
|
||||
toCartesian(at),
|
||||
Cesium.Ellipsoid.WGS84,
|
||||
),
|
||||
offset,
|
||||
);
|
||||
entry.framed = true;
|
||||
}
|
||||
|
||||
/**
|
||||
* With no position to frame for MAX_FRAME_ATTEMPTS frames, the follow
|
||||
* leaves the camera to Cesium: no framing, no zoom hold, no clamp.
|
||||
*/
|
||||
function giveUpAfterWaiting(entry) {
|
||||
if (entry.attempts >= MAX_FRAME_ATTEMPTS) giveUp(entry);
|
||||
}
|
||||
function giveUp(entry) {
|
||||
entry.gaveUp = true;
|
||||
entry.releaseZoom();
|
||||
}
|
||||
|
||||
return {
|
||||
/** @param {object|null} target A contract FollowTarget. */
|
||||
follow(target) {
|
||||
const previous = current;
|
||||
if (!target) {
|
||||
current = null;
|
||||
widget.trackedEntity = undefined;
|
||||
release(previous);
|
||||
return;
|
||||
}
|
||||
const entry = {
|
||||
target,
|
||||
helper: helperFor(target),
|
||||
framed: false,
|
||||
gaveUp: false,
|
||||
attempts: 0,
|
||||
previous: new Cesium.Cartesian3(),
|
||||
releaseZoom: () => {},
|
||||
};
|
||||
if (target.minRange > 0)
|
||||
entry.releaseZoom = holdFollowZoom(
|
||||
scene.screenSpaceCameraController,
|
||||
entry,
|
||||
target.minRange,
|
||||
);
|
||||
current = entry;
|
||||
removePreUpdate ??= scene.preUpdate.addEventListener(step);
|
||||
widget.trackedEntity = entry.helper;
|
||||
release(previous);
|
||||
},
|
||||
get followed() {
|
||||
return followed();
|
||||
},
|
||||
get followFramed() {
|
||||
return Boolean(current?.framed);
|
||||
},
|
||||
followOffset: Object.freeze({
|
||||
get() {
|
||||
if (!current?.framed) return null;
|
||||
const p = camera.position;
|
||||
return { x: p.x, y: p.y, z: p.z };
|
||||
},
|
||||
set(offset) {
|
||||
if (!current?.framed) return;
|
||||
camera.lookAtTransform(camera.transform, toCartesian(offset));
|
||||
Cesium.Cartesian3.clone(camera.position, current.previous);
|
||||
scene.requestRender();
|
||||
},
|
||||
}),
|
||||
dispose() {
|
||||
removeChanged();
|
||||
const ended = current;
|
||||
current = null;
|
||||
if (ended && !widget.isDestroyed?.()) {
|
||||
if (widget.trackedEntity === ended.helper)
|
||||
widget.trackedEntity = undefined;
|
||||
}
|
||||
release(ended);
|
||||
removePreUpdate?.();
|
||||
removePreUpdate = null;
|
||||
},
|
||||
};
|
||||
}
|
||||
Reference in new issue
Block a user