A spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe.
JavaScript 3d-globecesiumflight-trackinggeospatialgeospatial-intelligencegisosintphotogrammetrysatellite-trackingspatial-intelligencewebglworldview
/**
* 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 Cesium from 'cesium';
import { GLOBE_VIEW } from './locations.js';
import {
projectEarthDiscToViewport,
earthDiscScreenRadius,
getKeyholeGeometry,
} from './celestialRing.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 = Cesium.Math.toRadians(-89);
const PITCH_MAX = Cesium.Math.toRadians(-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 = new Cesium.Cartesian3();
const _arcB = new Cesium.Cartesian3();
const _chordVertical = new Cesium.Cartesian3();
const _turnCross = new Cesium.Cartesian3();
const _framePos = new Cesium.Cartesian3();
const _frameAheadPos = new Cesium.Cartesian3();
const _frameUp = new Cesium.Cartesian3();
const _frameIn = new Cesium.Cartesian3();
const _frameOut = new Cesium.Cartesian3();
const _frameGaze = new Cesium.Cartesian3();
const _frameRight = new Cesium.Cartesian3();
const _frameLevelUp = new Cesium.Cartesian3();
const _frameDir = new Cesium.Cartesian3();
const _frameEye = new Cesium.Cartesian3();
const _frameBankedUp = new Cesium.Cartesian3();
const _frameCarto = new Cesium.Cartographic();
const _frameAheadCarto = new Cesium.Cartographic();
const _bankQuat = new Cesium.Quaternion();
const _bankMatrix = new Cesium.Matrix3();
const _headingQuat = new Cesium.Quaternion();
const _headingMatrix = new Cesium.Matrix3();
const _warmPos = new Cesium.Cartesian3();
const _warmCarto = new Cesium.Cartographic();
const _probeCarto = new Cesium.Cartographic();
/** 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 Cesium.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);
Cesium.Cartesian3.subtract(b, a, result);
const vertical = Cesium.Cartesian3.multiplyByScalar(
up,
Cesium.Cartesian3.dot(result, up),
_chordVertical,
);
Cesium.Cartesian3.subtract(result, vertical, result);
const len = Cesium.Cartesian3.magnitude(result);
if (!(len > 1e-3)) return null;
return Cesium.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 = Cesium.Cartesian3.cross(a, b, _turnCross);
const sinLeft = Cesium.Cartesian3.dot(cross, up);
const cosTurn = Cesium.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 = Cesium.Cartographic.fromCartesian(
point,
Cesium.Ellipsoid.WGS84,
_warmCarto,
);
const lat = Number(Cesium.Math.toDegrees(carto.latitude).toFixed(3));
const lon = Number(Cesium.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 = Cesium.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 = Cesium.Cartographic.fromCartesian(
pts[0],
Cesium.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 = Cesium.Cartographic.fromCartesian(
pos,
Cesium.Ellipsoid.WGS84,
_frameCarto,
);
const up = Cesium.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
? Cesium.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 = Cesium.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 = Cesium.Matrix3.fromQuaternion(
Cesium.Quaternion.fromAxisAngle(up, -turnToGaze * k, _headingQuat),
_headingMatrix,
);
const turned = Cesium.Matrix3.multiplyByVector(
rotation,
state.headingDir,
_frameDir,
);
const vertical = Cesium.Cartesian3.multiplyByScalar(
up,
Cesium.Cartesian3.dot(turned, up),
_chordVertical,
);
Cesium.Cartesian3.subtract(turned, vertical, turned);
if (Cesium.Cartesian3.magnitude(turned) > 1e-6) {
Cesium.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 = Cesium.Cartesian3.fromElements(-pos.y, pos.x, 0, _frameGaze);
state.headingDir =
Cesium.Cartesian3.magnitude(east) > 1e-6
? Cesium.Cartesian3.normalize(east, new Cesium.Cartesian3())
: Cesium.Cartesian3.fromElements(1, 0, 0, new Cesium.Cartesian3());
}
const heading = state.headingDir;
// Locked pitch: heading gives the azimuth, the pitch never wanders.
const pitch = Cesium.Math.toRadians(ROUTE_PITCH_DEG);
const direction = Cesium.Cartesian3.normalize(
Cesium.Cartesian3.add(
Cesium.Cartesian3.multiplyByScalar(heading, Math.cos(pitch), _frameDir),
Cesium.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 = Cesium.Cartesian3.normalize(
Cesium.Cartesian3.cross(direction, up, _frameRight),
_frameRight,
);
const levelUp = Cesium.Cartesian3.normalize(
Cesium.Cartesian3.cross(right, direction, _frameLevelUp),
_frameLevelUp,
);
const bankRad = Cesium.Math.toRadians(appliedBankDeg);
let bankedUp = levelUp;
if (Math.abs(bankRad) > 1e-6) {
const quat = Cesium.Quaternion.fromAxisAngle(direction, bankRad, _bankQuat);
const rotation = Cesium.Matrix3.fromQuaternion(quat, _bankMatrix);
bankedUp = Cesium.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 = Cesium.Cartographic.fromCartesian(
aheadPos,
Cesium.Ellipsoid.WGS84,
_frameAheadCarto,
);
try {
const here = state.floorFn(
Cesium.Math.toDegrees(carto.latitude),
Cesium.Math.toDegrees(carto.longitude),
);
const ahead = state.floorFn(
Cesium.Math.toDegrees(aheadCarto.latitude),
Cesium.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 = Cesium.Cartesian3.fromRadians(
carto.longitude,
carto.latitude,
heightM,
Cesium.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,
};
}
let _viewer = null;
let _getTarget = null;
let _active = null; // { kind, motion, direction, speed, mode, motionId, ...state }
let _tickRemover = null;
let _trackingRemover = null;
let _inputRemovers = [];
/** Monotonic id for the motion currently running; 0 means "no motion". */
let _motionSeq = 0;
/**
* 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.
* @param {object|null} state Motion state, or null to clear.
* @returns {object|null} The installed state.
*/
function setActiveMotion(state) {
if (state) {
_motionSeq += 1;
state.motionId = _motionSeq;
}
_active = state;
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);
}
function clearLookAt() {
try {
_viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
} catch {
/* teardown race */
}
}
/**
* Put the horizon back.
*
* The route dolly is the only motion that rolls the camera, and Cesium keeps
* whatever world-space up vector it was last handed — so releasing a flight
* mid-bank leaves the user holding a tilted horizon until some later motion
* happens to level it. Heading, pitch and position are preserved; only the
* roll is taken out.
* @returns {boolean} Whether a roll was actually removed.
*/
function levelCameraRoll() {
try {
const cam = _viewer?.camera;
if (!cam || typeof cam.setView !== 'function') return false;
const roll = Cesium.Math.negativePiToPi(cam.roll || 0);
if (Math.abs(roll) < 1e-5) return false;
cam.setView({
orientation: { heading: cam.heading, pitch: cam.pitch, roll: 0 },
});
return true;
} catch {
return false; // teardown race
}
}
/** Stop any active motion. Returns whether one was running. */
export function interruptCameraMotion(reason = 'interrupt') {
const wasActive = Boolean(_active);
// 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.
const tracking = Boolean(_viewer?.trackedEntity);
const wasRoute = wasActive && _active.kind === 'route';
if (
wasActive &&
!tracking &&
(_active.kind === 'orbit' || _active.kind === 'route')
)
clearLookAt();
// 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.
const leveled = wasRoute && !tracking ? levelCameraRoll() : false;
_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,
};
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;
}
function onTick() {
if (!_active || !_viewer) 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 - (_active.lastMs ?? nowMs)) / 1000),
);
_active.lastMs = nowMs;
const cam = _viewer.camera;
const m = _active;
// `once` motions ease out and self-stop on budget exhaustion.
let scale = 1;
if (m.mode === 'once') {
m.elapsed = (m.elapsed || 0) + dt;
const t = Math.min(1, m.elapsed / ONCE.durationS);
scale = 1 - (1 - t) * (1 - t); // ease-out progress share
if (t >= 1) {
interruptCameraMotion('once-complete');
}
}
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 (_viewer.scene.tweens.length > 0) {
m.settledS = 0;
return;
}
m.settledS = (m.settledS || 0) + dt;
if (m.settledS < 0.8) return;
const target = _getTarget?.(_viewer);
if (!target) return;
const cam2 = _viewer.camera;
const range = Cesium.Cartesian3.distance(cam2.positionWC, target);
const carto2 = Cesium.Cartographic.fromCartesian(cam2.positionWC);
const tCarto2 = Cesium.Cartographic.fromCartesian(target);
const dh2 = carto2.height - tCarto2.height;
m.target = target;
m.hpr = new Cesium.HeadingPitchRange(
cam2.heading,
-Math.asin(Math.min(1, Math.max(-1, dh2 / Math.max(1, range)))),
range,
);
m.hprStartHeading = cam2.heading;
m.pending = false;
m.elapsed = 0; // once-mode budget starts when the orbit actually begins
return;
}
if (m.kind === 'orbit') {
const rate =
Cesium.Math.toRadians(ORBIT_DEG_S[m.speed]) *
(m.direction === 'left' ? -1 : 1);
if (m.mode === 'once') {
const total =
Cesium.Math.toRadians(ONCE.orbitDeg) *
(m.direction === 'left' ? -1 : 1);
m.hpr.heading = m.hprStartHeading + total * scale;
} else {
m.hpr.heading += rate * dt;
}
cam.lookAt(m.target, m.hpr);
} else if (m.kind === 'pan') {
const heightM = Math.max(50, cam.positionCartographic.height);
const step =
m.mode === 'once'
? heightM * ONCE.panViewFraction * (scale - (m.lastScale || 0))
: heightM * PAN_VIEW_FRACTION_S[m.speed] * dt;
m.lastScale = scale;
if (m.direction === 'left') cam.moveLeft(step);
else if (m.direction === 'right') cam.moveRight(step);
else if (m.direction === 'up') cam.moveUp(step);
else cam.moveDown(step);
} else if (
m.kind === 'tilt' ||
m.kind === 'rotate' ||
m.kind === 'rotate_globe'
) {
const degS = TILT_DEG_S[m.speed];
const stepRad =
m.mode === 'once'
? Cesium.Math.toRadians(
m.kind === 'tilt' ? ONCE.tiltDeg : ONCE.rotateDeg,
) *
(scale - (m.lastScale || 0))
: Cesium.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 Cesium's rotation while the frame is identity.
if (
_viewer.scene.mode !== Cesium.SceneMode.SCENE3D ||
_viewer.trackedEntity ||
_isCockpitActive?.() ||
!Cesium.Matrix4.equals(cam.transform, Cesium.Matrix4.IDENTITY)
) {
interruptCameraMotion('globe-camera-owner-changed');
return;
}
// Cesium rotates both position and basis about the reference-frame
// origin. 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() !== true) {
interruptCameraMotion('globe-framing-changed');
return;
}
if (
!globeRotationHasClearance(cam.positionWC) ||
Math.abs(
Cesium.Cartesian3.magnitude(cam.positionWC) - m.rotationRadius,
) > 0.01
) {
interruptCameraMotion('globe-surface-limit');
return;
}
cam.rotate(m.rotationAxis, angle);
} else if (m.kind === 'tilt') {
const up = m.direction === 'up';
// Clamp pitch to [-89°, -5°]: never through the ground, never at the sky.
const next = cam.pitch + (up ? stepRad : -stepRad);
if (next > PITCH_MAX || next < PITCH_MIN) {
interruptCameraMotion('tilt-clamp');
return;
}
if (up) cam.lookUp(stepRad);
else cam.lookDown(stepRad);
} else if (m.direction === 'left') cam.lookLeft(stepRad);
else cam.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;
cam.setView({
destination: frame.eye,
orientation: { direction: frame.direction, up: frame.up },
});
if (frame.finished) {
interruptCameraMotion('route-complete');
return;
}
}
} catch {
interruptCameraMotion('tick-error');
}
}
/** Rigid origin-centred rotation stays outside the actual ellipsoid's bounding sphere. */
function globeRotationHasClearance(position) {
const ellipsoid = _viewer.scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84;
const { minimumRadius, maximumRadius } = ellipsoid;
const radius = Cesium.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. */
function globeRotationFitsKeyhole(camera = _viewer.camera) {
const ellipsoid = _viewer.scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84;
if (!Cesium.Cartesian3.equals(ellipsoid.radii, Cesium.Ellipsoid.WGS84.radii))
return null;
const canvas = _viewer.scene.canvas;
const width = canvas.clientWidth;
const height = canvas.clientHeight;
const frustum = camera.frustum;
if (
!Number.isFinite(width) ||
!Number.isFinite(height) ||
width <= 0 ||
height <= 0 ||
!(frustum instanceof Cesium.PerspectiveFrustum) ||
!Number.isFinite(frustum.near) ||
frustum.near <= 0 ||
!Number.isFinite(frustum.far) ||
frustum.far <= frustum.near ||
frustum.xOffset !== 0 ||
frustum.yOffset !== 0
)
return null;
try {
const cam = camera;
const distance = Cesium.Cartesian3.magnitude(cam.positionWC);
const sphereRadius = ellipsoid.maximumRadius;
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, frustum.fovy);
if (!radiusPx) return null;
const keyhole = getKeyholeGeometry(width, height);
// The known nadir reset probe uses the same exact cone below; projecting
// through SceneTransforms would read the live scene.camera instead.
if (
camera === _viewer.camera &&
!projectEarthDiscToViewport(_viewer, 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 = Cesium.Cartesian3.negate(
cam.positionWC,
new Cesium.Cartesian3(),
);
const depth = Cesium.Cartesian3.dot(toCenter, cam.directionWC);
const right = Math.abs(Cesium.Cartesian3.dot(toCenter, cam.rightWC));
const up = Math.abs(Cesium.Cartesian3.dot(toCenter, cam.upWC));
const focalY = height / (2 * Math.tan(frustum.fovy / 2));
const focalX =
width / (2 * Math.tan(frustum.fovy / 2) * frustum.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 < frustum.near ||
depth + sphereRadius > frustum.far
)
return null;
return true;
} catch {
return null;
}
}
/** Check the unchanged reset destination without moving the live camera. */
function globeResetFitsKeyhole() {
try {
const camera = Cesium.Camera.clone(_viewer.camera);
const { longitude, latitude } = _viewer.camera.positionCartographic;
camera.setView({
destination: Cesium.Cartesian3.fromRadians(
longitude,
latitude,
GLOBE_VIEW.heightM,
),
orientation: {
heading: 0,
pitch: Cesium.Math.toRadians(GLOBE_VIEW.pitchDeg),
roll: 0,
},
endTransform: Cesium.Matrix4.IDENTITY,
});
return globeRotationFitsKeyhole(camera) === 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 };
}
/**
* Wire the module to the viewer once (idempotent). 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 VIEWER, never clears an
* installed getter.
*
* A getter closes over the viewer it was built for. When the viewer changes —
* a new application lifetime — the previous getter is dropped even if this
* call brings none, so a callback from the old viewer can never answer for the
* new one.
*/
export function initCameraVerbs(
viewer,
getViewTargetCartesian = null,
{ isCockpitActive } = {},
) {
const nextTarget =
typeof getViewTargetCartesian === 'function'
? getViewTargetCartesian
: null;
if (_viewer === viewer) {
if (nextTarget) _getTarget = nextTarget;
if (typeof isCockpitActive === 'function')
_isCockpitActive = isCockpitActive;
return;
}
// A globe motion belongs to the viewer whose world pose it captured.
if (_active?.kind === 'rotate_globe')
interruptCameraMotion('viewer-replaced');
_getTarget = nextTarget;
_isCockpitActive =
typeof isCockpitActive === 'function' ? isCockpitActive : null;
_viewer = viewer;
if (_tickRemover) _tickRemover();
_tickRemover = viewer.clock.onTick.addEventListener(onTick);
if (_trackingRemover) _trackingRemover();
// Cockpit can acquire then clear tracking before the next clock tick.
// Yield on acquisition itself without changing legacy camera motions.
_trackingRemover = viewer.trackedEntityChanged?.addEventListener((entity) => {
if (entity && _active?.kind === 'rotate_globe')
interruptCameraMotion('globe-camera-owner-changed');
});
for (const rm of _inputRemovers) rm();
_inputRemovers = [];
const canvas = viewer.scene.canvas;
// ANY manual camera input reclaims control — the cancelFlight reflex.
for (const evt of ['pointerdown', 'touchstart', 'wheel']) {
const h = () => interruptCameraMotion('manual-input');
canvas.addEventListener(evt, h, { passive: true });
_inputRemovers.push(() => canvas.removeEventListener(evt, h));
}
}
/**
* 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();
}
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' &&
!['left', 'right', 'up', 'down'].includes(direction)
) {
return {
ok: false,
action: 'move_camera',
error: `${motion} needs a direction (left/right${motion !== 'rotate' ? '/up/down' : ''}).`,
};
}
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.',
};
}
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 = _viewer.camera.pitch;
if (direction === 'up' && pitch >= PITCH_MAX - Cesium.Math.toRadians(0.5)) {
return {
ok: false,
action: 'move_camera',
error:
'Already at the upper tilt limit (near the horizon) — tilt down, or zoom/pan instead.',
};
}
if (
direction === 'down' &&
pitch <= PITCH_MIN + Cesium.Math.toRadians(0.5)
) {
return {
ok: false,
action: 'move_camera',
error: 'Already looking straight down — tilt up to raise the horizon.',
};
}
}
if (
(motion === 'rotate_globe' ||
(motion === 'orbit' && typeof runNavigation !== 'function')) &&
_viewer?.trackedEntity
) {
// 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 =
_viewer.trackedEntity?.name ||
_viewer.trackedEntity?.id ||
'the tracked target';
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 (_viewer.scene.mode !== Cesium.SceneMode.SCENE3D) {
return {
ok: false,
action: 'move_camera',
error: 'Globe rotation requires a 3D view.',
};
}
const cam = _viewer.camera;
globePose = {
position: Cesium.Cartesian3.clone(cam.positionWC),
direction: Cesium.Cartesian3.clone(cam.directionWC),
up: Cesium.Cartesian3.normalize(cam.upWC, new Cesium.Cartesian3()),
right: Cesium.Cartesian3.clone(cam.rightWC),
};
if (_isCockpitActive?.())
return {
ok: false,
action: 'move_camera',
reason: 'camera-owned',
error: 'Exit Cockpit before rotating the globe.',
};
const ellipsoid = _viewer.scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84;
if (!(
Number.isFinite(ellipsoid.minimumRadius) &&
ellipsoid.minimumRadius > 0 &&
Number.isFinite(ellipsoid.maximumRadius) &&
ellipsoid.maximumRadius >= ellipsoid.minimumRadius &&
Number.isFinite(Cesium.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();
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();
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(globePose.position))
return {
ok: false,
action: 'move_camera',
reason: 'unsafe-ellipsoid',
error: 'Globe rotation requires a clear ellipsoid bounding sphere.',
};
}
const start = () => {
interruptCameraMotion('replaced');
const state = {
kind: motion,
direction: direction || 'right',
speed,
mode,
};
if (motion === 'rotate_globe') {
// Convert an inherited ground-target frame without changing the world
// pose. Rotation must pivot about Earth, never the previous local target.
const cam = _viewer.camera;
cam.cancelFlight();
cam.lookAtTransform(Cesium.Matrix4.IDENTITY);
// Handoff may level a route's bank. Keep the caller's exact world pose.
// Copy the basis directly: setView's heading/pitch conversion is singular
// at nadir and can change the captured orientation near the poles.
Cesium.Cartesian3.clone(globePose.position, cam.position);
Cesium.Cartesian3.clone(globePose.direction, cam.direction);
Cesium.Cartesian3.clone(globePose.up, cam.up);
Cesium.Cartesian3.clone(globePose.right, cam.right);
state.rotationAxis = globePose.up;
state.rotationRadius = Cesium.Cartesian3.magnitude(globePose.position);
}
if (motion === 'orbit') {
if (_viewer.scene.tweens.length > 0) {
// A camera flight is in progress ("fly to X and orbit it") — ALWAYS arm
// and capture at the destination; a target existing right now is
// meaningless (the globe is always under the crosshair).
setActiveMotion({
kind: 'orbit',
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 target = _getTarget?.(_viewer);
if (!target) {
// Mid-flight chain ("fly to X and orbit it"): ARM the orbit — the tick
// loop keeps trying for a ground target as the flight settles.
setActiveMotion({
kind: 'orbit',
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 cam = _viewer.camera;
const range = Cesium.Cartesian3.distance(cam.positionWC, target);
// Pitch from geometry so lookAt reproduces the CURRENT framing exactly.
const carto = Cesium.Cartographic.fromCartesian(cam.positionWC);
const tCarto = Cesium.Cartographic.fromCartesian(target);
const dh = carto.height - tCarto.height;
const pitch = -Math.asin(
Math.min(1, Math.max(-1, dh / Math.max(1, range))),
);
state.target = target;
state.hpr = new Cesium.HeadingPitchRange(cam.heading, pitch, range);
state.hprStartHeading = cam.heading;
}
setActiveMotion(state);
// Verb motion drives the camera per clock tick — 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,
};
};
const preserveCameraFlight =
motion === 'orbit' &&
_viewer.scene.tweens.length > 0 &&
!_viewer.trackedEntity;
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").
* @param {number} factor >1 zooms out (radius grows), <1 zooms in.
* @returns {boolean} true when an orbit consumed the zoom.
*/
export function adjustOrbitRange(factor) {
if (!_active || _active.kind !== 'orbit' || !_active.hpr) return false;
_active.hpr.range = Math.max(
80,
Math.min(5_000_000, _active.hpr.range * factor),
);
return true;
}
/**
* 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.
*/
export function flyRoute(
annoList,
args = {},
floorFn = null,
runNavigation = null,
warmFn = null,
) {
const speed = ROUTE_M_S[String(args.speed || 'normal').toLowerCase()]
? String(args.speed || 'normal').toLowerCase()
: 'normal';
const routes = (annoList || []).filter(
(a) => a.type === 'route' && 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) =>
Cesium.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] + Cesium.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 start = () => {
interruptCameraMotion('replaced');
setActiveMotion(
createRouteFlight({
pts,
cumM,
speed,
floorFn,
warmFn,
probeFn: (cells) => probeMeshFloorM(_viewer?.scene, cells),
cameraHeightM: _viewer?.camera?.positionCartographic?.height,
reducedMotion: prefersReducedMotion(),
}),
);
holdContinuousRender('camera-verb');
return {
ok: true,
action: 'fly_route',
label: route.label || null,
speed,
distanceM: Math.round(_active.totalM),
durationS: Math.round(_active.durationS),
waypoints: pts.length,
// The caller keeps this so it can stop ITS flight later without stopping
// whatever has replaced it (see interruptCameraMotionIfActive).
motionId: _active.motionId,
};
};
return typeof runNavigation === 'function' ? runNavigation(start) : start();
}