mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
camera.controls now maps the contract's CameraControls onto the scene's ScreenSpaceCameraController: the enable flags, zoom distances, zoom factor, coast as Cesium inertia (decay seconds, 0 for no coast), the collision switch, the tilt limit as the upper end of pitchRange, and the zoom bindings by name. suspend and enabled use the scene's shared input holds, so they count with the input port's and the dispatcher's. A follow's zoom hold now composes with the settings: minDistance and coast.zoom read and set what the follow gives back, a higher floor takes effect at once, and a follow never lengthens a shorter zoom coast. The ctrl+wheel binding check reuses the controls' binding helpers, and the controls checks run in the Cesium conformance set, the settings one in Node as well.
396 lines
13 KiB
JavaScript
396 lines
13 KiB
JavaScript
/**
|
|
* @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();
|
|
/** Each helper entity's FollowTarget. */
|
|
const HELPER_TARGETS = new WeakMap();
|
|
|
|
/**
|
|
* A pick as the follow's helper entity should not make it: a hit on a helper
|
|
* is a hit on its target's drawn `entity`, or no hit when it has none. Any
|
|
* other pick comes back as it was.
|
|
* @param {object|undefined} picked What `scene.pick` or `drillPick` gave.
|
|
* @returns {object|undefined}
|
|
*/
|
|
export function pickThroughFollowHelper(picked) {
|
|
const target = picked?.id && HELPER_TARGETS.get(picked.id);
|
|
if (!target) return picked;
|
|
return target.entity ? { ...picked, id: target.entity } : undefined;
|
|
}
|
|
|
|
/**
|
|
* 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);
|
|
applyFollowZoom(controller, state);
|
|
return () => {
|
|
const current = ZOOM_STATES.get(controller);
|
|
if (!current?.owners.delete(owner)) return;
|
|
if (current.owners.size > 0) {
|
|
applyFollowZoom(controller, current);
|
|
return;
|
|
}
|
|
controller.inertiaZoom = current.inertiaZoom;
|
|
controller.minimumZoomDistance = current.minimumZoomDistance;
|
|
ZOOM_STATES.delete(controller);
|
|
};
|
|
}
|
|
|
|
/**
|
|
* The controller's own zoom coast or zoom floor: while a follow holds them,
|
|
* the value it gives back on release, not the one in force.
|
|
* @param {object} controller A ScreenSpaceCameraController.
|
|
* @param {'inertiaZoom'|'minimumZoomDistance'} key
|
|
* @returns {number}
|
|
*/
|
|
export function followZoomBase(controller, key) {
|
|
const state = ZOOM_STATES.get(controller);
|
|
return state ? state[key] : controller[key];
|
|
}
|
|
|
|
/**
|
|
* Set the controller's own zoom coast or zoom floor. While a follow holds
|
|
* them it is what the follow gives back on release, and a zoom floor above
|
|
* the follow's holds takes effect at once.
|
|
* @param {object} controller A ScreenSpaceCameraController.
|
|
* @param {'inertiaZoom'|'minimumZoomDistance'} key
|
|
* @param {number} value
|
|
*/
|
|
export function setFollowZoomBase(controller, key, value) {
|
|
const state = ZOOM_STATES.get(controller);
|
|
if (!state) {
|
|
controller[key] = value;
|
|
return;
|
|
}
|
|
state[key] = value;
|
|
applyFollowZoom(controller, state);
|
|
}
|
|
|
|
function applyFollowZoom(controller, state) {
|
|
// The hold's coast is Cesium's shortest coefficient, 0; a controller of
|
|
// its own already coasting less (1 or more is no coast, under 0 is faster
|
|
// decay) keeps its own.
|
|
const own = state.inertiaZoom;
|
|
controller.inertiaZoom = own >= 1 || own < 0 ? own : 0;
|
|
controller.minimumZoomDistance = Math.max(
|
|
state.minimumZoomDistance,
|
|
...state.owners.values(),
|
|
);
|
|
}
|
|
|
|
/**
|
|
* 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) {
|
|
const helper = 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.
|
|
// Outline too: Cesium blends an opaque default outline into the edge.
|
|
point: {
|
|
pixelSize: 1,
|
|
color: TRANSPARENT,
|
|
outlineColor: TRANSPARENT,
|
|
outlineWidth: 0,
|
|
},
|
|
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,
|
|
});
|
|
HELPER_TARGETS.set(helper, target);
|
|
return helper;
|
|
}
|
|
|
|
// 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;
|
|
},
|
|
};
|
|
}
|