Files
gods-eye-view/src/ui/cameraOrientationControls.js
T
German Khokhlov 7f478e3815 Remove always-true layer availability and leftover viewer paths
Every layer draws on both engines, so the per-engine availability
machinery always answered yes. The renderer manifest is now the id to
display map plus the wind flow backend; the catalog filter, the voice and
QA-probe refusals and the engine-kind checks go with it. The Navara
notice lists the same layers in the same words.

Paths that read the Cesium viewer behind an engine that is always there
are gone: the Recent Imagery viewer fallbacks, the shell's imagery-host
service (one shared host module remains), the engineless map controller,
viewer gates in voice actions, world packets and camera verbs, the
orientation controls' tracked-entity fallback, and the Bhote Koshi and
FIRMS Cesium-shaped paths. setCameraInputs, which nothing called, leaves
the contract; suspensions remain.

Smaller duplicates go too: one tracker-release helper for navigation and
location, the no-op frame latch, missing-engine guards, one name for the
injected display, flat bikeshare and installations displays, one overlay
host and binder, one name per world-overlay method, and stub-viewer
guards in the Cesium engine. Layers that still read the viewer keep the
shared init(viewer, context) entry.

Behaviour is unchanged on both engines. Viewer lines fall from 849 to
750 and engine-name literals from 32 to 27.
2026-11-08 17:06:01 +04:00

416 lines
14 KiB
JavaScript

import * as geo from '../geo/index.js';
import { isPickedWorldPosition } from '../data/scenePick.js';
import { t } from '../i18n/index.js';
// The camera is the globe engine's, and so is the follow: the followed
// entity is engine.camera.following().native (on Cesium also an entity the
// app put on viewer.trackedEntity). The viewer, when callers pass one, is
// read only for its clock.
// 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 followedEntity(engine) {
const handle = engine?.camera.following?.();
return handle?.native ?? null;
}
// An engine's own follow (no tracked entity: Navara): its handle, which
// knows its target and takes a new offset without ending the follow.
function engineFollow(engine, viewer) {
const handle = engine?.camera.following?.();
return handle &&
!followedEntity(engine) &&
typeof handle.target === 'function' &&
typeof handle.retarget === 'function'
? handle
: null;
}
function trackedTarget(entity, viewer) {
// 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 | null} engine
*/
export function pickViewTarget(engine) {
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 | null} engine
* @param {object | null} [viewer] The Cesium viewer whose tracked entity is
* the orbit target.
*/
export function readCameraTargetFrame(engine, viewer = null) {
if (!engine) return null;
const entity = followedEntity(engine);
const follow = engineFollow(engine, viewer);
const center = entity
? trackedTarget(entity, viewer)
: (follow?.target() ?? 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 | null} engine
* @param {object} frame From {@link readCameraTargetFrame}.
* @param {object | null} [viewer] As in readCameraTargetFrame.
*/
function setCameraTargetFrame(engine, frame, viewer = null) {
if (!engine || !frame?.target || !Number.isFinite(frame.range)) return false;
const { camera } = engine;
// Inside an engine's own follow: the new frame is the follow's offset (a
// camera command would end the follow; Cesium's tracked entity keeps its
// follow through lookAt below, so both engines keep following).
const follow = engineFollow(engine, viewer);
if (follow) {
const heading = normalizedHeading(frame.heading);
const flat = Math.cos(frame.pitch);
follow.retarget({
viewFrom: geo.cartesian3.create(
-frame.range * Math.sin(heading) * flat,
-frame.range * Math.cos(heading) * flat,
-frame.range * Math.sin(frame.pitch),
),
});
engine.render.request('camera-orientation');
return true;
}
try {
const trackedTransform = followedEntity(engine) ? 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}.
*/
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(engine, viewer = null) {
const frame = readCameraTargetFrame(engine, viewer);
if (!frame) return false;
const tilted = frameIsTilted(frame);
const pitch = tilted ? STRAIGHT_DOWN_PITCH : OBLIQUE_PITCH;
return setCameraTargetFrame(engine, { ...frame, pitch }, viewer)
? { tilted: !tilted, pitch }
: false;
}
/** Rotate around the viewport center until north is at the top. */
export function resetCameraNorth(engine, viewer = null) {
const frame = readCameraTargetFrame(engine, viewer);
if (!frame) return false;
return setCameraTargetFrame(engine, { ...frame, heading: 0 }, viewer);
}
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 | null} engine
* @param {{ now?: () => number, duration?: number, tracker?: object }} [options]
* `tracker`: the viewer, as in readCameraTargetFrame.
*/
export function createCameraOrientationAnimator(
engine,
{ now = () => performance.now(), duration = 650, tracker = null } = {},
) {
const viewer = 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 = followedEntity(engine);
pending = destination;
const start = now();
const headingDelta = geo.math.negativePiToPi(
destination.heading - frame.heading,
);
remove = engine.frames.preUpdate.addEventListener(() => {
if (engine.isDestroyed() || followedEntity(engine) !== entity) {
cancel();
return;
}
const progress = geo.math.clamp((now() - start) / duration, 0, 1);
const eased = cubicInOut(progress);
const center = entity ? trackedTarget(entity, 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 The viewer is only read for its clock and tracked entity.
*/
export function bindCameraOrientationControls({
viewer = null,
engine = null,
publish,
runNavigation,
showToast,
animationMs,
}) {
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(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();
};
/**
* 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(engine)) % 360,
};
publish?.(next);
}
function tilt() {
if (destroyed) return;
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 ? 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 = readFrame();
return (
frame &&
animator.animate(frame, {
heading: 0,
pitch: pending?.pitch ?? frame.pitch,
})
);
});
if (result) showToast?.(t('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(engine?.camera.followChanged, 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 {
tilt,
northUp,
sync,
refreshTilt,
cancel: animator.cancel,
destroy() {
if (destroyed) return;
destroyed = true;
animator.cancel();
for (const remove of removers.splice(0)) remove();
},
};
}