Files
gods-eye-view/src/cameraVerbs.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

2879 lines
107 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* Camera verbs — the "spy satellite simulator" feel
* (docs/superpowers/specs/2026-07-23-camera-verbs-fly-route-spec.md).
*
* One motion at a time, driven per clock tick. `once` = bounded eased nudge;
* `continuous` runs until move_camera{stop}, ANY manual camera input on the
* canvas (pointerdown/wheel/touchstart — the cancelFlight reflex), or a navigation tool
* starts (the shared UI navigation policy releases this owner before the new
* destination mutates the camera). fly_route is a
* continuous motion in the same slot: a cinematic dolly along an existing
* route annotation's street-following path.
*
* Orbit circles the current screen-center ground target holding range and
* pitch while advancing heading (per-frame camera.lookAt; the lookAt
* transform is cleared on every stop so manual control returns cleanly).
* Globe rotation turns the world-frame camera about its screen-up axis through
* Earth's center, preserving range and framing. Left/right name the visible
* globe motion, opposite to the camera's travel around Earth.
*/
import * as geo from './geo/index.js';
import { GLOBE_VIEW } from './locations.js';
import {
globeFrameShare,
isFreeGlobeCamera,
lookAngleWithinFrame,
lookPose,
lookStepLosesGlobe,
posePitch,
} from './globeInView.js';
import {
earthDiscScreenRadius,
getKeyholeGeometry,
KEYHOLE_OUTER_RADIUS,
} from './celestialRing.js';
import { isScopeMaskEnabled } from './scopeMask.js';
import {
holdContinuousRender,
releaseContinuousRender,
} from './renderGovernor.js';
let _isCockpitActive = null;
/** °/s by speed word — orbit; pan uses fractions of view height/s. */
const ORBIT_DEG_S = { slow: 2, normal: 6, fast: 15 };
const TILT_DEG_S = { slow: 4, normal: 10, fast: 20 };
const PAN_VIEW_FRACTION_S = { slow: 0.08, normal: 0.2, fast: 0.45 };
/** MEAN ground speed by speed word. The trapezoid profile below eases in and
* out around this mean, so a route still takes totalM / ROUTE_M_S seconds. */
const ROUTE_M_S = { slow: 20, normal: 40, fast: 90 };
/** Bounded `once` nudges (spec: tune by feel in the field test). */
const ONCE = {
orbitDeg: 30,
tiltDeg: 15,
rotateDeg: 15,
panViewFraction: 0.25,
durationS: 0.9,
};
const PITCH_MIN = geo.math.toRadians(-89);
const PITCH_MAX = geo.math.toRadians(-5);
/** A bare "tilt the camera" / "oblique view" settles here. */
const TILT_DEFAULT_PITCH_DEG = -45;
/** °/s for a tilt to a requested angle; short ones keep the once duration. */
const TILT_TO_DEG_S = 30;
/**
* A pivoting tilt keeps the range, so its height above the pivot is
* range × sin|pitch|. It swings no lower than this; the rest tilts in place.
*/
const TILT_MIN_CLEARANCE_M = 150;
/**
* Beyond this range a pivot would swing the camera thousands of km about the
* crosshair point, so the tilt happens in place instead.
*/
const TILT_PIVOT_MAX_RANGE_M = 1_000_000;
/**
* A pivot range rebuilt from the camera's position comes back a hair off the
* range it was set at: a range this close past the cutoff still counts as on
* it.
*/
const TILT_PIVOT_RANGE_SLACK_M = 1;
/**
* The shallowest a pivot swing goes when its clearance is not what stops it.
* From several hundred km the camera's own horizon limit lies past the
* place's horizon; tilting the rest in place there would lift the crosshair
* onto the sky, so the swing stops with the place this far above it.
*/
const TILT_MIN_PIVOT_ELEVATION = geo.math.toRadians(0.5);
/* ── Route dolly: cinematic tuning ──────────────────────────────────────────
* Every knob an owner may want to retune lives in this block. The shaping is
* built from four independent layers, each of which flattens to nothing on its
* own: a trapezoid speed profile, a banked-turn roll, altitude breathing, and
* a gaze that leads the path. Under prefers-reduced-motion the last three are
* zeroed and the dolly is a plain eased track along the route.
* -------------------------------------------------------------------------- */
/** Mean AGL the dolly rides at — the altitude shaping oscillates AROUND this. */
const ROUTE_CAMERA_HEIGHT_M = 260;
/** Locked look-down angle. Decoupled from the lookahead distance so the framing
* no longer changes with the speed word (it used to fall out of the geometry:
* a 260 m eye aiming at a point 260 m ahead is a hard −45° at the pavement). */
const ROUTE_PITCH_DEG = -32;
/** Seconds of travel the gaze leads the camera by (≈260 m at normal — the
* shipped constant — but coherent at slow and fast too). */
const ROUTE_LOOKAHEAD_S = 6.5;
const ROUTE_LOOKAHEAD_MIN_M = 120;
const ROUTE_LOOKAHEAD_MAX_M = 600;
/** 1/s — exponential smoothing rate for the dolly's gaze direction. */
const ROUTE_DIR_SMOOTH_RATE = 1.6;
/** Seconds of ease-in (and again ease-out) at the ends of the flight. */
const ROUTE_RAMP_S = 2.4;
/** Ramps never eat more than this share of a SHORT route's runtime. */
const ROUTE_RAMP_MAX_FRACTION = 0.35;
/** This is a map, not a flight sim: the roll is a hint, never a barrel roll. */
const ROUTE_BANK_MAX_DEG = 10;
/** Seconds of path (centred on the camera) the turn is measured over. The
* measure is a triangular pulse peaking exactly at the corner, so the bank
* rolls in before the turn and rolls out after it. */
const ROUTE_BANK_WINDOW_S = 4;
/** Degrees of bank per °/s of planned turn. After the roll filters below, a 90°
* street corner settles near 7.5° and a hairpin saturates the cap, so the cap
* stays a limit rather than the everyday value. */
const ROUTE_BANK_PER_DEG_S = 0.44;
/** Two cascaded first-order filters — C¹ roll entry/exit, no snap at the edges
* of the turn pulse. */
const ROUTE_BANK_LEAD_RATE = 2.2;
const ROUTE_BANK_SETTLE_RATE = 1.6;
/** Zero-mean altitude "breathing" over long straights. */
const ROUTE_BREATH_M = 20;
const ROUTE_BREATH_WAVELENGTH_M = 2200;
/** Extra height at full bank — the lookahead rise into a turn. Sized by its
* RATE, not its size: the lift has to be delivered inside the few seconds the
* camera takes to roll in, so a bigger number reads as a lurch, not a swell. */
const ROUTE_TURN_LIFT_M = 26;
/** 1/s — how fast the ALTITUDE follows the roll. Deliberately slower than the
* roll itself: the wings roll through a corner in a few seconds, but the swell
* that lifts the eye over it wants to be a long, shallow arc. */
const ROUTE_LIFT_TRACK_RATE = 0.5;
/** 1/s — the altitude shaping is filtered on its way to the camera so rolling
* out of a turn sinks the eye gently instead of dropping it. */
const ROUTE_ALT_SMOOTH_RATE = 0.9;
/** Hard clearance above the sampled ground floor; the shaping can never dip
* the eye below this, whatever the tuning above says. */
const ROUTE_MIN_CLEARANCE_M = 90;
/** 1/s — how fast the SHAPING floor follows the sampled one, in both
* directions. The hard clearance clamp reads the raw sample, so this rate is
* a comfort setting, not a safety one. */
const ROUTE_FLOOR_FALL_RATE = 0.9;
/** Below this |cos| the two chords are antipodal and the cross product's sign
* is a floating-point coin toss — an exact U-turn must not flip the bank
* direction frame to frame, so the degenerate case is branched explicitly. */
const ANTIPODAL_EPS = 1e-6;
/** Metres of corridor warmed when a flight starts, and the rolling window
* warmed ahead of the camera afterwards. Cells are the house 0.001° (~111 m)
* coarse cells, deduped by the warm batch, which also skips already-warm ones
* and queues (never drops) contending callers. */
const ROUTE_WARM_START_M = 4000;
const ROUTE_WARM_AHEAD_M = 3000;
const ROUTE_WARM_MAX_CELLS = 96;
/** Seconds between rolling corridor warms during a flight. */
const ROUTE_WARM_INTERVAL_S = 2;
/** Metres of arc between corridor samples (~half a coarse cell, so no cell the
* route crosses for more than ~55 m of ground is skipped). */
const ROUTE_WARM_STEP_M = 55;
/** Ceiling on the conservative floor seed used while the corridor is COLD.
* Above this the camera's own altitude stops being a useful proxy for the
* ground under it (a globe-scale view would park the dolly in orbit). */
const ROUTE_UNKNOWN_FLOOR_CAP_M = 5000;
/** Corridor cells the floor acquisition looks at, and therefore the HARD cap
* on sampleHeight calls a whole route may make: the mesh probe is latched to
* fire once per flight, so this is a per-route budget, not a per-frame one. */
const ROUTE_MESH_PROBE_CELLS = 8;
/** Seconds the dolly ARMS — camera untouched — waiting for real floor data
* before it starts moving. The corridor warm is fire-and-forget, so without
* this the first frame RACES it and can render underground. Matches the house
* one-shot floor deadline (FLOOR_RESOLVE_DEADLINE_MS), and is the same
* arm-then-act shape a chained orbit uses while its flight settles. */
const ROUTE_ARM_S = 1.2;
/** m/s — cap on how fast the eye may DESCEND. Climbs are never limited (they
* are the safety direction). Ordinary terrain following runs a few m/s, so
* this only bites when a hold is released onto late-arriving floor data — most
* visibly when the mesh probe seeded the floor from a downtown ROOFTOP and the
* real DEM later corrects it ~90 m downward. Held at the same bound as the
* altitude shaping so that correction reads as one more swell rather than as a
* sink of its own. Lagging HIGH is the safe direction, so a genuinely steep
* downhill simply floats a little wider of the ground. */
const ROUTE_MAX_DESCENT_MPS = 10;
/* ── Pure cinematic helpers (unit-tested; no viewer, no module state) ────── */
/** Whether the operating system asked us to keep motion boring. */
export function prefersReducedMotion() {
try {
return (
typeof window !== 'undefined' &&
typeof window.matchMedia === 'function' &&
window.matchMedia('(prefers-reduced-motion: reduce)').matches === true
);
} catch {
return false;
}
}
/**
* Frame-rate independent first-order approach (exponential smoothing).
* `1 - e^(-rate·dt)` rather than `rate·dt` so a dropped frame cannot overshoot.
* @param {number} current Current value (NaN adopts the target).
* @param {number} target Value to approach.
* @param {number} ratePerS Approach rate, 1/s.
* @param {number} dt Seconds elapsed.
* @returns {number} The smoothed value.
*/
export function approachValue(current, target, ratePerS, dt) {
if (!Number.isFinite(current)) return target;
if (!Number.isFinite(target)) return current;
const k = 1 - Math.exp(-Math.max(0, ratePerS) * Math.max(0, dt));
return current + (target - current) * k;
}
/**
* Share of the flight's runtime spent easing in (and again easing out).
* @param {number} durationS Flight duration.
* @returns {number} Ramp fraction in [0, ROUTE_RAMP_MAX_FRACTION].
*/
export function routeRampFraction(durationS) {
if (!(durationS > 0)) return 0;
return Math.min(ROUTE_RAMP_MAX_FRACTION, ROUTE_RAMP_S / durationS);
}
/**
* Trapezoid speed profile — smoothstep up, cruise, smoothstep down.
*
* Distance is the CLOSED-FORM integral of the speed curve, so position is
* exact (no per-frame accumulation drift) and speed is continuous everywhere:
* zero at both ends, and C¹ across the ramp/plateau joins because smoothstep
* has zero slope at 0 and 1. Waypoints are invisible to it — the profile is a
* function of arc length only, so nothing steps as a segment changes.
* @param {number} u Normalized time, 0..1.
* @param {number} r Ramp fraction from routeRampFraction().
* @returns {{distance: number, speed: number}} Arc fraction 0..1, and speed as
* a multiple of the plateau (cruise) speed.
*/
export function routeSpeedProfile(u, r) {
const t = Math.min(1, Math.max(0, Number.isFinite(u) ? u : 0));
if (!(r > 0)) return { distance: t, speed: 1 };
const area = 1 - r; // ∫₀¹ v du — both ramps together contribute r
const rampArea = (p) => r * (p * p * p - (p * p * p * p) / 2);
const smoothstep = (p) => p * p * (3 - 2 * p);
if (t <= r) {
const p = t / r;
return { distance: rampArea(p) / area, speed: smoothstep(p) };
}
if (t >= 1 - r) {
const p = (1 - t) / r;
return { distance: (area - rampArea(p)) / area, speed: smoothstep(p) };
}
return { distance: (r / 2 + (t - r)) / area, speed: 1 };
}
/**
* Bank angle for a planned turn rate — proportional, capped, honest about zero.
* @param {number} turnRateDegS Planned turn rate, °/s (+ = turning right).
* @param {boolean} [reducedMotion] Flatten the roll entirely.
* @returns {number} Degrees of roll, + = right wing down.
*/
export function routeBankTargetDeg(turnRateDegS, reducedMotion = false) {
if (reducedMotion || !Number.isFinite(turnRateDegS)) return 0;
const raw = turnRateDegS * ROUTE_BANK_PER_DEG_S;
return Math.max(-ROUTE_BANK_MAX_DEG, Math.min(ROUTE_BANK_MAX_DEG, raw));
}
/**
* Altitude offset around the route's mean AGL: a zero-mean breath over long
* straights, plus a small rise into turns for lookahead. Breathing fades out
* as the bank comes in so the two never fight.
* @param {number} arcM Distance travelled along the route.
* @param {number} bankFraction Current bank as a fraction of the cap, −1..1.
* @param {boolean} [reducedMotion] Flatten to a constant altitude.
* @returns {number} Metres to add to the mean AGL.
*/
export function routeAltitudeOffsetM(
arcM,
bankFraction,
reducedMotion = false,
) {
if (reducedMotion) return 0;
const bank = Number.isFinite(bankFraction)
? Math.max(-1, Math.min(1, bankFraction))
: 0;
const straight = 1 - Math.abs(bank);
const s = Number.isFinite(arcM) ? arcM : 0;
const breath =
Math.sin((2 * Math.PI * s) / ROUTE_BREATH_WAVELENGTH_M) *
ROUTE_BREATH_M *
straight;
return breath + Math.abs(bank) * ROUTE_TURN_LIFT_M;
}
/**
* Eye height above the ellipsoid. The last word on terrain: whatever the
* shaping asks for, the eye stays ROUTE_MIN_CLEARANCE_M above the floor.
* @param {number} floorM Ground floor height at the camera.
* @param {number} offsetM Altitude shaping offset.
* @returns {number} Height above the ellipsoid.
*/
export function routeEyeHeightM(floorM, offsetM) {
const base = Number.isFinite(floorM) ? floorM : 0;
const shaped =
base + ROUTE_CAMERA_HEIGHT_M + (Number.isFinite(offsetM) ? offsetM : 0);
return Math.max(base + ROUTE_MIN_CLEARANCE_M, shaped);
}
/**
* Track the ground floor SMOOTHLY, in both directions.
*
* The floor is a staircase: cells are 0.001° (~111 m) and the dolly reads the
* max of the cell it is over and one ahead, so crossing a boundary can step
* several metres in one frame. Adopting a rise instantly — which terrain safety
* seems to argue for — turns every one of those steps into an altitude pop
* (measured: 21.7 m/s of vertical rate over otherwise flat downtown). Safety
* does not actually need it: the hard clamp in advanceRouteFlight is applied
* against the RAW sample, so the smoothed value only ever shapes the ride.
* @param {number} previousM Held floor.
* @param {number} sampledM Newly sampled floor (NaN keeps the held value).
* @param {number} dt Seconds elapsed.
* @returns {number} The floor to shape the flight over this frame.
*/
export function routeFloorHoldM(previousM, sampledM, dt) {
if (!Number.isFinite(sampledM)) return previousM;
if (!Number.isFinite(previousM)) return sampledM;
return approachValue(previousM, sampledM, ROUTE_FLOOR_FALL_RATE, dt);
}
/** Read-only view of the tuning, for tests and harnesses. */
export const ROUTE_CINEMA = Object.freeze({
meanHeightM: ROUTE_CAMERA_HEIGHT_M,
pitchDeg: ROUTE_PITCH_DEG,
maxBankDeg: ROUTE_BANK_MAX_DEG,
minClearanceM: ROUTE_MIN_CLEARANCE_M,
breathM: ROUTE_BREATH_M,
turnLiftM: ROUTE_TURN_LIFT_M,
rampS: ROUTE_RAMP_S,
});
/* ── Route dolly geometry ────────────────────────────────────────────────── */
const _arcA = geo.cartesian3.create();
const _arcB = geo.cartesian3.create();
const _chordVertical = geo.cartesian3.create();
const _turnCross = geo.cartesian3.create();
const _framePos = geo.cartesian3.create();
const _frameAheadPos = geo.cartesian3.create();
const _frameUp = geo.cartesian3.create();
const _frameIn = geo.cartesian3.create();
const _frameOut = geo.cartesian3.create();
const _frameGaze = geo.cartesian3.create();
const _frameRight = geo.cartesian3.create();
const _frameLevelUp = geo.cartesian3.create();
const _frameDir = geo.cartesian3.create();
const _frameEye = geo.cartesian3.create();
const _frameBankedUp = geo.cartesian3.create();
const _frameCarto = geo.cartographic.create();
const _frameAheadCarto = geo.cartographic.create();
const _bankQuat = geo.quaternion.create();
const _bankMatrix = geo.matrix3.create();
const _headingQuat = geo.quaternion.create();
const _headingMatrix = geo.matrix3.create();
const _warmPos = geo.cartesian3.create();
const _warmCarto = geo.cartographic.create();
const _probeCarto = geo.cartographic.create();
/** Point at arc length `s` along the polyline (binary search — queries jump
* backwards for the inbound chord, so a forward cursor would not do). */
function arcPoint(state, s, result) {
const { pts, cumM } = state;
const clamped = Math.min(state.totalM, Math.max(0, s));
let lo = 0;
let hi = cumM.length - 2;
while (lo < hi) {
const mid = (lo + hi + 1) >> 1;
if (cumM[mid] <= clamped) lo = mid;
else hi = mid - 1;
}
const segLen = cumM[lo + 1] - cumM[lo];
const t =
segLen > 1e-6 ? Math.min(1, Math.max(0, (clamped - cumM[lo]) / segLen)) : 0;
return geo.cartesian3.lerp(pts[lo], pts[lo + 1], t, result);
}
/** Unit horizontal direction from arc `sA` to arc `sB`, or null when degenerate. */
function horizontalChord(state, sA, sB, up, result) {
const a = arcPoint(state, sA, _arcA);
const b = arcPoint(state, sB, _arcB);
geo.cartesian3.subtract(b, a, result);
const vertical = geo.cartesian3.multiplyByScalar(
up,
geo.cartesian3.dot(result, up),
_chordVertical,
);
geo.cartesian3.subtract(result, vertical, result);
const len = geo.cartesian3.magnitude(result);
if (!(len > 1e-3)) return null;
return geo.cartesian3.divideByScalar(result, len, result);
}
/**
* Signed angle from `a` to `b` about `up`; positive = turning RIGHT.
*
* At exactly 180° the cross product is zero and its sign is decided by
* floating-point signed zeros, so an out-and-back route would flip the bank
* direction frame to frame. A U-turn is resolved as a RIGHT turn, always —
* arbitrary, but deterministic, which is the property that matters.
* @param {Cesium.Cartesian3} a Unit horizontal direction turned FROM.
* @param {Cesium.Cartesian3} b Unit horizontal direction turned TO.
* @param {Cesium.Cartesian3} up Local up, the axis the turn is measured about.
* @returns {number} Radians, + = right.
*/
export function signedTurnRad(a, b, up) {
const cross = geo.cartesian3.cross(a, b, _turnCross);
const sinLeft = geo.cartesian3.dot(cross, up);
const cosTurn = geo.cartesian3.dot(a, b);
if (cosTurn <= -1 + ANTIPODAL_EPS && Math.abs(sinLeft) < ANTIPODAL_EPS)
return Math.PI;
return -Math.atan2(sinLeft, cosTurn);
}
/**
* Coarse floor cells along a stretch of the route, in travel order.
* Deduped to the house 0.001° grid and capped, so one flight can never issue an
* unbounded warm batch.
* @param {Object} state Route flight state (needs pts/cumM/totalM).
* @param {number} fromM Arc length to start collecting at.
* @param {number} spanM Metres of arc to cover.
* @param {number} [maxCells] Cap on the returned cells.
* @returns {Array<{lat: number, lon: number}>} Cells to warm.
*/
export function routeCorridorCells(
state,
fromM,
spanM,
maxCells = ROUTE_WARM_MAX_CELLS,
) {
const out = [];
if (!(state?.totalM > 0) || !(spanM > 0) || !(maxCells > 0)) return out;
const start = Math.max(0, Math.min(state.totalM, fromM));
const end = Math.max(0, Math.min(state.totalM, fromM + spanM));
const seen = new Set();
for (
let s = start;
s <= end + 1e-6 && out.length < maxCells;
s += ROUTE_WARM_STEP_M
) {
const point = arcPoint(state, s, _warmPos);
const carto = geo.cartographic.fromCartesian(
point,
geo.ellipsoid.WGS84,
_warmCarto,
);
const lat = Number(geo.math.toDegrees(carto.latitude).toFixed(3));
const lon = Number(geo.math.toDegrees(carto.longitude).toFixed(3));
const key = `${lat},${lon}`;
if (seen.has(key)) continue;
seen.add(key);
out.push({ lat, lon });
}
return out;
}
/** Fire-and-forget warm of a corridor stretch; never throws into the caller. */
function warmRouteCorridor(state, fromM, spanM) {
if (typeof state?.warmFn !== 'function') return 0;
const cells = routeCorridorCells(state, fromM, spanM);
if (!cells.length) return 0;
try {
state.warmFn(cells);
} catch {
return 0; // best effort — a cold cell holds the last known floor
}
state.warmedCells += cells.length;
return cells.length;
}
/**
* The floor to hold while the corridor is still cold.
*
* Cold is missing data, not flat ground, and the route's own vertices carry
* height 0 — so the previous fallback flew a Rocky Mountain route at 260 m
* above the ELLIPSOID. The camera's current position is, by construction,
* above the ground the user is looking at, so its height minus the cruise AGL
* is a floor we can defend. It is capped, because at globe scale the camera's
* altitude stops saying anything about the ground under it.
* @param {number} pathHeightM The route vertices' own height.
* @param {number} cameraHeightM Camera height at flight start, if known.
* @returns {number} A floor to hold until real terrain arrives.
*/
export function routeColdSeedFloorM(pathHeightM, cameraHeightM) {
const base = Number.isFinite(pathHeightM) ? pathHeightM : 0;
if (!Number.isFinite(cameraHeightM)) return base;
const implied = cameraHeightM - ROUTE_CAMERA_HEIGHT_M;
return Math.max(base, Math.min(base + ROUTE_UNKNOWN_FLOOR_CAP_M, implied));
}
/**
* Adopt the corridor's floor, from the cache or — failing that — from the
* rendered mesh directly.
*
* Runs at construction and again on every ARMING frame, because the corridor
* warm is fire-and-forget and this is how the dolly notices it landed. The
* per-frame part is cache READS (a Map lookup per cell); the mesh probe is
* latched to fire at most ONCE per flight, so a whole route costs at most
* ROUTE_MESH_PROBE_CELLS sampleHeight calls however long it arms.
*
* A partially warm corridor is NOT resolved. One cached cell says nothing
* about the ground under the other seven, and treating it as an answer let the
* dolly descend to 460 m over a 1,600 m surface. Every cell must be accounted
* for — by the cache, or by a probe that actually reached it.
*
* The probe is the answer to "what if the DEM never arrives at all", and it
* closes the hole in the case where the hole is observable: clipping requires
* terrain to BE rendered, and what is rendered is what sampleHeight reads. It
* reads the rendered surface at the CURRENT level of detail — rooftops and
* primitives included — which is a better estimate than nothing but is not a
* guaranteed upper bound. The per-frame raw-sample clamp remains the backstop.
* @param {Object} state Route flight state.
* @param {boolean} takeWhole Adopt the value outright (pre-departure) rather
* than easing onto it — a mid-flight arrival must never snap the eye.
* @returns {boolean} Whether the corridor's floor is now RESOLVED.
*/
function acquireCorridorFloor(state, takeWhole) {
const cells = routeCorridorCells(
state,
state.traveled,
ROUTE_WARM_START_M,
ROUTE_MESH_PROBE_CELLS,
);
if (!cells.length) return false;
const known = [];
const cold = [];
if (typeof state.floorFn === 'function') {
for (const cell of cells) {
let floor = Number.NaN;
try {
floor = state.floorFn(cell.lat, cell.lon);
} catch {
/* a hostile read is the same as a cold one */
}
if (Number.isFinite(floor)) known.push(floor);
else cold.push(cell);
}
} else {
cold.push(...cells);
}
// The probe fires once, for exactly the cells the cache could not answer.
if (
cold.length &&
!state.meshProbeSpent &&
typeof state.probeFn === 'function'
) {
state.meshProbeSpent = true; // latched whatever it returns — one per flight
try {
const probe = state.probeFn(cold) || {};
if (Number.isFinite(probe.heightM)) {
state.meshProbeFloorM = probe.heightM;
state.floorFromMeshProbe = true;
// Only a probe that reached EVERY cold cell resolves the corridor.
state.meshProbeCoveredCold = probe.sampled >= cold.length;
}
} catch {
/* tiles not streamed, or a scene mid-teardown */
}
}
if (Number.isFinite(state.meshProbeFloorM)) known.push(state.meshProbeFloorM);
if (!known.length) return false;
const floor = Math.max(...known);
// A partial answer still RAISES the held floor — knowing something is better
// than the seed — but it does not resolve the corridor, so the safe hold and
// the arm stay in force.
state.floorM =
takeWhole || !Number.isFinite(state.floorM)
? floor
: Math.max(state.floorM, floor);
if (cold.length && !state.meshProbeCoveredCold) return false;
state.floorKnown = true;
return true;
}
/**
* Highest rendered surface across a handful of corridor cells, with the number
* of cells that actually answered — a cell whose tiles are not streamed yet
* contributes nothing, and the caller must not mistake silence for flat ground.
* @param {Cesium.Scene|undefined} scene The live scene.
* @param {Array<{lat: number, lon: number}>} cells Cells to probe.
* @returns {{heightM: number, sampled: number, requested: number}} The reading.
*/
export function probeMeshFloorM(scene, cells) {
const requested = Array.isArray(cells) ? cells.length : 0;
const empty = { heightM: Number.NaN, sampled: 0, requested };
if (!scene || typeof scene.sampleHeight !== 'function' || !requested)
return empty;
let heightM = Number.NaN;
let sampled = 0;
for (const cell of cells) {
try {
const carto = geo.cartographic.fromDegrees(
cell.lon,
cell.lat,
0,
_probeCarto,
);
const height = scene.sampleHeight(carto);
if (!Number.isFinite(height)) continue;
sampled += 1;
heightM = Number.isFinite(heightM) ? Math.max(heightM, height) : height;
} catch {
/* tiles not ready for this cell */
}
}
return { heightM, sampled, requested };
}
/**
* Build the state for one cinematic route flight.
* @param {Object} options
* @param {Cesium.Cartesian3[]} options.pts Route vertices.
* @param {number[]} options.cumM Cumulative arc length per vertex.
* @param {string} [options.speed] slow | normal | fast.
* @param {Function|null} [options.floorFn] (latDeg, lonDeg) => floor metres.
* @param {Function|null} [options.warmFn] (cells) => void — corridor floor warm.
* @param {Function|null} [options.probeFn] (cells) => {heightM, sampled} —
* synchronous rendered-mesh probe, fired at most ONCE per flight and only for
* the cells the cached floor could not answer.
* @param {number} [options.cameraHeightM] Camera height at start, for the cold seed.
* @param {boolean} [options.reducedMotion] Flatten bank + altitude shaping.
* @returns {Object} Motion state for advanceRouteFlight().
*/
export function createRouteFlight({
pts,
cumM,
speed = 'normal',
floorFn = null,
warmFn = null,
probeFn = null,
cameraHeightM = Number.NaN,
reducedMotion = false,
}) {
const totalM = cumM[cumM.length - 1];
const cruiseMps = ROUTE_M_S[speed] || ROUTE_M_S.normal;
// The 0.5 s floor keeps a degenerate route from being an instant teleport (it
// also divides the profile). It is the one case where the speed word is not
// the mean: routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly slower
// than asked. Those are shorter than the camera is tall — nothing to see.
const durationS = Math.max(0.5, totalM / cruiseMps);
const pathHeightM = geo.cartographic.fromCartesian(
pts[0],
geo.ellipsoid.WGS84,
_warmCarto,
).height;
const state = {
kind: 'route',
mode: 'continuous',
direction: 'forward',
speed,
pts,
cumM,
totalM,
durationS,
ramp: routeRampFraction(durationS),
u: 0,
traveled: 0,
floorFn,
warmFn,
probeFn,
reducedMotion,
floorM: Number.NaN,
floorKnown: false,
coldSeedFloorM: routeColdSeedFloorM(pathHeightM, cameraHeightM),
// The one altitude we can defend without terrain data: the camera is
// already there, and the user is already looking at the world from it. It
// is a NON-DESCENT guarantee, not a clearance guarantee — nothing can
// promise clearance over ground that was never measured.
safeHoldHeightM: Number.isFinite(cameraHeightM)
? cameraHeightM
: Number.NaN,
coldFrames: 0,
floorFromMeshProbe: false,
meshProbeSpent: false,
meshProbeFloorM: Number.NaN,
meshProbeCoveredCold: false,
armS: 0,
armed: false,
departed: false,
appliedHeightM: Number.NaN,
warmedCells: 0,
warmDueS: ROUTE_WARM_INTERVAL_S,
offsetM: Number.NaN,
bankLeadDeg: 0,
bankDeg: 0,
appliedBankDeg: 0,
liftBankDeg: 0,
headingDir: null,
groundSpeedMps: 0,
};
// Warm the head of the corridor before the first frame renders, then check
// whether anything is warm ALREADY (contact traffic, or a second run over the
// same route) — that flight needs no arming and no hold at all.
warmRouteCorridor(state, 0, ROUTE_WARM_START_M);
acquireCorridorFloor(state, true);
return state;
}
/**
* Advance one dolly frame. Returns the camera pose to apply; the caller owns
* the viewer (so this stays testable without one).
* @param {Object} state From createRouteFlight().
* @param {number} dt Seconds elapsed.
* @returns {{finished: boolean, eye: Cesium.Cartesian3, direction: Cesium.Cartesian3,
* up: Cesium.Cartesian3, bankDeg: number, heightM: number, aglM: number,
* groundSpeedMps: number, progress: number}} The frame.
*/
export function advanceRouteFlight(state, dt) {
const step = Math.min(0.25, Math.max(0, Number.isFinite(dt) ? dt : 0));
// ARMING. The corridor warm is fire-and-forget, so the alternative to waiting
// is racing it — and losing that race means rendering the first frames at an
// altitude derived from nothing. While armed the camera is not touched at
// all: no teleport onto the route, no descent. The wait is covered by the
// model speaking its confirmation, and a warm cache skips it entirely.
const canAnswer =
typeof state.floorFn === 'function' || typeof state.probeFn === 'function';
if (
canAnswer &&
!state.floorKnown &&
!state.departed &&
state.armS < ROUTE_ARM_S
) {
state.armS += step;
if (!acquireCorridorFloor(state, true)) {
return { arming: true, finished: false, progress: 0, bankDeg: 0 };
}
}
state.departed = true;
state.u = Math.min(1, (state.u || 0) + step / state.durationS);
const profile = routeSpeedProfile(state.u, state.ramp);
const traveled = state.totalM * profile.distance;
state.traveled = traveled;
const cruiseMps = state.totalM / (state.durationS * (1 - state.ramp));
state.groundSpeedMps = cruiseMps * profile.speed;
const pos = arcPoint(state, traveled, _framePos);
const carto = geo.cartographic.fromCartesian(
pos,
geo.ellipsoid.WGS84,
_frameCarto,
);
const up = geo.ellipsoid.WGS84.geodeticSurfaceNormalCartographic(
carto,
_frameUp,
);
// Planned turn: compare where we came from with where we are going, over a
// window centred on the camera. Peaks AT the corner, tapers either side.
const halfWindowM = Math.max(20, (ROUTE_BANK_WINDOW_S * cruiseMps) / 2);
const inbound = horizontalChord(
state,
traveled - halfWindowM,
traveled,
up,
_frameIn,
);
const outbound = horizontalChord(
state,
traveled,
traveled + halfWindowM,
up,
_frameOut,
);
const turnRateDegS =
inbound && outbound
? geo.math.toDegrees(signedTurnRad(inbound, outbound, up)) /
ROUTE_BANK_WINDOW_S
: 0;
const bankTarget = routeBankTargetDeg(turnRateDegS, state.reducedMotion);
state.bankLeadDeg = approachValue(
state.bankLeadDeg,
bankTarget,
ROUTE_BANK_LEAD_RATE,
step,
);
state.bankDeg = approachValue(
state.bankDeg,
state.bankLeadDeg,
ROUTE_BANK_SETTLE_RATE,
step,
);
// Wings level for takeoff and landing. The speed profile is already a
// smoothstep envelope that is 1 across the cruise and exactly 0 at both ends,
// so reusing it unwinds the roll as the dolly slows — and guarantees the LAST
// applied frame is level, with no snap to get there.
const appliedBankDeg = state.bankDeg * profile.speed;
// Gaze leads along the arc, then eases toward the new heading so corners
// swing like a crane shot instead of a whip pan.
const lookaheadM = Math.min(
ROUTE_LOOKAHEAD_MAX_M,
Math.max(ROUTE_LOOKAHEAD_MIN_M, ROUTE_LOOKAHEAD_S * cruiseMps),
);
const gaze =
horizontalChord(state, traveled, traveled + lookaheadM, up, _frameGaze) ||
outbound ||
inbound;
if (gaze && !state.headingDir) state.headingDir = geo.cartesian3.clone(gaze);
else if (gaze) {
// Rotate the heading TOWARD the gaze about the local up, rather than
// lerping the two vectors. A Cartesian lerp cannot cross an antipodal pair
// (a U-turn): below t=0.5 the blend still points backwards, and no
// per-frame t ever reaches 0.5, so the camera stayed reversed for the whole
// return leg. An angle always crosses.
const k = 1 - Math.exp(-ROUTE_DIR_SMOOTH_RATE * step);
const turnToGaze = signedTurnRad(state.headingDir, gaze, up);
// signedTurnRad is + for a RIGHT turn; a positive rotation about up is a
// LEFT turn, so the step is negated.
const rotation = geo.matrix3.fromQuaternion(
geo.quaternion.fromAxisAngle(up, -turnToGaze * k, _headingQuat),
_headingMatrix,
);
const turned = geo.matrix3.multiplyByVector(
rotation,
state.headingDir,
_frameDir,
);
const vertical = geo.cartesian3.multiplyByScalar(
up,
geo.cartesian3.dot(turned, up),
_chordVertical,
);
geo.cartesian3.subtract(turned, vertical, turned);
if (geo.cartesian3.magnitude(turned) > 1e-6) {
geo.cartesian3.normalize(turned, state.headingDir);
}
}
// A path with no horizontal extent (identical lat/lon, differing heights)
// has no azimuth to fly: point east so the frame stays orthonormal.
if (!state.headingDir) {
const east = geo.cartesian3.fromElements(-pos.y, pos.x, 0, _frameGaze);
state.headingDir =
geo.cartesian3.magnitude(east) > 1e-6
? geo.cartesian3.normalize(east, geo.cartesian3.create())
: geo.cartesian3.fromElements(1, 0, 0, geo.cartesian3.create());
}
const heading = state.headingDir;
// Locked pitch: heading gives the azimuth, the pitch never wanders.
const pitch = geo.math.toRadians(ROUTE_PITCH_DEG);
const direction = geo.cartesian3.normalize(
geo.cartesian3.add(
geo.cartesian3.multiplyByScalar(heading, Math.cos(pitch), _frameDir),
geo.cartesian3.multiplyByScalar(up, Math.sin(pitch), _frameLevelUp),
_frameDir,
),
_frameDir,
);
// Orthonormal camera frame, then roll it about its own forward axis: a
// positive rotation drops the right wing, which is what a right turn wants.
const right = geo.cartesian3.normalize(
geo.cartesian3.cross(direction, up, _frameRight),
_frameRight,
);
const levelUp = geo.cartesian3.normalize(
geo.cartesian3.cross(right, direction, _frameLevelUp),
_frameLevelUp,
);
const bankRad = geo.math.toRadians(appliedBankDeg);
let bankedUp = levelUp;
if (Math.abs(bankRad) > 1e-6) {
const quat = geo.quaternion.fromAxisAngle(direction, bankRad, _bankQuat);
const rotation = geo.matrix3.fromQuaternion(quat, _bankMatrix);
bankedUp = geo.matrix3.multiplyByVector(rotation, levelUp, _frameBankedUp);
}
// Keep the corridor ahead of the camera warm. The batch dedupes to coarse
// cells, skips warm ones and queues contenders, so a repeat costs nothing.
state.warmDueS -= step;
if (state.warmDueS <= 0) {
state.warmDueS = ROUTE_WARM_INTERVAL_S;
warmRouteCorridor(state, traveled, ROUTE_WARM_AHEAD_M);
}
// Ground floor: the max of here and just ahead, so a rise is cleared BEFORE
// the camera reaches it. Both are cached reads — nothing samples the mesh.
let sampledFloor = Number.NaN;
if (typeof state.floorFn === 'function') {
const aheadPos = arcPoint(state, traveled + lookaheadM / 2, _frameAheadPos);
const aheadCarto = geo.cartographic.fromCartesian(
aheadPos,
geo.ellipsoid.WGS84,
_frameAheadCarto,
);
try {
const here = state.floorFn(
geo.math.toDegrees(carto.latitude),
geo.math.toDegrees(carto.longitude),
);
const ahead = state.floorFn(
geo.math.toDegrees(aheadCarto.latitude),
geo.math.toDegrees(aheadCarto.longitude),
);
const warm = [here, ahead].filter((value) => Number.isFinite(value));
if (warm.length) sampledFloor = Math.max(...warm);
} catch {
sampledFloor = Number.NaN;
}
}
if (!Number.isFinite(sampledFloor)) {
// NEVER descend blind. A cold cell is missing data, not flat ground — the
// route's own vertices carry height 0, so trusting them put the eye 1.3 km
// UNDER Albuquerque. Hold the last floor we actually knew; before we have
// ever known one, hold the conservative seed captured at flight start.
state.floorM = Number.isFinite(state.floorM)
? state.floorM
: state.coldSeedFloorM;
state.coldFrames += 1;
} else if (!state.floorKnown) {
// Data arrived AFTER the arm gave up. Easing is the right move now: the
// camera is already flying, so taking the gap between the safety hold and
// the ground in one frame would snap. (Pre-departure acquisition takes it
// whole — see acquireCorridorFloor — because nothing is moving yet.)
state.floorM = routeFloorHoldM(state.floorM, sampledFloor, step);
state.floorKnown = true;
} else {
state.floorM = routeFloorHoldM(state.floorM, sampledFloor, step);
}
state.liftBankDeg = approachValue(
state.liftBankDeg,
appliedBankDeg,
ROUTE_LIFT_TRACK_RATE,
step,
);
const bankFraction = state.liftBankDeg / ROUTE_BANK_MAX_DEG;
state.offsetM = approachValue(
state.offsetM,
routeAltitudeOffsetM(traveled, bankFraction, state.reducedMotion),
ROUTE_ALT_SMOOTH_RATE,
step,
);
// Two floors, two jobs. The SMOOTHED floor shapes the ride, so a cell
// boundary does not pop the eye. The RAW sample owns the safety clamp, so a
// real rise is cleared on the frame it is seen, smoothing or not.
let heightM = Math.max(
routeEyeHeightM(state.floorM, state.offsetM),
(Number.isFinite(sampledFloor) ? sampledFloor : state.floorM) +
ROUTE_MIN_CLEARANCE_M,
);
// Still no terrain data (the arm timed out, or the warm never landed at all):
// hold the launch altitude for as long as that lasts. It is not a clearance
// guarantee — nothing can promise clearance over ground that was never
// measured — but the dolly will not take the camera DOWN into the unknown.
if (!state.floorKnown && Number.isFinite(state.safeHoldHeightM)) {
heightM = Math.max(heightM, state.safeHoldHeightM);
}
// Releasing that hold onto late data is a controlled descent, never a drop.
if (Number.isFinite(state.appliedHeightM)) {
heightM = Math.max(
heightM,
state.appliedHeightM - ROUTE_MAX_DESCENT_MPS * step,
);
}
state.appliedHeightM = heightM;
const eye = geo.cartesian3.fromRadians(
carto.longitude,
carto.latitude,
heightM,
geo.ellipsoid.WGS84,
_frameEye,
);
state.appliedBankDeg = appliedBankDeg;
return {
finished: state.u >= 1,
eye,
direction,
up: bankedUp,
bankDeg: appliedBankDeg,
heightM,
aglM: heightM - state.floorM,
groundSpeedMps: state.groundSpeedMps,
progress: state.u,
};
}
/* ── Camera rig ─────────────────────────────────────────────────────────────
* A motion drives one globe engine's camera through its rig, and remembers
* which one.
*
* The rig speaks only the engine-neutral globe contract
* (src/globe/contract.js): camera.pose/height/setView/lookAt/release/
* transform/flightActive/following/followChanged/cancelFlight, frames.preRender,
* host.canvas/size, projector.worldToWindow, surface and render.request. The
* same verbs therefore run on Navara, on Cesium (src/globe/cesium) and on the
* fake engine. Its listeners exist only while one of its motions runs, so an
* engine that is parked or destroyed holds nothing of ours.
* -------------------------------------------------------------------------- */
/** Manual camera input that reclaims control (the cancelFlight reflex). */
const MANUAL_INPUT_EVENTS = Object.freeze([
'pointerdown',
'touchstart',
'wheel',
]);
/** Cesium's PerspectiveFrustum defaults: the depth planes an engine rig admits
* a globe rotation against, as a default Cesium camera would. */
const ENGINE_FRUSTUM = Object.freeze({ near: 1, far: 500_000_000 });
const newVector = () => geo.cartesian3.create();
/** Vectors rotated about `axis` by `angle` (right-handed), as fresh values. */
function rotateVectors(axis, angle, vectors) {
const rotation = geo.matrix3.fromQuaternion(
geo.quaternion.fromAxisAngle(axis, angle, geo.quaternion.create()),
geo.matrix3.create(),
);
return vectors.map((vector) =>
geo.matrix3.multiplyByVector(rotation, vector, newVector()),
);
}
/** Direction and up for heading/pitch/roll at `position`, as Cesium's setView
* builds them (heading 0 looks north, negative pitch looks down). */
function orientationVectors(position, heading, pitch, roll) {
const frame = geo.transforms.eastNorthUpToFixedFrame(
position,
geo.ellipsoid.WGS84,
);
const east = geo.cartesian3.create(frame[0], frame[1], frame[2]);
const north = geo.cartesian3.create(frame[4], frame[5], frame[6]);
const up = geo.cartesian3.create(frame[8], frame[9], frame[10]);
const combine = (e, n, u) =>
geo.cartesian3.add(
geo.cartesian3.add(
geo.cartesian3.multiplyByScalar(east, e, newVector()),
geo.cartesian3.multiplyByScalar(north, n, newVector()),
newVector(),
),
geo.cartesian3.multiplyByScalar(up, u, newVector()),
newVector(),
);
const cosPitch = Math.cos(pitch);
const direction = geo.cartesian3.normalize(
combine(
Math.sin(heading) * cosPitch,
Math.cos(heading) * cosPitch,
Math.sin(pitch),
),
newVector(),
);
const levelRight = combine(Math.cos(heading), -Math.sin(heading), 0);
const levelUp = geo.cartesian3.cross(levelRight, direction, newVector());
const rolledUp = geo.cartesian3.add(
geo.cartesian3.multiplyByScalar(levelUp, Math.cos(roll), newVector()),
geo.cartesian3.multiplyByScalar(levelRight, Math.sin(roll), newVector()),
newVector(),
);
return {
direction,
up: geo.cartesian3.normalize(rolledUp, newVector()),
};
}
/** The keyhole admission's view of a contract camera pose. */
function engineKeyholeView(pose) {
return {
position: pose.position,
direction: pose.direction,
right:
pose.right ??
geo.cartesian3.normalize(
geo.cartesian3.cross(pose.direction, pose.up, newVector()),
newVector(),
),
up: pose.up,
perspective: true,
fovy: pose.fovy,
aspectRatio: pose.aspectRatio,
near: ENGINE_FRUSTUM.near,
far: ENGINE_FRUSTUM.far,
xOffset: 0,
yOffset: 0,
};
}
/** The globe contract's camera (see the block comment above). */
function createEngineRig(engine) {
const camera = engine.camera;
const pose = () => camera.pose();
const place = (position, direction, up) =>
camera.setView({ destination: position, orientation: { direction, up } });
return {
kind: 'engine',
owner: engine,
engine,
position: () => pose().position,
pitch: () => pose().pitch,
heightM: () => camera.height(),
orbitPose: pose,
// The pose the frame limit (src/globeInView.js) judges: the camera pose
// and the eye's height.
framePose() {
const p = pose();
return { ...p, height: p.cartographic.height };
},
flightBusy: () => camera.flightActive(),
tracking: () => Boolean(camera.following()),
trackedLabel() {
const handle = camera.following();
return handle
? handle.name || handle.label?.id || 'the tracked target'
: null;
},
// Both engines draw only the 3D globe.
is3D: () => true,
unlocked: () =>
camera
.transform()
.every((value, index) => value === geo.matrix4.IDENTITY[index]),
lookAt: (target, hpr) =>
camera.lookAt(target, {
heading: hpr.heading,
pitch: hpr.pitch,
range: hpr.range,
}),
release: () => camera.release(),
// Cesium's moveLeft/moveRight translate along the camera's right vector
// and moveUp/moveDown along its up vector.
move(direction, amount) {
const p = pose();
const sideways = direction === 'left' || direction === 'right';
const sign = direction === 'left' || direction === 'down' ? -1 : 1;
const step = geo.cartesian3.multiplyByScalar(
sideways ? p.right : p.up,
sign * amount,
newVector(),
);
place(
geo.cartesian3.add(p.position, step, newVector()),
p.direction,
p.up,
);
},
// Cesium's lookUp/lookDown turn the view about the camera's right vector
// and lookLeft/lookRight about its up vector; the position stays.
look(direction, angle) {
const p = pose();
const vertical = direction === 'up' || direction === 'down';
const sign = direction === 'up' || direction === 'left' ? 1 : -1;
const [nextDirection, nextUp] = rotateVectors(
vertical ? p.right : p.up,
sign * angle,
[p.direction, p.up],
);
place(p.position, nextDirection, nextUp);
},
// Cesium's camera.rotate: position and basis turn about an axis through
// Earth's centre; a positive angle turns the camera clockwise about it.
rotate(axis, angle) {
const p = pose();
const [position, direction, turnedUp] = rotateVectors(axis, -angle, [
p.position,
p.direction,
p.up,
]);
const right = geo.cartesian3.cross(direction, turnedUp, newVector());
place(
position,
direction,
geo.cartesian3.cross(right, direction, newVector()),
);
},
setFrame: (eye, direction, up) => place(eye, direction, up),
// Put the horizon back: the route dolly is the only motion that rolls
// the camera, and a bank released mid-flight would stay until some later
// motion happened to level it. Heading, pitch and position are kept.
levelRoll() {
const p = pose();
if (Math.abs(geo.math.negativePiToPi(p.roll)) <= 1e-5) return false;
camera.setView({
destination: p.position,
orientation: { heading: p.heading, pitch: p.pitch, roll: 0 },
});
return true;
},
surface: () => engine.surface,
ellipsoid: () => geo.ellipsoid.WGS84,
supportedEllipsoid: () => true,
viewport: () => engine.host.size(),
keyholeView: () => engineKeyholeView(pose()),
// projectEarthDiscToViewport's test on the contract: Earth's centre in
// front of the camera and on screen, with a disc of finite size.
earthDiscProjects(width, height) {
const p = pose();
const distance = geo.cartesian3.magnitude(p.position);
if (
!Number.isFinite(distance) ||
distance <= geo.ellipsoid.WGS84.maximumRadius
)
return false;
const toCenter = geo.cartesian3.negate(p.position, newVector());
if (geo.cartesian3.dot(p.direction, toCenter) <= 0) return false;
const center = engine.projector.worldToWindow(geo.cartesian3.ZERO);
if (!center || !Number.isFinite(center.x) || !Number.isFinite(center.y))
return false;
return Boolean(earthDiscScreenRadius(distance, height, p.fovy));
},
resetView() {
const p = pose();
const position = geo.cartesian3.fromRadians(
p.cartographic.longitude,
p.cartographic.latitude,
GLOBE_VIEW.heightM,
geo.ellipsoid.WGS84,
);
const { direction, up } = orientationVectors(
position,
0,
geo.math.toRadians(GLOBE_VIEW.pitchDeg),
0,
);
return engineKeyholeView({
position,
direction,
up,
fovy: p.fovy,
aspectRatio: p.aspectRatio,
});
},
captureGlobePose() {
const p = pose();
return {
position: p.position,
direction: p.direction,
up: geo.cartesian3.normalize(p.up, newVector()),
right: p.right,
};
},
takeGlobePose(globePose) {
camera.cancelFlight();
camera.release();
place(globePose.position, globePose.direction, globePose.up);
},
};
}
const engineRigs = new WeakMap();
/** One rig per engine, so a motion's rig compares by identity. */
function engineRigFor(engine) {
let rig = engineRigs.get(engine);
if (!rig) engineRigs.set(engine, (rig = createEngineRig(engine)));
return rig;
}
/** The members an engine rig reads, as paths on the engine. */
const ENGINE_RIG_MEMBERS = Object.freeze([
'camera.pose',
'camera.height',
'camera.setView',
'camera.lookAt',
'camera.release',
'camera.transform',
'camera.flightActive',
'camera.following',
'camera.cancelFlight',
'frames.preRender.addEventListener',
'camera.followChanged.addEventListener',
'host.size',
'projector.worldToWindow',
'render.request',
]);
/**
* Whether the camera verbs (move_camera, and fly_route over a route list) can
* drive this target: a globe engine with every contract member the rig
* reads. The voice gate asks this instead of "is there a viewer".
* @param {object|null|undefined} target A globe engine.
* @returns {boolean}
*/
export function cameraVerbsSupported(target) {
if (!target || target.isDestroyed?.()) return false;
return ENGINE_RIG_MEMBERS.every(
(path) =>
typeof path
.split('.')
.reduce(
(value, key) => (value == null ? value : value[key]),
target,
) === 'function',
);
}
/* ── Motion state ───────────────────────────────────────────────────────── */
/** The rig new motions start on: the latest initCameraVerbs target. */
let _rig = null;
let _getTarget = null;
let _active = null; // { kind, rig, direction, speed, mode, motionId, ...state }
/** The engine listeners of the running motion, or null. */
let _engineBinding = null;
function unbindEngineMotion() {
const binding = _engineBinding;
_engineBinding = null;
binding?.remove();
}
/**
* Bind the running motion to its engine: a frame listener that advances it,
* the manual-input reflex on the engine's canvas and the follow-camera yield.
* A Directions dolly can move between engines (suspendRouteFlight /
* resumeRouteFlight): geometry and flight time stay with the motion, the
* listeners belong only to the engine it runs on now.
*/
function bindEngineMotion(rig) {
unbindEngineMotion();
const { engine } = rig;
const removers = [];
const canvas = engine.host?.canvas;
if (typeof canvas?.addEventListener === 'function') {
const cancel = () => interruptCameraMotion('manual-input');
for (const event of MANUAL_INPUT_EVENTS) {
canvas.addEventListener(event, cancel, { passive: true });
removers.push(() => canvas.removeEventListener(event, cancel));
}
}
// A follow taking the camera (Cockpit can acquire and clear one between
// two frames) yields a globe rotation at once, before its next frame, and
// a pivoting tilt, whose lookAt would fight the follow camera every frame.
// Other motions carry on.
removers.push(
engine.camera.followChanged.addEventListener((handle) => {
if (!handle || _active?.rig !== rig) return;
if (_active.kind === 'rotate_globe')
interruptCameraMotion('globe-camera-owner-changed');
else if (_active.kind === 'tilt' && _active.hpr)
interruptCameraMotion('tilt-camera-owner-changed');
}),
);
removers.push(
engine.frames.preRender.addEventListener(() => {
tickMotion(rig);
if (_active?.rig === rig) engine.render.request('camera-verb');
}),
);
// Its first frame takes the minimum step (a resumed flight must not jump
// across the time it was parked).
if (_active?.rig === rig) _active.lastMs = undefined;
_engineBinding = {
rig,
remove: () => {
for (const remove of removers) remove();
},
};
engine.render.request('camera-verb');
}
/**
* Park the Directions route flight `id` for an engine switch: its listeners
* go, its state is returned for resumeRouteFlight.
* @param {number} id The flight's motion id.
* @returns {object|null} The parked state, or null when `id` is not running.
*/
export function suspendRouteFlight(id) {
if (!id || _active?.motionId !== id) return null;
const state = _active;
_active = null;
unbindEngineMotion();
releaseContinuousRender('camera-verb');
return state;
}
/**
* Continue a parked route flight on `engine`.
* @returns {boolean} Whether it runs again.
*/
export function resumeRouteFlight(state, engine) {
if (!state || !engine || _active) return false;
state.rig = engineRigFor(engine);
_active = state;
bindEngineMotion(state.rig);
holdContinuousRender('camera-verb');
return true;
}
/** Monotonic id for the motion currently running; 0 means "no motion". */
let _motionSeq = 0;
/** Canvas grabs, touches and wheel turns since load. */
let _manualInputCount = 0;
/**
* Lets a caller holding a motion back (behind a fly-to) see whether the user
* took the camera meanwhile; Cesium does not cancel a flight on input.
* @returns {number} Manual camera inputs so far.
*/
export function manualCameraInputCount() {
// Counting starts the first time a caller asks: the count is only ever
// compared with an earlier one, and until then no canvas holds a listener
// of ours.
if (!_countingInput) {
_countingInput = true;
countManualInput(_rig?.engine ?? null);
}
return _manualInputCount;
}
/** Whether a caller has asked for the count, so input is counted. */
let _countingInput = false;
/** Removes the input counter from the canvas it listens on, or null. */
let _inputCountRemover = null;
/**
* Count manual camera input on `engine`'s canvas, the one new motions start
* on, whether or not a motion runs (a motion held back behind a flight is not
* running yet). Null, or no caller counting yet, stops counting. The engine
* keeps the counter until releaseCameraVerbs or another engine takes over.
*/
function countManualInput(engine) {
_inputCountRemover?.();
_inputCountRemover = null;
if (!_countingInput) return;
const canvas = engine?.host?.canvas;
if (typeof canvas?.addEventListener !== 'function') return;
const count = () => {
_manualInputCount += 1;
};
for (const event of MANUAL_INPUT_EVENTS)
canvas.addEventListener(event, count, { passive: true });
_inputCountRemover = () => {
for (const event of MANUAL_INPUT_EVENTS)
canvas.removeEventListener?.(event, count);
};
}
/**
* Install a motion and stamp it with a fresh id. The id is what lets a caller
* that started a flight stop THAT flight later without stopping whatever has
* replaced it in the meantime. The motion binds its engine listeners here.
* @param {object} state Motion state (with its rig).
* @returns {object} The installed state.
*/
function setActiveMotion(state) {
_motionSeq += 1;
state.motionId = _motionSeq;
_active = state;
bindEngineMotion(state.rig);
return state;
}
/**
* @returns {number} Id of the running motion, or 0 when the camera is idle.
*/
export function activeCameraMotionId() {
return _active?.motionId || 0;
}
/**
* Stop a motion only while it is still the one running. A feature that owns a
* flight calls this on clear/teardown: if the user (or voice, or a tracked
* entity) has since taken the camera, the newer motion is left alone.
* @param {number} motionId Id returned when the motion started.
* @param {string} [reason] Diagnostic label.
* @returns {{wasActive: boolean, reason: string, leveled: boolean}}
*/
export function interruptCameraMotionIfActive(
motionId,
reason = 'owner-cancel',
) {
if (!motionId || _active?.motionId !== motionId) {
return { wasActive: false, reason, leveled: false };
}
return interruptCameraMotion(reason);
}
// The frame share that in-place voice turns measure their limit against, with
// the pose the last voice turn left the camera in. A turn that starts where
// the last one left off keeps that baseline (raised if the planet now fills
// more of the frame), so repeating a request cannot take a little more each
// time. Once anything else has moved or turned the camera, a turn starts over
// from what is on screen.
let _lookBaseline = null;
// The pre-check's proof that a half-degree turn from this pose keeps the planet
// in view: which way, from which position and direction. A motion that starts from that
// pose turns at least that far, so a request reported as done really moves
// even when a smaller first step lands in a dip of the sampled share.
const PROVEN_TURN_RAD = geo.math.toRadians(0.5);
let _provenLook = null;
/** The rig's look direction for a globeInView look name ('lookUp', ...). */
const LOOK_DIRECTIONS = Object.freeze({
lookUp: 'up',
lookDown: 'down',
lookLeft: 'left',
lookRight: 'right',
});
/** The part of the frame a viewer can see: the scope keyhole when it is on. */
function visibleFrame() {
return { keyholeRadius: isScopeMaskEnabled() ? KEYHOLE_OUTER_RADIUS : 0 };
}
/** Whether `pose` is where `mark` (a position and direction) left it. */
function sameLookPose(mark, pose) {
return (
geo.cartesian3.equalsEpsilon(mark.position, pose.position, 0, 1) &&
geo.cartesian3.equalsEpsilon(mark.direction, pose.direction, 0, 1e-9)
);
}
/** The frame share an in-place turn from `pose` is limited against. */
function lookBaselineShare(pose) {
const share = globeFrameShare(pose, visibleFrame());
const continues = _lookBaseline && sameLookPose(_lookBaseline, pose);
_lookBaseline = {
position: geo.cartesian3.clone(pose.position),
direction: geo.cartesian3.clone(pose.direction),
share: continues ? Math.max(_lookBaseline.share, share) : share,
};
return _lookBaseline.share;
}
/**
* One in-place look step of motion `m` on `rig`. From orbit a free globe
* camera turns only as far as keeps the planet in frame, measured against the
* baseline the turn started from, then the motion ends there.
*/
function lookWithinFrame(rig, m, look, angle) {
let allowed = angle;
if (isFreeGlobeCamera(rig.engine)) {
const pose = rig.framePose();
if (m.globeShareAtStart === undefined) {
m.globeShareAtStart = lookBaselineShare(pose);
m.provenTurnRad = lookProven(pose, look) ? PROVEN_TURN_RAD : 0;
m.turnedRad = 0;
}
_provenLook = null;
allowed = lookAngleWithinFrame(pose, look, angle, {
...visibleFrame(),
startShare: m.globeShareAtStart,
});
const owed = Math.min(angle, m.provenTurnRad - m.turnedRad);
if (allowed < owed) allowed = owed;
m.turnedRad += allowed;
}
if (allowed > 0) rig.look(LOOK_DIRECTIONS[look], allowed);
// The pose this turn leaves, for a turn that continues from it.
if (_lookBaseline)
_lookBaseline.direction = geo.cartesian3.clone(rig.framePose().direction);
if (allowed < angle) interruptCameraMotion('globe-out-of-frame');
}
/**
* The in-place look a pitch change from `fromPitch` to `goalPitch` makes:
* 'lookUp', 'lookDown', or null when it does not move. A tilt is judged by
* the way its pitch moves, whatever form or direction word it came in.
*/
function tiltLook(fromPitch, goalPitch) {
if (!Number.isFinite(fromPitch) || !Number.isFinite(goalPitch)) return null;
if (goalPitch > fromPitch) return 'lookUp';
return goalPitch < fromPitch ? 'lookDown' : null;
}
/** Tilt `m` in place to `goalPitch`, as far as the frame limit allows. */
function tiltInPlaceWithinFrame(rig, m, goalPitch) {
const pitch = rig.pitch();
const look = tiltLook(pitch, goalPitch);
if (look) lookWithinFrame(rig, m, look, Math.abs(goalPitch - pitch));
}
/**
* The pitch an in-place tilt from `rig`'s pose toward `goalPitch` reaches
* before the frame limit stops it, judged as its steps will be: `goalPitch`
* itself when the planet stays in frame the whole way, or the camera is not a
* free globe camera. The steps run on a copy of the pose, each looking by
* the pitch still to go as the tilt's frames do, because a rolled camera's
* look turns its pitch by less than the look angle.
*/
function tiltPitchWithinFrame(rig, goalPitch) {
const pose = rig.framePose();
const look = tiltLook(pose.pitch, goalPitch);
if (!look || !isFreeGlobeCamera(rig.engine)) return goalPitch;
const frame = { ...visibleFrame(), startShare: lookBaselineShare(pose) };
// A proven half degree is turned whatever the sampled share says.
let owed = lookProven(pose, look) ? PROVEN_TURN_RAD : 0;
let probe = pose;
let pitch = pose.pitch;
for (let i = 0; i < 32; i += 1) {
if (tiltLook(pitch, goalPitch) !== look) return goalPitch;
const angle = Math.abs(goalPitch - pitch);
if (angle < 1e-6) return goalPitch;
const allowed = Math.max(
lookAngleWithinFrame(probe, look, angle, frame),
Math.min(angle, owed),
);
owed -= allowed;
if (allowed > 0) {
probe = lookPose(probe, look, allowed);
pitch = posePitch(probe);
}
if (allowed < angle) return pitch;
}
return pitch;
}
/** The reply's note for a tilt the frame limit stops short of its angle. */
function tiltFrameNote(pitch) {
return `Stopped at ${Math.round(geo.math.toDegrees(pitch))}°: from this height a shallower angle would turn the globe out of view. Zoom in to tilt further.`;
}
/** True when the pre-check proved a half-degree `look` from `pose`. */
function lookProven(pose, look) {
return _provenLook?.look === look && sameLookPose(_provenLook, pose);
}
/**
* The check a voice in-place turn (`look`: 'lookUp', 'lookDown', 'lookLeft'
* or 'lookRight') must pass from orbit: refused when even half a degree would
* cross the frame limit, otherwise proven for that half degree from this pose.
* With `released`, the turn runs through a navigation that first releases a
* tracked or locked camera and keeps its world pose. The frame measure and the
* turn are the same in any reference frame, so such a camera is judged as it
* is, before the release, and a refusal leaves tracking as it was. Otherwise a
* camera that is not a free globe camera is not checked. Returns the refusal,
* or null.
*/
function checkLookFromOrbit(rig, look, { released = false } = {}) {
_provenLook = null;
if (!rig.is3D()) return null;
if (!released && !isFreeGlobeCamera(rig.engine)) return null;
const pose = rig.framePose();
if (
lookStepLosesGlobe(pose, look, PROVEN_TURN_RAD, {
...visibleFrame(),
startShare: lookBaselineShare(pose),
})
)
return {
ok: false,
action: 'move_camera',
error:
'From this height that would turn the globe out of view — zoom in first, or turn the other way.',
};
_provenLook = {
look,
position: geo.cartesian3.clone(pose.position),
direction: geo.cartesian3.clone(pose.direction),
};
return null;
}
/** Stop any active motion. Returns whether one was running. */
export function interruptCameraMotion(reason = 'interrupt') {
const motion = _active;
const wasActive = Boolean(motion);
const rig = motion?.rig ?? null;
let leveled = false;
if (rig) {
// While an entity is TRACKED, the follow camera owns the reference frame —
// resetting the lookAt transform here flings the camera into space (field
// finding). Leave the transform to the tracker; it re-asserts every frame.
let tracking = false;
try {
tracking = rig.tracking();
} catch {
/* teardown race */
}
// A route dolly only ever sets views; it never locks a transform. A
// pivoting tilt swings about its ground point as an orbit does.
if (
!tracking &&
(motion.kind === 'orbit' || (motion.kind === 'tilt' && motion.hpr))
) {
try {
rig.release();
} catch {
/* teardown race */
}
}
// Instant, not eased: the user grabbed the camera, or the flight is over.
// Either way the next thing they hold must be a level horizon.
if (motion.kind === 'route') {
try {
leveled = rig.levelRoll();
} catch {
leveled = false; // teardown race
}
}
}
unbindEngineMotion();
_active = null;
releaseContinuousRender('camera-verb');
return { wasActive, reason, leveled };
}
/** Diagnostics / harness hook. */
export function getActiveCameraMotion() {
if (!_active) return null;
const info = {
kind: _active.kind,
mode: _active.mode,
speed: _active.speed,
motionId: _active.motionId || 0,
rig: _active.rig?.kind ?? null,
};
if (_active.kind === 'route') {
info.progress = _active.u;
info.bankDeg = _active.bankDeg;
info.groundSpeedMps = _active.groundSpeedMps;
info.traveledM = _active.traveled;
info.totalM = _active.totalM;
info.reducedMotion = _active.reducedMotion;
info.arming = !_active.departed;
info.floorKnown = _active.floorKnown;
info.floorFromMeshProbe = _active.floorFromMeshProbe;
info.meshProbeSpent = _active.meshProbeSpent;
}
return info;
}
/** Advance the running motion one frame, when it runs on `rig`. */
function tickMotion(rig) {
const m = _active;
if (!m || m.rig !== rig) return;
// Wall-clock dt: clock.currentTime FREEZES when the app clock isn't
// animating, which starved motion to the 1 ms floor (harness catch).
const nowMs = performance.now();
const dt = Math.min(
0.25,
Math.max(0.001, (nowMs - (m.lastMs ?? nowMs)) / 1000),
);
m.lastMs = nowMs;
stepMotion(m, rig, dt);
}
/** One frame of motion `m` on `rig`. */
function stepMotion(m, rig, dt) {
// `once` motions ease out and self-stop on budget exhaustion. The budget
// starts when the motion does: an orbit still armed for its target spends
// none of it.
let scale = 1;
let finishing = false;
if (m.mode === 'once' && !m.pending) {
m.elapsed = (m.elapsed || 0) + dt;
const t = Math.min(1, m.elapsed / (m.durationS || ONCE.durationS));
scale = 1 - (1 - t) * (1 - t); // ease-out progress share
finishing = t >= 1;
}
try {
if (m.kind === 'orbit' && m.pending) {
// Armed but target-less (started mid-flight, e.g. "fly to X and orbit
// it"): keep trying for a ground target until the camera settles.
m.pendingS = (m.pendingS || 0) + dt;
if (m.pendingS > 30) {
interruptCameraMotion('orbit-arm-timeout');
return;
}
// pickEllipsoid hits the globe from ANY altitude — target existence
// alone is not arrival. Camera flights are scene tweens, and multi-stage
// flights have GAPS between tweens: require the tween queue quiet for a
// continuous 0.8 s before capturing the orbit framing at the REAL
// destination (field finding: Eiffel chain orbited from mid-flight).
if (rig.flightBusy()) {
m.settledS = 0;
return;
}
m.settledS = (m.settledS || 0) + dt;
if (m.settledS < 0.8) return;
const target = _getTarget?.(rig.owner);
if (!target) return;
const { position, heading } = rig.orbitPose();
m.target = target;
m.hpr = orbitOffset(position, heading, target);
m.hprStartHeading = heading;
m.pending = false;
m.elapsed = 0; // once-mode budget starts when the orbit actually begins
return;
}
if (m.kind === 'orbit') {
const rate =
geo.math.toRadians(ORBIT_DEG_S[m.speed]) *
(m.direction === 'left' ? -1 : 1);
if (m.mode === 'once') {
const total =
geo.math.toRadians(ONCE.orbitDeg) * (m.direction === 'left' ? -1 : 1);
m.hpr.heading = m.hprStartHeading + total * scale;
} else {
m.hpr.heading += rate * dt;
}
rig.lookAt(m.target, m.hpr);
} else if (m.kind === 'pan') {
const heightM = Math.max(50, rig.heightM());
const step =
m.mode === 'once'
? heightM * ONCE.panViewFraction * (scale - (m.lastScale || 0))
: heightM * PAN_VIEW_FRACTION_S[m.speed] * dt;
m.lastScale = scale;
rig.move(m.direction, step);
} else if (m.kind === 'tilt') {
tickTilt(rig, m, scale, dt);
} else if (m.kind === 'rotate' || m.kind === 'rotate_globe') {
const degS = TILT_DEG_S[m.speed];
const stepRad =
m.mode === 'once'
? geo.math.toRadians(ONCE.rotateDeg) * (scale - (m.lastScale || 0))
: geo.math.toRadians(degS) * dt;
m.lastScale = scale;
if (m.kind === 'rotate_globe') {
// Tracking can acquire the camera without going through navigation.
// Yield without resetting its pose/frame: the world-space arc proof
// only describes the rotation while the frame is identity.
if (
!rig.is3D() ||
rig.tracking() ||
_isCockpitActive?.() ||
!rig.unlocked()
) {
interruptCameraMotion('globe-camera-owner-changed');
return;
}
// The camera rotates position and basis about Earth's centre. The
// captured screen-up axis keeps left/right horizontal even in a tilted
// or rolled view; a positive angle moves the globe right.
const angle = m.direction === 'left' ? -stepRad : stepRad;
if (globeRotationFitsKeyhole(rig) !== true) {
interruptCameraMotion('globe-framing-changed');
return;
}
const position = rig.position();
if (
!globeRotationHasClearance(rig, position) ||
Math.abs(geo.cartesian3.magnitude(position) - m.rotationRadius) > 0.01
) {
interruptCameraMotion('globe-surface-limit');
return;
}
rig.rotate(m.rotationAxis, angle);
} else {
lookWithinFrame(
rig,
m,
m.direction === 'left' ? 'lookLeft' : 'lookRight',
stepRad,
);
}
} else if (m.kind === 'route') {
// The dolly's shaping lives in advanceRouteFlight(); the tick only
// applies the pose and honours the same completion path as before.
const frame = advanceRouteFlight(m, dt);
// Armed and waiting for floor data — the camera stays exactly where the
// user left it rather than teleporting to an altitude derived from
// nothing. An interrupt during the arm is still instant.
if (frame.arming) return;
rig.setFrame(frame.eye, frame.direction, frame.up);
if (frame.finished) {
interruptCameraMotion('route-complete');
return;
}
}
} catch {
interruptCameraMotion('tick-error');
return;
}
// The last eased step lands first, then the motion lets go: a finished
// orbit leaves no lookAt lock behind.
if (finishing && _active === m) interruptCameraMotion('once-complete');
}
/** Heading/pitch/range that lookAt turns into the CURRENT framing exactly. */
function orbitOffset(position, heading, target) {
const range = geo.cartesian3.distance(position, target);
// Pitch from geometry so lookAt reproduces the CURRENT framing exactly.
const carto = geo.cartographic.fromCartesian(position);
const tCarto = geo.cartographic.fromCartesian(target);
const dh = carto.height - tCarto.height;
// A plain heading/pitch/range: Cesium's lookAt reads the fields, and the
// Cesium SDK is not loaded on a Navara page.
return {
heading,
pitch: -Math.asin(Math.min(1, Math.max(-1, dh / Math.max(1, range)))),
range,
};
}
/**
* One frame of tilt. With a ground pivot the camera swings about it (lookAt),
* so the place under the crosshair stays centred; without one it looks up or
* down in place. Every angle and limit is the camera's own pitch, which at
* regional range is several degrees steeper than the pivot's (the Earth
* curves away), so the swing solves for the pivot pitch that gives it. Pitch
* is clamped to [-89°, -5°] only in the direction of travel: a top-down view
* sits at -90°, below the limit, and must still be able to tilt up out of it.
* A pivot swing toward the horizon lowers the camera, so it stops at
* TILT_MIN_CLEARANCE_M and the rest tilts in place. Farther out it stops with
* the camera TILT_MIN_PIVOT_ELEVATION above the place's horizon instead, and
* keeps the place centred: tilting in place there would lift the crosshair
* onto the sky.
*/
function tickTilt(rig, m, scale, dt) {
const from = rig.pitch();
const want =
m.mode === 'once'
? m.startPitch + (m.goalPitch - m.startPitch) * scale
: from +
geo.math.toRadians(TILT_DEG_S[m.speed]) *
dt *
(m.direction === 'up' ? 1 : -1);
const up = want > from;
const limited = up
? Math.min(want, Math.max(from, PITCH_MAX))
: Math.max(want, Math.min(from, PITCH_MIN));
let atLimit = false;
if (m.hpr) {
// Apply a range a zoom set since the last frame, even when the pitch
// then has nowhere to go (a zoom in to the clearance ends the pivot).
rig.lookAt(m.target, m.hpr);
// Up toward the horizon the swing lowers the camera: hold the clearance,
// and keep the place below the horizon.
const cap = up
? Math.max(m.hpr.pitch, tiltPivotPitchMax(m.hpr.range))
: Infinity;
for (let i = 0; i < 3 && Math.abs(limited - rig.pitch()) > 1e-6; i += 1) {
const pitch = Math.min(
cap,
Math.max(-geo.math.PI_OVER_TWO, m.hpr.pitch + limited - rig.pitch()),
);
if (pitch === m.hpr.pitch) break;
m.hpr.pitch = pitch;
rig.lookAt(m.target, m.hpr);
}
// A once motion that completes with this step lets go of the lookAt
// frame after it (stepMotion), as an orbit does.
if (up && m.hpr.pitch >= cap && rig.pitch() < limited - 1e-6) {
if (tiltClearanceBinds(m.hpr.range)) {
// Down to its clearance: let go of the pivot and tilt the rest in
// place, which keeps the height.
rig.release();
m.hpr = null;
m.target = null;
} else {
// The place is at its horizon limit: stop here, still centred.
atLimit = true;
}
}
}
if (!m.hpr) tiltInPlaceWithinFrame(rig, m, limited);
if (m.mode !== 'once' && (limited !== want || atLimit))
interruptCameraMotion('tilt-clamp');
}
/** The refusal for a tilt up the camera has no room left for. */
function tiltUpLimitRefusal() {
return {
ok: false,
action: 'move_camera',
error:
'Already at the upper tilt limit (near the horizon) — tilt down, or zoom/pan instead.',
};
}
/** Shallowest pivot pitch that keeps the clearance at this range. */
function tiltPivotPitchMax(range) {
return Math.min(
-Math.asin(Math.min(1, TILT_MIN_CLEARANCE_M / range)),
-TILT_MIN_PIVOT_ELEVATION,
);
}
/**
* Whether the clearance, not the horizon, stops a swing at this range. Only
* then does the rest of the tilt happen in place: that close in (under ~17
* km) the camera's -5° limit stays well below its own horizon.
*/
function tiltClearanceBinds(range) {
return TILT_MIN_CLEARANCE_M / range >= Math.sin(TILT_MIN_PIVOT_ELEVATION);
}
/**
* The shallowest camera pitch a tilt starting from this frame can reach with
* the place under the crosshair still in view: PITCH_MAX, or less where a
* far pivot meets its horizon limit first.
*/
function tiltUpLimit({ rig, target, pivot }) {
if (!pivot || tiltClearanceBinds(pivot.range)) return PITCH_MAX;
return Math.min(
PITCH_MAX,
pivotCameraPitch(
rig,
target,
pivot,
Math.max(pivot.pitch, tiltPivotPitchMax(pivot.range)),
),
);
}
/** The camera pitch lookAt gives for this pivot at the given pivot pitch. */
function pivotCameraPitch(rig, target, { heading, range }, pitch) {
const ellipsoid = rig.ellipsoid();
const offset = geo.cartesian3.create(
-range * Math.cos(pitch) * Math.sin(heading),
-range * Math.cos(pitch) * Math.cos(heading),
-range * Math.sin(pitch),
);
const eye = geo.matrix4.multiplyByPoint(
geo.transforms.eastNorthUpToFixedFrame(target, ellipsoid),
offset,
newVector(),
);
const look = geo.cartesian3.subtract(target, eye, newVector());
geo.cartesian3.normalize(look, look);
const upAtEye = ellipsoid.geodeticSurfaceNormal(eye, newVector());
return Math.asin(geo.math.clamp(geo.cartesian3.dot(look, upAtEye), -1, 1));
}
/**
* Where a tilt starts. It swings about the ground under the crosshair so the
* place stays centred. It tilts in place with no ground there, from globe
* range, or while an entity is tracked (the follow camera owns that frame;
* voice releases it before moving, so a voice tilt still pivots).
*/
function tiltStartFrame(rig) {
const target = rig.tracking() ? null : _getTarget?.(rig.owner);
let pivot = target ? tiltPivot(rig, target) : null;
if (pivot && !tiltPivotInReach(pivot.range)) pivot = null;
return { rig, target, pivot, from: rig.pitch() };
}
/** Whether a tilt may pivot at this range: up to and including the cutoff. */
function tiltPivotInReach(range) {
return range <= TILT_PIVOT_MAX_RANGE_M + TILT_PIVOT_RANGE_SLACK_M;
}
/** The reply's note for a tilt the place's horizon stops short of its angle. */
function tiltHorizonNote(pitch) {
return `Stopped at ${Math.round(geo.math.toDegrees(pitch))}°: from this range a shallower angle puts the place past the horizon. Zoom in to tilt further.`;
}
/** Ground pivot for a tilt: heading, pitch and range in the target's own frame. */
function tiltPivot(rig, target) {
const { position, heading: cameraHeading } = rig.orbitPose();
const local = geo.matrix4.multiplyByPoint(
geo.matrix4.inverseTransformation(
geo.transforms.eastNorthUpToFixedFrame(target, rig.ellipsoid()),
geo.matrix4.create(),
),
position,
newVector(),
);
const range = geo.cartesian3.magnitude(local);
if (!(range > 1) || local.z <= 0) return null;
// Near straight overhead the offset's heading is float noise (it flipped a
// north-up London view to south); keep the camera's own.
const heading =
Math.hypot(local.x, local.y) > range * 0.01
? Math.atan2(-local.x, -local.y)
: cameraHeading;
// A plain heading/pitch/range, as orbitOffset's.
return {
heading,
pitch: -Math.asin(Math.min(1, local.z / range)),
range,
};
}
/** Rigid origin-centred rotation stays outside the actual ellipsoid's bounding sphere. */
function globeRotationHasClearance(rig, position) {
const { minimumRadius, maximumRadius } = rig.ellipsoid();
const radius = geo.cartesian3.magnitude(position);
return (
Number.isFinite(minimumRadius) &&
minimumRadius > 0 &&
Number.isFinite(maximumRadius) &&
maximumRadius >= minimumRadius &&
Number.isFinite(radius) &&
radius > maximumRadius * (1 + 1e-12)
);
}
/**
* Use the existing WGS84/CSS-pixel projection; null means unsupported, not
* close-up. `view` is the rig's keyhole view of a camera; `live` says it is
* the camera on screen (a reset probe is not).
*/
function globeRotationFitsKeyhole(rig, view = rig.keyholeView(), live = true) {
if (!rig.supportedEllipsoid()) return null;
const sphereRadius = rig.ellipsoid().maximumRadius;
const { width, height } = rig.viewport();
if (
!Number.isFinite(width) ||
!Number.isFinite(height) ||
width <= 0 ||
height <= 0 ||
!view?.perspective ||
!Number.isFinite(view.near) ||
view.near <= 0 ||
!Number.isFinite(view.far) ||
view.far <= view.near ||
view.xOffset !== 0 ||
view.yOffset !== 0
)
return null;
try {
const distance = geo.cartesian3.magnitude(view.position);
if (!Number.isFinite(distance) || distance <= 0) return null;
if (distance <= sphereRadius) return false; // Near-surface polar views are close-up too.
const radiusPx = earthDiscScreenRadius(distance, height, view.fovy);
if (!radiusPx) return null;
const keyhole = getKeyholeGeometry(width, height);
// The known nadir reset probe uses the same exact cone below; projecting
// through the live projection would read the camera on screen instead.
if (live && !rig.earthDiscProjects(width, height)) {
// A near-surface horizon view cannot fit even when pointed at Earth;
// an orbital camera looking away is unsupported, not a close-up offer.
return radiusPx > Math.min(keyhole.radius, width / 2, height / 2)
? false
: null;
}
// The shared disc is an overlay approximation off-axis. Bound the sphere
// against the existing keyhole cone. Canvas-edge clipping does not change
// framing during rigid globe rotation and is not a clearance condition,
// without changing the UI projection or defining another keyhole/mask.
const toCenter = geo.cartesian3.negate(view.position, newVector());
const depth = geo.cartesian3.dot(toCenter, view.direction);
const right = Math.abs(geo.cartesian3.dot(toCenter, view.right));
const up = Math.abs(geo.cartesian3.dot(toCenter, view.up));
const focalY = height / (2 * Math.tan(view.fovy / 2));
const focalX = width / (2 * Math.tan(view.fovy / 2) * view.aspectRatio);
if (
![depth, right, up, focalX, focalY].every(Number.isFinite) ||
focalX <= 0 ||
focalY <= 0
)
return null;
const halfAngle = Math.asin(sphereRadius / distance);
const centerAngle = Math.atan2(Math.hypot(right, up), depth);
const keyholeAngle = Math.atan(keyhole.radius / Math.max(focalX, focalY));
// No overlay visibility hysteresis: a fully contained smaller globe needs no reset.
const framed = centerAngle + halfAngle <= keyholeAngle;
if (!framed) return false;
// Projection alone does not prove that a tiny globe is within depth planes.
if (depth - sphereRadius < view.near || depth + sphereRadius > view.far)
return null;
return true;
} catch {
return null;
}
}
/** Check the unchanged reset destination without moving the live camera. */
function globeResetFitsKeyhole(rig) {
try {
return globeRotationFitsKeyhole(rig, rig.resetView(), false) === true;
} catch {
return false;
}
}
/** Release only globe rotation when a new camera intent takes ownership. */
export function interruptGlobeRotation(reason = 'camera-intent') {
if (_active?.kind === 'rotate_globe') return interruptCameraMotion(reason);
return { wasActive: false, reason, leveled: false };
}
/**
* Release what the verbs hold on a departing engine: a motion running on it
* stops, and when it is the one new motions start on, its getters go too.
* @param {object} target The globe engine.
*/
export function releaseCameraVerbs(target) {
if (target == null) return;
if (_active?.rig?.owner === target) interruptCameraMotion('engine-released');
if (_rig?.owner === target) {
_rig = _getTarget = _isCockpitActive = null;
countManualInput(null);
}
}
/**
* Wire the module to the camera once (idempotent). `target` is a globe
* engine (Navara, or the Cesium engine over the app's viewer). The
* view-target getter is optional so a non-voice caller (the Directions FLY
* chip) can arm route flights before any voice session exists; a later call
* with a real getter installs it, and a call without one, FOR THE SAME
* TARGET, never clears an installed getter.
*
* A getter closes over the camera it was built for. When the target changes —
* a new application lifetime, or another engine — the previous getter is
* dropped even if this call brings none, so a callback from the old camera can
* never answer for the new one.
*/
export function initCameraVerbs(
target,
getViewTargetCartesian = null,
{ isCockpitActive } = {},
) {
const nextTarget =
typeof getViewTargetCartesian === 'function'
? getViewTargetCartesian
: null;
if (target != null && _rig?.owner === target) {
if (nextTarget) _getTarget = nextTarget;
if (typeof isCockpitActive === 'function')
_isCockpitActive = isCockpitActive;
return;
}
if (!target) return;
const previous = _rig;
const next = engineRigFor(target);
if (_active && (_active.rig === previous || previous === null)) {
// A globe motion belongs to the camera whose world pose it captured, and
// no motion crosses to another camera.
if (_active.kind === 'rotate_globe')
interruptCameraMotion('viewer-replaced');
else if (_active.rig === previous && previous !== null)
interruptCameraMotion('camera-replaced');
}
_getTarget = nextTarget;
_isCockpitActive =
typeof isCockpitActive === 'function' ? isCockpitActive : null;
_rig = next;
_lookBaseline = null;
countManualInput(target);
}
/**
* A tilt's angle: the one asked for, the default oblique view when a bare
* "tilt the camera" names neither angle nor direction, or null for a nudge.
*/
function requestedTiltPitch(args, direction) {
// Only a real number or numeric text: Number('') and Number(null) are 0,
// which would swing the camera to the horizon.
const raw = args.pitchDeg;
const requested =
typeof raw === 'number' || (typeof raw === 'string' && raw.trim() !== '')
? Number(raw)
: NaN;
// The camera never looks above the horizon, so a positive angle can only
// mean the same angle below it ("tilt 45 degrees" sent as 45).
if (Number.isFinite(requested))
return geo.math.clamp(
geo.math.toRadians(-Math.abs(requested)),
PITCH_MIN,
PITCH_MAX,
);
return direction === null ? geo.math.toRadians(TILT_DEFAULT_PITCH_DEG) : null;
}
/**
* Argument errors move_camera refuses whatever the camera is doing, so a
* caller holding a motion back behind a flight can refuse it before waiting.
* @param {Object} args
* @returns {Object|null} The refusal, or null when the arguments are usable.
*/
export function moveCameraArgsError(args = {}) {
const motion = String(args.motion || '').toLowerCase();
const direction = args.direction
? String(args.direction).toLowerCase()
: null;
if (motion === 'stop') return null;
if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion)) {
return {
ok: false,
action: 'move_camera',
error: `Unknown motion "${args.motion}" — use orbit, pan, tilt, rotate, rotate_globe, or stop.`,
};
}
if (
motion !== 'orbit' &&
motion !== 'rotate_globe' &&
(motion !== 'tilt' || requestedTiltPitch(args, direction) === null) &&
!['left', 'right', 'up', 'down'].includes(direction)
) {
return {
ok: false,
action: 'move_camera',
error: `${motion} needs a direction (${motion === 'tilt' ? 'up/down' : motion === 'rotate' ? 'left/right' : 'left/right/up/down'}).`,
};
}
if (motion === 'tilt' && (direction === 'left' || direction === 'right')) {
return {
ok: false,
action: 'move_camera',
error: 'tilt needs up or down, or pitchDeg alone for an angle.',
};
}
if (motion === 'rotate' && !['left', 'right'].includes(direction)) {
return {
ok: false,
action: 'move_camera',
error: 'rotate needs left or right.',
};
}
if (
motion === 'rotate_globe' &&
direction !== null &&
!['left', 'right'].includes(direction)
) {
return {
ok: false,
action: 'move_camera',
error: 'rotate_globe needs left or right.',
};
}
return null;
}
/**
* move_camera implementation. Returns the house result shape; rejections are
* plain-English `ok:false` errors.
* @param {Object} args
* @param {Function|null} runNavigation Validated camera-authority transaction.
*/
export function moveCamera(args = {}, runNavigation = null) {
const motion = String(args.motion || '').toLowerCase();
const direction = args.direction
? String(args.direction).toLowerCase()
: null;
const speed = ORBIT_DEG_S[String(args.speed || 'normal').toLowerCase()]
? String(args.speed || 'normal').toLowerCase()
: 'normal';
const mode =
args.mode === 'continuous' ||
(motion === 'rotate_globe' && args.mode === undefined)
? 'continuous'
: 'once';
if (motion === 'stop') {
const wasActiveBeforeHandoff = Boolean(_active);
const stop = () => {
const { wasActive } = interruptCameraMotion('voice-stop');
return {
ok: true,
action: 'move_camera',
motion: 'stop',
stopped: wasActiveBeforeHandoff || wasActive,
};
};
return typeof runNavigation === 'function' ? runNavigation(stop) : stop();
}
const argsError = moveCameraArgsError(args);
if (argsError) return argsError;
const rig = _rig;
if (!rig) {
return {
ok: false,
action: 'move_camera',
reason: 'no-camera',
error: 'Camera motion needs a globe, and none is attached.',
};
}
const tiltToPitch =
motion === 'tilt' ? requestedTiltPitch(args, direction) : null;
if (motion === 'tilt' && tiltToPitch !== null) {
// Angles and limits are the camera's own pitch, whatever the swing pivots
// about; releasing the follow camera does not change it.
const from = rig.pitch();
// -89 or -90 means top-down, which a -90° view already is: the clamp
// must not tilt it up 1°.
const atTopDown = tiltToPitch <= PITCH_MIN && from <= PITCH_MIN;
if (atTopDown || Math.abs(tiltToPitch - from) < geo.math.toRadians(0.5)) {
// Still a camera request: it stops a running motion and releases the
// follow camera, as a tilt that moves would.
const hold = () => {
interruptCameraMotion('replaced');
return {
ok: true,
action: 'move_camera',
motion,
pitchDeg: Math.round(
geo.math.toDegrees(atTopDown ? from : tiltToPitch),
),
unchanged: true,
};
};
return typeof runNavigation === 'function' ? runNavigation(hold) : hold();
}
// pitchDeg is an absolute angle, not a step: "tilt down 10 degrees" sent
// as {direction:'down', pitchDeg:10} would tilt up from -45°.
const towards = tiltToPitch > from ? 'up' : 'down';
if ((direction === 'up' || direction === 'down') && direction !== towards) {
const target = Math.round(geo.math.toDegrees(tiltToPitch));
const now = Math.round(geo.math.toDegrees(from));
return {
ok: false,
action: 'move_camera',
error: `pitchDeg is an absolute angle, not a step: ${target}° from ${now}° tilts ${towards}, not ${direction}. Send direction alone for a nudge, or pitchDeg alone for an angle.`,
};
}
if (
towards === 'up' &&
from >= tiltUpLimit(tiltStartFrame(rig)) - geo.math.toRadians(0.5)
)
return tiltUpLimitRefusal();
} else if (motion === 'tilt') {
// Honest limits: at the clamp a tilt is a no-op — say so instead of
// reporting success and letting the model gaslight itself (field test).
const pitch = rig.pitch();
if (
direction === 'up' &&
pitch >= tiltUpLimit(tiltStartFrame(rig)) - geo.math.toRadians(0.5)
) {
return tiltUpLimitRefusal();
}
if (direction === 'down' && pitch <= PITCH_MIN + geo.math.toRadians(0.5)) {
return {
ok: false,
action: 'move_camera',
error: 'Already looking straight down — tilt up to raise the horizon.',
};
}
}
// A tilt is judged by the way its pitch will move: toward its angle, or a
// nudge up or down; a rotate turns left only when told to, as it runs.
const look =
motion === 'tilt'
? tiltLook(
rig.pitch(),
tiltToPitch ??
rig.pitch() +
geo.math.toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1),
)
: motion === 'rotate'
? direction === 'left'
? 'lookLeft'
: 'lookRight'
: null;
// Honest limits from orbit too: a stopped turn rests within 0.05° of its
// limit, so one that cannot go half a degree further is refused rather than
// run and reported as done, and one that can is then turned at least that
// far. Near the limit the sampled share wobbles as the planet's edge crosses
// the grid, so a turn that would keep the planet can occasionally be refused
// too.
// A camera that is tracked or locked now is judged as the navigation that
// runs the turn will release it, so a refusal keeps the tracking.
const lookRefusal =
look &&
checkLookFromOrbit(rig, look, {
released: typeof runNavigation === 'function',
});
if (lookRefusal) return lookRefusal;
if (
(motion === 'rotate_globe' ||
(motion === 'orbit' && typeof runNavigation !== 'function')) &&
rig.tracking()
) {
// The follow camera owns a tracked view; a lookAt orbit fights it frame
// by frame and stop rips the camera out (field finding). Honest refusal
// until tracked-orbit rides the follow camera natively (roadmap).
const label = rig.trackedLabel();
return {
ok: false,
action: 'move_camera',
error: `Already following ${label} — the follow camera owns the view while tracking. Say "stop tracking" first if you want ${motion === 'rotate_globe' ? 'to rotate the globe' : 'a free orbit'}.`,
};
}
let globePose;
if (motion === 'rotate_globe') {
if (!rig.is3D()) {
return {
ok: false,
action: 'move_camera',
error: 'Globe rotation requires a 3D view.',
};
}
globePose = rig.captureGlobePose();
if (_isCockpitActive?.())
return {
ok: false,
action: 'move_camera',
reason: 'camera-owned',
error: 'Exit Cockpit before rotating the globe.',
};
const ellipsoid = rig.ellipsoid();
if (!(
Number.isFinite(ellipsoid.minimumRadius) &&
ellipsoid.minimumRadius > 0 &&
Number.isFinite(ellipsoid.maximumRadius) &&
ellipsoid.maximumRadius >= ellipsoid.minimumRadius &&
Number.isFinite(geo.cartesian3.magnitude(globePose.position))
))
return {
ok: false,
action: 'move_camera',
reason: 'unsafe-ellipsoid',
error:
'Globe rotation requires a finite supported ellipsoid and a clear globe view.',
};
const fits = globeRotationFitsKeyhole(rig);
if (fits === null)
return {
ok: false,
action: 'move_camera',
reason: 'unsupported-view',
error: 'Globe rotation requires a supported perspective view.',
};
if (!fits) {
const canReset = globeResetFitsKeyhole(rig);
return {
ok: false,
action: 'move_camera',
reason: canReset ? 'globe-view-required' : 'globe-reset-unavailable',
error: canReset
? 'Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’'
: 'Zoom out further to fit the globe inside the keyhole; the Globe View preset does not fit this viewport.',
};
}
if (!globeRotationHasClearance(rig, globePose.position))
return {
ok: false,
action: 'move_camera',
reason: 'unsafe-ellipsoid',
error: 'Globe rotation requires a clear ellipsoid bounding sphere.',
};
}
// The angle a tilt to an angle stops at short of it, and why.
let stoppedAt = null;
let stopNote = null;
const start = () => {
interruptCameraMotion('replaced');
// Checked again only if the release left the camera somewhere other than
// where the check above expected it.
if (look && !lookProven(rig.framePose(), look)) {
const refusal = checkLookFromOrbit(rig, look);
if (refusal) return refusal;
}
const state = {
kind: motion,
rig,
direction: direction || 'right',
speed,
mode,
};
if (motion === 'tilt') {
const frame = tiltStartFrame(rig);
const { target, pivot, from } = frame;
if (pivot) {
state.target = target;
state.hpr = pivot;
}
state.startPitch = from;
const upLimit = tiltUpLimit(frame);
if (tiltToPitch !== null) {
// From far out the place reaches its horizon before the camera
// reaches the asked angle: stop there, and say so.
let goal =
tiltToPitch > from
? Math.min(tiltToPitch, Math.max(from, upLimit))
: tiltToPitch;
if (goal !== tiltToPitch) stopNote = tiltHorizonNote(goal);
// From orbit an in-place tilt stops where the planet would leave the
// frame: aim it there, and say so.
if (!pivot) {
const framed = tiltPitchWithinFrame(rig, goal);
if (framed !== goal) {
goal = framed;
stopNote = tiltFrameNote(goal);
}
}
state.mode = 'once';
state.direction = goal > from ? 'up' : 'down';
state.goalPitch = goal;
// A zoom mid-tilt moves the horizon limit; it re-judges the goal
// against the angle asked for.
state.askedPitch = tiltToPitch;
state.durationS = Math.max(
ONCE.durationS,
Math.abs(geo.math.toDegrees(goal - from)) / TILT_TO_DEG_S,
);
if (goal !== tiltToPitch) stoppedAt = goal;
} else {
// A nudge stops at the limit it travels toward.
const step =
geo.math.toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1);
state.goalPitch =
step > 0
? Math.min(from + step, Math.max(from, upLimit))
: Math.max(from + step, Math.min(from, PITCH_MIN));
}
}
if (motion === 'rotate_globe') {
rig.takeGlobePose(globePose);
state.rotationAxis = globePose.up;
state.rotationRadius = geo.cartesian3.magnitude(globePose.position);
}
if (motion === 'orbit') {
// A camera flight in progress ALWAYS arms and captures at the
// destination: a target existing right now is meaningless (the globe
// is always under the crosshair). The voice runner already holds an
// orbit until its own fly-to lands; this covers any other flight.
// Without a target (mid-flight chain) the orbit arms too: the tick loop
// keeps trying for a ground target as the flight settles.
const target = rig.flightBusy() ? null : _getTarget?.(rig.owner);
if (!target) {
setActiveMotion({
kind: 'orbit',
rig,
direction: direction || 'right',
speed,
mode,
pending: true,
});
holdContinuousRender('camera-verb');
return {
ok: true,
action: 'move_camera',
motion,
direction: direction || 'right',
speed,
mode,
armed: 'waiting-for-arrival',
};
}
const { position, heading } = rig.orbitPose();
state.target = target;
state.hpr = orbitOffset(position, heading, target);
state.hprStartHeading = heading;
}
setActiveMotion(state);
// Verb motion drives the camera per frame — hold until interrupted;
// interruptCameraMotion is the single release path. (perf wave 2)
holdContinuousRender('camera-verb');
return {
ok: true,
action: 'move_camera',
motion,
direction: state.direction,
speed,
mode: state.mode,
...(tiltToPitch !== null && {
pitchDeg: Math.round(geo.math.toDegrees(stoppedAt ?? tiltToPitch)),
}),
...(stopNote !== null && { note: stopNote }),
};
};
const preserveCameraFlight =
motion === 'orbit' && rig.flightBusy() && !rig.tracking();
return typeof runNavigation === 'function'
? runNavigation(start, { preserveCameraFlight })
: start();
}
/**
* Zoom while orbiting: scale the orbit RADIUS instead of letting the zoom
* fight the per-frame lookAt (field test: "zoom out did literally nothing").
* A tilt swinging about its pivot holds a range the same way.
* @param {number} factor >1 zooms out (radius grows), <1 zooms in.
* @returns {{kind: string, changed: boolean, pitchDeg?: number,
* note?: string}|null} the motion that consumed the zoom, and whether its
* range moved; null when none did. A tilt to an angle whose end the new
* range moves also names the angle it now ends at (pitchDeg), with a note.
*/
export function adjustOrbitRange(factor) {
if (!_active || !['orbit', 'tilt'].includes(_active.kind) || !_active.hpr)
return null;
// A tilt's zoom in stops at the range that keeps its clearance. The limits
// never move a view the wrong way: a zoom in leaves a closer view in place,
// and a zoom out leaves a farther one.
const { kind, hpr } = _active;
const floor =
kind === 'tilt'
? Math.max(80, TILT_MIN_CLEARANCE_M / Math.abs(Math.sin(hpr.pitch)))
: 80;
// A tilt pivots only within TILT_PIVOT_MAX_RANGE_M; farther out the swing
// would carry the camera thousands of km.
const ceiling = kind === 'tilt' ? TILT_PIVOT_MAX_RANGE_M : 5_000_000;
const range = hpr.range;
hpr.range = Math.max(
Math.min(floor, range),
Math.min(Math.max(ceiling, range), range * factor),
);
// Under half a metre counts as not moved, as for a plain zoom.
const changed = Math.abs(hpr.range - range) >= 0.5;
return { kind, changed, ...(changed && retargetTiltAfterZoom(_active)) };
}
/**
* A zoom changed the range a tilt to an angle holds, and with it the place's
* horizon limit: aim the tilt at the angle asked for or the new limit,
* whichever comes first, from where the camera is now. The pivot pitch is
* re-solved so the new range keeps the camera's pitch, and a limit the camera
* is already past is eased down to rather than jumped to. Returns the end
* angle and a note for the reply when that end moved, otherwise nothing.
*/
function retargetTiltAfterZoom(m) {
if (m.kind !== 'tilt' || m.mode !== 'once' || m.askedPitch === undefined)
return {};
let from = m.rig.pitch();
if (!(m.askedPitch > from)) return {};
if (m.hpr) {
// At the same pivot pitch a longer range looks down more steeply (the
// Earth curves away): find the pivot pitch that holds this camera pitch.
// It stays below the place's horizon limit (or where the pivot already
// was): past it the place drops behind the Earth, so a camera the zoom
// leaves past that limit steps down to it with the zoom.
const cap = Math.max(m.hpr.pitch, tiltPivotPitchMax(m.hpr.range));
for (let i = 0; i < 4; i += 1) {
const error =
from - pivotCameraPitch(m.rig, m.target, m.hpr, m.hpr.pitch);
if (Math.abs(error) < 1e-7) break;
const pitch = geo.math.clamp(
m.hpr.pitch + error,
-geo.math.PI_OVER_TWO,
cap,
);
if (pitch === m.hpr.pitch) break;
m.hpr.pitch = pitch;
}
from = Math.min(
from,
pivotCameraPitch(m.rig, m.target, m.hpr, m.hpr.pitch),
);
}
const limit =
m.hpr && !tiltClearanceBinds(m.hpr.range)
? Math.min(
PITCH_MAX,
pivotCameraPitch(
m.rig,
m.target,
m.hpr,
tiltPivotPitchMax(m.hpr.range),
),
)
: PITCH_MAX;
const goal = Math.min(m.askedPitch, limit);
if (Math.abs(goal - m.goalPitch) < 1e-6) return {};
m.goalPitch = goal;
m.startPitch = from;
m.elapsed = 0;
m.durationS = Math.max(
ONCE.durationS,
Math.abs(geo.math.toDegrees(goal - from)) / TILT_TO_DEG_S,
);
const limited = goal !== m.askedPitch;
return {
pitchDeg: Math.round(geo.math.toDegrees(goal)),
note: limited
? tiltHorizonNote(goal)
: `The tilt now reaches ${Math.round(geo.math.toDegrees(goal))}°.`,
};
}
/**
* fly_route implementation: dolly along an existing route annotation.
* @param {Array} annoList — engine list() output (raw annos incl. `path`)
* @param {Object} args
* @param {Function|null} floorFn (latDeg, lonDeg) => cached floor metres.
* @param {Function|null} runNavigation Validated camera-authority transaction.
* @param {Function|null} warmFn (cells) => void — batch-warms the floor cells
* along the route corridor. Without it a cold cache has no protection: route
* vertices carry height 0, so an unwarmed mountain corridor reads as sea level.
* @param {object|null} engine The globe engine to fly on (its contract
* camera); by default the camera initCameraVerbs installed.
*/
export function flyRoute(
annoList,
args = {},
floorFn = null,
runNavigation = null,
warmFn = null,
engine = null,
) {
const speed = ROUTE_M_S[String(args.speed || 'normal').toLowerCase()]
? String(args.speed || 'normal').toLowerCase()
: 'normal';
// A route hidden from Draw's list is not on screen, so it is not flown.
const routes = (annoList || []).filter(
(a) =>
a.type === 'route' &&
!a.hidden &&
Array.isArray(a.path) &&
a.path.length >= 2,
);
if (!routes.length) {
return {
ok: false,
action: 'fly_route',
error:
'No route is drawn — draw a route first (e.g. "route from A to B"), then fly it.',
};
}
let route = routes[routes.length - 1];
if (args.label) {
const wanted = String(args.label).toLowerCase();
const byLabel = routes.filter((a) =>
String(a.label || '')
.toLowerCase()
.includes(wanted),
);
if (!byLabel.length) {
return {
ok: false,
action: 'fly_route',
error: `No route matches "${args.label}" — say fly the route without a name for the newest one.`,
};
}
route = byLabel[byLabel.length - 1];
}
if (
route.path.some(
(point) =>
!Number.isFinite(point?.lat) ||
point.lat < -90 ||
point.lat > 90 ||
!Number.isFinite(point?.lon) ||
point.lon < -180 ||
point.lon > 180 ||
(point.height !== undefined && !Number.isFinite(point.height)),
)
) {
return {
ok: false,
action: 'fly_route',
error: 'The selected route has an invalid waypoint.',
};
}
const pts = route.path.map((p) =>
geo.cartesian3.fromDegrees(p.lon, p.lat, p.height || 0),
);
const cumM = [0];
for (let i = 1; i < pts.length; i += 1) {
cumM.push(cumM[i - 1] + geo.cartesian3.distance(pts[i - 1], pts[i]));
}
if (!Number.isFinite(cumM.at(-1)) || cumM.at(-1) <= 0) {
return {
ok: false,
action: 'fly_route',
error: 'The selected route has no flyable distance.',
};
}
const rig = engine ? engineRigFor(engine) : _rig;
if (!rig) {
return {
ok: false,
action: 'fly_route',
reason: 'no-camera',
error: 'Route flying needs a globe, and none is attached.',
};
}
const start = () => {
interruptCameraMotion('replaced');
let flight = null;
flight = createRouteFlight({
pts,
cumM,
speed,
floorFn,
warmFn,
// The camera the flight runs on NOW (a parked flight may resume on
// another engine before its one probe fires).
probeFn: (cells) =>
probeMeshFloorM((flight?.rig ?? rig).surface(), cells),
cameraHeightM: rig.heightM(),
reducedMotion: prefersReducedMotion(),
});
flight.rig = rig;
setActiveMotion(flight);
holdContinuousRender('camera-verb');
return {
ok: true,
action: 'fly_route',
label: route.label || null,
speed,
distanceM: Math.round(flight.totalM),
durationS: Math.round(flight.durationS),
waypoints: pts.length,
// The caller keeps this so it can stop ITS flight later without stopping
// whatever has replaced it (see interruptCameraMotionIfActive).
motionId: flight.motionId,
};
};
return typeof runNavigation === 'function' ? runNavigation(start) : start();
}