Files
gods-eye-view/src/ui/cameraOrientationControls.js
T
Sameh Khamis 068c39d5e7 Tilt, north-up and the compass through the camera, query and frame ports
The map orientation controls pick the view's centre through the query
port (depth, then the globe along the pick ray, then the ellipsoid), read
the camera from the camera port's pose, and set the orbit frame through
the port's lookAt, release and setView. The eased orientation runs on the
frame port's preUpdate, the compass needle on its preRender, and the tilt
state refreshes on the camera port's moveEnd.

While the camera follows something, the orbit offset must stay in the
follow's own frame (a satellite's included), which only Cesium knows: that
step moves verbatim into placeFollowEye in shareFollow, which stays on the
Cesium allow-list. cameraOrientationControls leaves it.
2026-11-07 03:11:51 -08:00

352 lines
12 KiB
JavaScript

import { isPickedWorldPosition } from '../data/scenePick.js';
import { t } from '../i18n/index.js';
import {
followedOf,
followedPosition,
isFollowing,
onFollowChanged,
} from '../data/followed.js';
import {
clamp,
eastNorthUp,
inverseFramePoint,
magnitude,
negativePiToPi,
toDegrees,
toRadians,
TWO_PI,
zeroToTwoPi,
} from '../geo/index.js';
import { findCamera, findFrame, findQuery } from '../render/rendererOf.js';
import { placeFollowEye } from './shareFollow.js';
function trackedTarget(viewer) {
// The visual's sample first: sampling a flight CallbackProperty twice can
// advance dead reckoning ahead of the displayed aircraft.
return followedPosition(viewer, followedOf(viewer));
}
export const OBLIQUE_PITCH = toRadians(-35);
export const STRAIGHT_DOWN_PITCH = toRadians(-89);
const OBLIQUE_THRESHOLD = toRadians(-60);
const EPSILON10 = 1e-10;
function normalizedHeading(heading) {
const wrapped = zeroToTwoPi(Number.isFinite(heading) ? heading : 0);
return Math.abs(wrapped - TWO_PI) < EPSILON10 ? 0 : wrapped;
}
/** The camera port's pose, or null when there is none to read. */
function poseOf(camera) {
try {
return camera?.pose() ?? null;
} catch {
return null;
}
}
/** Cubic ease in and out, 0..1 to 0..1. */
function cubicInOut(k) {
if (k < 0.5) return 4 * k * k * k;
const f = 2 * k - 2;
return 0.5 * f * f * f + 1;
}
/** Return the world position under the center of the canvas, when available. */
export function pickViewTarget(viewer) {
const query = findQuery(viewer);
const canvas = viewer?.scene?.canvas;
if (!query || !canvas) return null;
const width = canvas.clientWidth || canvas.width || 0;
const height = canvas.clientHeight || canvas.height || 0;
if (!width || !height) return null;
const x = width / 2;
const y = height / 2;
const attempt = (pick) => {
try {
return pick();
} catch {
return null;
}
};
// Depth first: what is drawn under the centre, tiles included.
let target = attempt(() => query.pickPosition(x, y));
// 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. The ellipsoid answers with sea level, which on a
// plateau sits far below the view and would swing the camera on every tilt.
if (!isPickedWorldPosition(target))
target = attempt(() => query.pickGlobe(query.pickRay(x, y)));
if (!isPickedWorldPosition(target))
target = attempt(() => query.pickEllipsoid(x, y));
return isPickedWorldPosition(target) ? target : null;
}
/** Describe the camera as an orbit around the current viewport center. */
export function readCameraTargetFrame(viewer) {
const pose = poseOf(findCamera(viewer));
const target = isFollowing(viewer)
? trackedTarget(viewer)
: pickViewTarget(viewer);
if (!pose || !target || !isPickedWorldPosition(pose.position)) return null;
const localOffset = inverseFramePoint(eastNorthUp(target), pose.position);
const range = magnitude(localOffset);
if (!Number.isFinite(range) || range < 1) return null;
const pitch = -Math.asin(clamp(localOffset.z / range, -1, 1));
// A lookAt camera sits 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 < toRadians(-88.5) ? pose.heading : targetHeading,
);
return { target, range, heading, pitch };
}
/** Apply an orbit frame, then return the camera to the world frame. */
function setCameraTargetFrame(viewer, frame) {
const camera = findCamera(viewer);
if (!camera || !frame?.target || !Number.isFinite(frame.range)) return false;
const offset = {
heading: normalizedHeading(frame.heading),
pitch: frame.pitch,
range: frame.range,
};
try {
// Following keeps the follow's own frame (satellite frames included):
// its next update carries the new offset along with the target.
if (isFollowing(viewer))
return placeFollowEye(viewer, frame.target, offset);
camera.lookAt(frame.target, offset);
const pose = camera.pose();
camera.release();
if (pose?.position && pose.direction && pose.up)
camera.setView({
destination: pose.position,
orientation: { direction: pose.direction, up: pose.up },
});
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}.
*/
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(viewer) {
const frame = readCameraTargetFrame(viewer);
if (!frame) return false;
const tilted = frameIsTilted(frame);
const pitch = tilted ? STRAIGHT_DOWN_PITCH : OBLIQUE_PITCH;
return setCameraTargetFrame(viewer, { ...frame, pitch })
? { tilted: !tilted, pitch }
: false;
}
/** Rotate around the viewport center until north is at the top. */
export function resetCameraNorth(viewer) {
const frame = readCameraTargetFrame(viewer);
if (!frame) return false;
return setCameraTargetFrame(viewer, { ...frame, heading: 0 });
}
function headingDegrees(viewer) {
return toDegrees(normalizedHeading(poseOf(findCamera(viewer))?.heading));
}
/** Ease an orbit without handing off the entity that owns the follow camera. */
export function createCameraOrientationAnimator(
viewer,
{ now = () => performance.now(), duration = 650 } = {},
) {
let remove = null;
let pending = null;
const cancel = () => {
remove?.();
remove = null;
pending = null;
};
function animate(frame, destination) {
cancel();
const frames = findFrame(viewer);
if (!frames || duration <= 0)
return setCameraTargetFrame(viewer, { ...frame, ...destination });
const followed = followedOf(viewer);
pending = destination;
const start = now();
const headingDelta = negativePiToPi(destination.heading - frame.heading);
remove = frames.on('preUpdate', () => {
if (viewer.isDestroyed?.() || followedOf(viewer) !== followed) {
cancel();
return;
}
const progress = clamp((now() - start) / duration, 0, 1);
const eased = cubicInOut(progress);
const target = followed ? trackedTarget(viewer) : frame.target;
if (
!isPickedWorldPosition(target) ||
!setCameraTargetFrame(viewer, {
...frame,
target,
heading: frame.heading + headingDelta * eased,
pitch: (1 - eased) * frame.pitch + eased * destination.pitch,
})
) {
cancel();
return;
}
if (progress === 1) cancel();
});
frames.requestRender('camera-orientation');
return true;
}
return {
animate,
cancel,
get destination() {
return pending;
},
};
}
/**
* Answer the two map-orientation actions and publish the state their buttons
* show: whether the map is tilted and the camera's whole-degree heading.
* The state is published on every rendered frame; its store keeps only a
* change, so an owner that takes the buttons back shows its state at once.
*/
export function bindCameraOrientationControls({
viewer,
publish,
runNavigation,
showToast,
}) {
const removers = [];
let destroyed = false;
// 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(viewer);
/** Recompute the tilt state exactly, paying for one pick. */
const refreshTilt = () => {
if (destroyed) return;
tilted = frameIsTilted(readCameraTargetFrame(viewer));
sync();
};
/**
* Publish the two controls' state.
*
* 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.
* That measured the controls' own work; what a publish renders is the
* view's (the globe actions compass alone renders the heading).
*/
function sync() {
if (destroyed) return;
const next = {
tilted,
heading: Math.round(headingDegrees(viewer)) % 360,
};
publish?.(next);
}
function tilt() {
if (destroyed) return;
const pending = animator.destination;
const result = runNavigation('camera', () => {
const frame = readCameraTargetFrame(viewer);
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 ? t('Tilted view') : t('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();
}
function northUp() {
if (destroyed) return;
const pending = animator.destination;
const result = runNavigation('camera', () => {
const frame = readCameraTargetFrame(viewer);
return (
frame &&
animator.animate(frame, {
heading: 0,
pitch: pending?.pitch ?? frame.pitch,
})
);
});
if (result) showToast?.(t('North up'));
sync();
}
const subscribe = (remove) => {
if (typeof remove === 'function') removers.push(remove);
};
// The needle follows every frame the scene draws. The camera's `changed`
// is NOT enough: it only fires past its threshold, so a rotation of a few
// degrees leaves the needle pointing at the old bearing.
subscribe(findFrame(viewer)?.on('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(findCamera(viewer)?.on('moveEnd', refreshTilt));
if (viewer) removers.push(onFollowChanged(viewer, animator.cancel));
for (const type of ['pointerdown', 'wheel']) {
const canvas = viewer?.scene?.canvas;
canvas?.addEventListener?.(type, animator.cancel, { passive: true });
removers.push(() => canvas?.removeEventListener?.(type, animator.cancel));
}
refreshTilt();
return {
tilt,
northUp,
sync,
refreshTilt,
cancel: animator.cancel,
destroy() {
if (destroyed) return;
destroyed = true;
animator.cancel();
for (const remove of removers.splice(0)) remove();
},
};
}