mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
The application shell keeps the page's globe engine and hands it to the navigation controller, location navigation (search, city and POI flights, orbit, globe reset), the tilt and north-up controls, share-link save and restore, share restoration's first-gesture listeners and the HUD. The viewer is passed only where entity tracking still lives on it (phase 1c) and to the HUD's basemap label context (voice); every such use is null-safe. Share links and captured shots write heading and roll as Cesium's camera reports them (src/cameraAngles.js): the contract's [0, 2π) pose maps an exact 0 back to Cesium's 2π, except the roll of a vertical view, so links stay byte-identical (heading=360, roll=360) on every engine. Source-reading tests follow the moved code with the same checks.
420 lines
15 KiB
JavaScript
420 lines
15 KiB
JavaScript
import * as geo from '../geo/index.js';
|
|
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).
|
|
const engineOf = (target) => engineFromViewer(target);
|
|
const trackerOf = (target, tracker) =>
|
|
tracker ?? (target && !isGlobeEngine(target) ? target : null);
|
|
|
|
// Cesium's EasingFunction.CUBIC_IN_OUT (tween.js Cubic.InOut).
|
|
function cubicInOut(amount) {
|
|
if ((amount *= 2) < 1) return 0.5 * amount * amount * amount;
|
|
return 0.5 * ((amount -= 2) * amount * amount + 2);
|
|
}
|
|
|
|
function trackedTarget(viewer) {
|
|
const entity = viewer.trackedEntity;
|
|
// 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)
|
|
);
|
|
}
|
|
|
|
export const OBLIQUE_PITCH = geo.math.toRadians(-35);
|
|
export const STRAIGHT_DOWN_PITCH = geo.math.toRadians(-89);
|
|
const OBLIQUE_THRESHOLD = geo.math.toRadians(-60);
|
|
|
|
function normalizedHeading(heading) {
|
|
const wrapped = geo.math.zeroToTwoPi(Number.isFinite(heading) ? heading : 0);
|
|
return Math.abs(wrapped - geo.math.TWO_PI) < geo.math.EPSILON10 ? 0 : wrapped;
|
|
}
|
|
|
|
/**
|
|
* Return the world position under the center of the canvas, when available.
|
|
* @param {import('../globe/contract.js').GlobeEngine | object} target The
|
|
* globe engine, or a viewer registered for one.
|
|
*/
|
|
export function pickViewTarget(target) {
|
|
const engine = engineOf(target);
|
|
if (!engine) return null;
|
|
const { width, height } = engine.host.size();
|
|
if (!width || !height) return null;
|
|
const center = { x: width / 2, y: height / 2 };
|
|
const { picker, camera } = engine;
|
|
// Depth first, then terrain before the ellipsoid: the globe pick
|
|
// intersects the rendered surface, so over keyless elevated terrain it
|
|
// returns the ground the operator is looking at. pickEllipsoid answers with
|
|
// sea level, which on a plateau sits far below the view and would swing the
|
|
// camera on every tilt.
|
|
const stages = [
|
|
() =>
|
|
picker.pickPositionSupported ? picker.pickPosition(center) : undefined,
|
|
() => picker.pickGlobe(center),
|
|
() => camera.pickEllipsoid(center),
|
|
];
|
|
for (const stage of stages) {
|
|
let picked = null;
|
|
try {
|
|
picked = stage();
|
|
} catch {
|
|
picked = null;
|
|
}
|
|
if (isPickedWorldPosition(picked)) return picked;
|
|
}
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Describe the camera as an orbit around the current viewport center.
|
|
* @param {import('../globe/contract.js').GlobeEngine | object} target The
|
|
* globe engine, or a viewer registered for one.
|
|
* @param {object} [tracker] The viewer whose tracked entity is the orbit
|
|
* target (defaults to `target` when that is a viewer).
|
|
*/
|
|
export function readCameraTargetFrame(target, tracker) {
|
|
const engine = engineOf(target);
|
|
if (!engine) return null;
|
|
const viewer = trackerOf(target, tracker);
|
|
const center = viewer?.trackedEntity
|
|
? trackedTarget(viewer)
|
|
: pickViewTarget(engine);
|
|
const pose = engine.camera.pose();
|
|
if (!center || !isPickedWorldPosition(pose.position)) return null;
|
|
|
|
const transform = geo.transforms.eastNorthUpToFixedFrame(center);
|
|
const inverse = geo.matrix4.inverseTransformation(
|
|
transform,
|
|
geo.matrix4.create(),
|
|
);
|
|
const localOffset = geo.matrix4.multiplyByPoint(
|
|
inverse,
|
|
pose.position,
|
|
geo.cartesian3.create(),
|
|
);
|
|
const range = geo.cartesian3.magnitude(localOffset);
|
|
if (!Number.isFinite(range) || range < 1) return null;
|
|
|
|
const pitch = -Math.asin(geo.math.clamp(localOffset.z / range, -1, 1));
|
|
// Cesium places a lookAt camera at range * (-sin h cos p, -cos h cos p,
|
|
// -sin p) in the target's east-north-up frame, so recovering h means
|
|
// negating BOTH horizontal components. Negating only the north one reads
|
|
// every heading as its mirror image (30 deg comes back as 330), which would
|
|
// make north-up rotate the wrong way from three quarters of the compass.
|
|
const targetHeading = Math.atan2(-localOffset.x, -localOffset.y);
|
|
const heading = normalizedHeading(
|
|
pitch < geo.math.toRadians(-88.5) ? pose.heading : targetHeading,
|
|
);
|
|
return { target: center, range, heading, pitch };
|
|
}
|
|
|
|
/**
|
|
* Apply an orbit frame, then return the camera to the fixed-world frame.
|
|
* @param {import('../globe/contract.js').GlobeEngine | object} target The
|
|
* globe engine, or a viewer registered for one.
|
|
* @param {object} frame From {@link readCameraTargetFrame}.
|
|
* @param {object} [tracker] As in readCameraTargetFrame.
|
|
*/
|
|
export function setCameraTargetFrame(target, frame, tracker) {
|
|
const engine = engineOf(target);
|
|
if (!engine || !frame?.target || !Number.isFinite(frame.range)) return false;
|
|
const viewer = trackerOf(target, tracker);
|
|
const { camera } = engine;
|
|
try {
|
|
const trackedTransform = viewer?.trackedEntity ? camera.transform() : null;
|
|
camera.lookAt(frame.target, {
|
|
heading: normalizedHeading(frame.heading),
|
|
pitch: frame.pitch,
|
|
range: frame.range,
|
|
});
|
|
if (trackedTransform) {
|
|
// Preserve EntityView's reference frame (including satellite frames).
|
|
// Its next update carries this new local offset along with the target.
|
|
camera.lookAtTransform(trackedTransform);
|
|
engine.render.request('camera-orientation');
|
|
return true;
|
|
}
|
|
const { position: destination, direction, up } = camera.pose();
|
|
camera.release();
|
|
if (destination && direction && up) {
|
|
camera.setView({ destination, orientation: { direction, up } });
|
|
}
|
|
engine.render.request('camera-orientation');
|
|
return true;
|
|
} catch {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Whether the map reads as tilted, from the orbit frame.
|
|
*
|
|
* This is the quantity the toggle commands, so it is the only one the button
|
|
* may show. The camera's OWN pitch is a different angle: at a few kilometres
|
|
* the two agree to 0.02 degrees, but from the full-globe view they are tens of
|
|
* degrees apart, because the point under the middle of the screen is most of a
|
|
* hemisphere away. Reading the camera's pitch there made the toggle choose
|
|
* oblique twice in a row — commanded oblique, camera pitch came back near -77,
|
|
* still "not tilted", tilt again.
|
|
*
|
|
* @param {{pitch: number}|null} frame From {@link readCameraTargetFrame}.
|
|
*/
|
|
export function frameIsTilted(frame) {
|
|
const pitch = Number(frame?.pitch);
|
|
return Number.isFinite(pitch) ? pitch > OBLIQUE_THRESHOLD : false;
|
|
}
|
|
|
|
/** Toggle between a straight-down map and a useful oblique map angle. */
|
|
export function toggleCameraTilt(target, tracker) {
|
|
const frame = readCameraTargetFrame(target, tracker);
|
|
if (!frame) return false;
|
|
const tilted = frameIsTilted(frame);
|
|
const pitch = tilted ? STRAIGHT_DOWN_PITCH : OBLIQUE_PITCH;
|
|
return setCameraTargetFrame(target, { ...frame, pitch }, tracker)
|
|
? { tilted: !tilted, pitch }
|
|
: false;
|
|
}
|
|
|
|
/** Rotate around the viewport center until north is at the top. */
|
|
export function resetCameraNorth(target, tracker) {
|
|
const frame = readCameraTargetFrame(target, tracker);
|
|
if (!frame) return false;
|
|
return setCameraTargetFrame(target, { ...frame, heading: 0 }, tracker);
|
|
}
|
|
|
|
function headingDegrees(engine) {
|
|
return geo.math.toDegrees(normalizedHeading(engine?.camera.pose().heading));
|
|
}
|
|
|
|
/**
|
|
* Ease an orbit without handing off the entity that owns the follow camera.
|
|
* @param {import('../globe/contract.js').GlobeEngine | object} target The
|
|
* globe engine, or a viewer registered for one.
|
|
* @param {{ now?: () => number, duration?: number, tracker?: object }} [options]
|
|
* `tracker` as in readCameraTargetFrame.
|
|
*/
|
|
export function createCameraOrientationAnimator(
|
|
target,
|
|
{ now = () => performance.now(), duration = 650, tracker } = {},
|
|
) {
|
|
const engine = engineOf(target);
|
|
const viewer = trackerOf(target, tracker);
|
|
let remove = null;
|
|
let pending = null;
|
|
const cancel = () => {
|
|
remove?.();
|
|
remove = null;
|
|
pending = null;
|
|
};
|
|
function animate(frame, destination) {
|
|
cancel();
|
|
if (!engine) return false;
|
|
if (duration <= 0)
|
|
return setCameraTargetFrame(engine, { ...frame, ...destination }, viewer);
|
|
const entity = viewer?.trackedEntity;
|
|
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) {
|
|
cancel();
|
|
return;
|
|
}
|
|
const progress = geo.math.clamp((now() - start) / duration, 0, 1);
|
|
const eased = cubicInOut(progress);
|
|
const center = entity ? trackedTarget(viewer) : frame.target;
|
|
if (
|
|
!isPickedWorldPosition(center) ||
|
|
!setCameraTargetFrame(
|
|
engine,
|
|
{
|
|
...frame,
|
|
target: center,
|
|
heading: frame.heading + headingDelta * eased,
|
|
pitch: geo.math.lerp(frame.pitch, destination.pitch, eased),
|
|
},
|
|
viewer,
|
|
)
|
|
) {
|
|
cancel();
|
|
return;
|
|
}
|
|
if (progress === 1) cancel();
|
|
});
|
|
engine.render.request('camera-orientation');
|
|
return true;
|
|
}
|
|
return {
|
|
animate,
|
|
cancel,
|
|
get destination() {
|
|
return pending;
|
|
},
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Bind the two map-orientation actions and keep their accessible state current.
|
|
* @param {{
|
|
* engine?: import('../globe/contract.js').GlobeEngine,
|
|
* viewer?: object,
|
|
* elements: object,
|
|
* runNavigation: Function,
|
|
* showToast?: Function,
|
|
* animationMs?: number,
|
|
* }} options `engine` defaults to the one registered for `viewer`; the viewer
|
|
* is otherwise only read for its tracked entity (phase 1c).
|
|
*/
|
|
export function bindCameraOrientationControls({
|
|
viewer = null,
|
|
engine = engineOf(viewer),
|
|
elements,
|
|
runNavigation,
|
|
showToast,
|
|
animationMs,
|
|
}) {
|
|
const tiltButton = elements?.tiltButton;
|
|
const northButton = elements?.northButton;
|
|
const removers = [];
|
|
let destroyed = false;
|
|
let applied = null;
|
|
// The tilt state is the one thing here that costs a depth read of the middle
|
|
// of the screen: 4 ms median and up to 12 ms, measured on this machine. It is
|
|
// therefore held between refreshes rather than recomputed per frame.
|
|
let tilted = false;
|
|
const animator = createCameraOrientationAnimator(engine, {
|
|
tracker: viewer,
|
|
...(animationMs === undefined ? {} : { duration: animationMs }),
|
|
});
|
|
const readFrame = () => readCameraTargetFrame(engine, viewer);
|
|
|
|
/** Recompute the tilt state exactly, paying for one pick. */
|
|
const refreshTilt = () => {
|
|
if (destroyed) return;
|
|
tilted = frameIsTilted(readFrame());
|
|
sync();
|
|
};
|
|
|
|
/**
|
|
* Write the two controls' state, but only what actually changed.
|
|
*
|
|
* The compass needle reads the camera's own bearing, which costs nothing, so
|
|
* this can run on every rendered frame: measured at 1.4 ms across 120 frames
|
|
* of a continuously dragged map (0.012 ms per frame, 0.1 ms worst case),
|
|
* against the 4 ms per frame the depth read it replaced would have cost.
|
|
*/
|
|
function sync() {
|
|
if (destroyed) return;
|
|
const next = {
|
|
tilted,
|
|
heading: Math.round(headingDegrees(engine)) % 360,
|
|
};
|
|
if (
|
|
applied &&
|
|
applied.tilted === next.tilted &&
|
|
applied.heading === next.heading
|
|
)
|
|
return;
|
|
if (!applied || applied.tilted !== next.tilted) {
|
|
tiltButton?.setAttribute('aria-pressed', String(next.tilted));
|
|
tiltButton?.setAttribute(
|
|
'aria-label',
|
|
next.tilted
|
|
? 'Return map to straight-down view'
|
|
: 'Tilt map to oblique view',
|
|
);
|
|
}
|
|
if (!applied || applied.heading !== next.heading) {
|
|
northButton?.setAttribute('data-north-up', String(next.heading === 0));
|
|
northButton?.style?.setProperty('--camera-heading', `${next.heading}deg`);
|
|
northButton?.setAttribute(
|
|
'aria-label',
|
|
`Reset map to north up. Current heading ${next.heading} degrees`,
|
|
);
|
|
}
|
|
applied = next;
|
|
}
|
|
|
|
const listen = (element, handler) => {
|
|
if (!element) return;
|
|
element.addEventListener('click', handler);
|
|
removers.push(() => element.removeEventListener('click', handler));
|
|
};
|
|
listen(tiltButton, () => {
|
|
const pending = animator.destination;
|
|
const result = runNavigation('camera', () => {
|
|
const frame = readFrame();
|
|
if (!frame) return false;
|
|
const nextTilted = !frameIsTilted(pending || frame);
|
|
const pitch = nextTilted ? OBLIQUE_PITCH : STRAIGHT_DOWN_PITCH;
|
|
return animator.animate(frame, {
|
|
heading: pending?.heading ?? frame.heading,
|
|
pitch,
|
|
})
|
|
? { tilted: nextTilted, pitch }
|
|
: false;
|
|
});
|
|
if (result) {
|
|
showToast?.(result.tilted ? 'Tilted view' : 'Straight-down view');
|
|
// The action reports the state it just commanded, so the button can
|
|
// follow it without a second pick.
|
|
tilted = result.tilted;
|
|
}
|
|
sync();
|
|
});
|
|
listen(northButton, () => {
|
|
const pending = animator.destination;
|
|
const result = runNavigation('camera', () => {
|
|
const frame = readFrame();
|
|
return (
|
|
frame &&
|
|
animator.animate(frame, {
|
|
heading: 0,
|
|
pitch: pending?.pitch ?? frame.pitch,
|
|
})
|
|
);
|
|
});
|
|
if (result) showToast?.('North up');
|
|
sync();
|
|
});
|
|
|
|
const subscribe = (event, handler) => {
|
|
const remove = event?.addEventListener?.(handler);
|
|
if (typeof remove === 'function') removers.push(remove);
|
|
};
|
|
// The needle follows every frame the scene draws. `camera.changed` is NOT
|
|
// enough: it only fires past `camera.percentageChanged`, so a rotation of a
|
|
// few degrees leaves the needle pointing at the old bearing.
|
|
subscribe(engine?.frames.preRender, sync);
|
|
// 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(viewer?.trackedEntityChanged, animator.cancel);
|
|
for (const type of ['pointerdown', 'wheel']) {
|
|
const canvas = engine?.host.canvas;
|
|
canvas?.addEventListener?.(type, animator.cancel, { passive: true });
|
|
removers.push(() => canvas?.removeEventListener?.(type, animator.cancel));
|
|
}
|
|
refreshTilt();
|
|
|
|
return {
|
|
sync,
|
|
refreshTilt,
|
|
cancel: animator.cancel,
|
|
destroy() {
|
|
if (destroyed) return;
|
|
destroyed = true;
|
|
animator.cancel();
|
|
for (const remove of removers.splice(0)) remove();
|
|
},
|
|
};
|
|
}
|