Files
gods-eye-view/src/ui/cameraOrientationControls.js
T
German Khokhlov 35e70ec280 Draw the aircraft family, Wildlife Sightings and the Cockpit through the contract
The layers that still had one Cesium and one Navara implementation, or
drew on Cesium only, now draw through engine.movers, engine.lines and
engine.camera on both engines, and application code holds the engine
instead of guessing it from a viewer.

- Aircraft family: flights, military and local ADS-B share one display
  (src/layers/aircraft/render/display.js). The Cesium and Navara
  renderers are gone. Where they differed, the display follows Cesium:
  - attach and visibility tracking, live disableDepthTestDistance
    changes, the tracked glyph's distance scale, model ids that change,
    local ADS-B markers hidden until shown and its UAT ring as a point;
  - the trail head's hidden alpha is 0.45, the contract's
    depthFailAlpha scaled by the head's 0.9.
  The tracked glyph stays over the fleet, as on Navara. The movers
  contract reports readiness per model and reads model axes as the
  glTF's own on every engine. Cesium's follow takes any native target
  through a proxy entity in the ENU frame and mirrors its readout fields.
- Wildlife Sightings draws badges and the density glow as sprite sets
  and its privacy cells as line outlines (no fill yet). It takes clicks
  from engine.input and its card anchors to the engine's canvas and
  camera, so the layer is in both engines' catalogs again and a switch
  keeps the session's layer set.
- Cockpit: cockpitHost takes the engine only. The ridden aircraft is the
  engine follow's target, hidden through its sprite; only the Cesium
  Viewer's stock double-click is still routed around.
- About forty camera, navigation, share-link, HUD, voice, detection and
  layer-lifecycle callers take the engine. isGlobeEngine and
  engineFromViewer calls outside src/globe fall from 51 to 14.

The coupling baseline drops accordingly: layer renderer lines from
5239/12331 to 4546/11106 (Cesium/Navara), `viewer` lines from 2424 to
2209, Cesium-importing files from 69 to 66.
2026-11-07 02:34:34 +04:00

420 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, and for its tracked entity when the engine
// reports no follow.
// 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, viewer) {
const handle = engine?.camera.following?.();
return handle ? (handle.native ?? null) : (viewer?.trackedEntity ?? 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, viewer) &&
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, viewer);
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, viewer)
? 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, viewer);
pending = destination;
const start = now();
const headingDelta = geo.math.negativePiToPi(
destination.heading - frame.heading,
);
remove = engine.frames.preUpdate.addEventListener(() => {
if (engine.isDestroyed() || followedEntity(engine, viewer) !== 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);
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 {
tilt,
northUp,
sync,
refreshTilt,
cancel: animator.cancel,
destroy() {
if (destroyed) return;
destroyed = true;
animator.cancel();
for (const remove of removers.splice(0)) remove();
},
};
}