Files
gods-eye-view/src/cameraVerbs.js
T
Sameh Khamis c8346c9fda Keep shape radii, rim gradients, depth-fail looks, sweep cadence and step camera moves out of the renderer contract
Shapes take their radii in metres; the world annotation ring follows the
camera height itself (ringRadiusAt), resizing on preRender. The radial rim
preset and depthBias go: the launch pad zone draws a canvas image fill made
by the layer. Solid and dashed lines take one depthFail look (solid or
dash) in place of depthFailColor and depthFailDash. sonarCadenceHz goes from
the quality settings: nothing set it, and the sweep moves every 80 ms.

Camera move, look, rotateAround and zoom leave the camera port: the app's pans,
in-place turns, globe turns and zooms are setView views summed over the pose
(geo/eyeMoves), and the Cesium port places a view by direction and up
exactly rather than through heading, pitch and roll. The conformance driver
runs those script steps through setView; the lookAt script turns in place
where it turned about the frame-local axis, and its reference is recorded
again.
2026-11-10 04:08:41 -08:00

2435 lines
92 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 { followedOf, isFollowing, onFollowChanged } from './data/followed.js';
import { GLOBE_VIEW } from './locations.js';
import {
globeFrameShare,
isFreeGlobeCamera,
lookAngleWithinFrame,
lookStepLosesGlobe,
lookedPose,
} from './globeInView.js';
import {
projectEarthDiscToViewport,
earthDiscScreenRadius,
getKeyholeGeometry,
KEYHOLE_OUTER_RADIUS,
} from './celestialRing.js';
import { isScopeMaskEnabled } from './scopeMask.js';
import {
holdContinuousRender,
releaseContinuousRender,
} from './renderGovernor.js';
import {
PI_OVER_TWO,
WGS84,
add,
clamp,
cross,
distance,
dot,
eastNorthUp,
framePoint,
fromAxisAngle,
fromDegrees,
fromRadians,
frameVector,
geodeticSurfaceNormal,
headingPitchRollFrame,
inverseFramePoint,
lerpInto,
magnitude,
negativePiToPi,
normalize,
scale,
sub,
toAxes,
toCartographicRadians,
toDegrees,
toRadians,
vec,
} from './geo/index.js';
import { eyeMoved, eyeRotatedAbout, eyeTurned } from './geo/eyeMoves.js';
import { heightsOf } from './queries/heights.js';
import {
cameraOf,
findCamera,
findFrame,
rendererOf,
} from './render/rendererOf.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 = toRadians(-89);
const PITCH_MAX = 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 = 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 ────────────────────────────────────────────────── */
/** Scratch points for the per-frame arc reads. */
const _arcA = vec();
const _arcB = vec();
const _framePos = vec();
const _frameAheadPos = vec();
const _warmPos = vec();
/** `v` turned by `angle` radians about `axis`: quaternion, then its axes. */
const rotateAbout = (v, axis, angle) =>
frameVector(toAxes(fromAxisAngle(axis, angle)), v);
/** `v` less its part along unit `up`. */
function horizontalPart(v, up) {
const along = dot(v, up);
return vec(v.x - up.x * along, v.y - up.y * along, v.z - up.z * along);
}
/** The ellipsoid's unit normal at geodetic `lon`, `lat` (radians). */
function surfaceNormal(lon, lat) {
const cosLat = Math.cos(lat);
return normalize(
vec(cosLat * Math.cos(lon), cosLat * Math.sin(lon), Math.sin(lat)),
);
}
/** 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 lerpInto(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) {
const a = arcPoint(state, sA, _arcA);
const b = arcPoint(state, sB, _arcB);
const horizontal = horizontalPart(vec(b.x - a.x, b.y - a.y, b.z - a.z), up);
const len = magnitude(horizontal);
if (!(len > 1e-3)) return null;
return vec(horizontal.x / len, horizontal.y / len, horizontal.z / len);
}
/**
* 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 {{x: number, y: number, z: number}} a Unit horizontal direction turned FROM.
* @param {{x: number, y: number, z: number}} b Unit horizontal direction turned TO.
* @param {{x: number, y: number, z: number}} up Local up, the axis the turn is measured about.
* @returns {number} Radians, + = right.
*/
export function signedTurnRad(a, b, up) {
const sinLeft = dot(cross(a, b), up);
const cosTurn = 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 carto = toCartographicRadians(arcPoint(state, s, _warmPos));
const lat = Number(toDegrees(carto.lat).toFixed(3));
const lon = Number(toDegrees(carto.lon).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 {object|undefined} viewer The live scene object, asked through its
* renderer's heights (`heightsOf`).
* @param {Array<{lat: number, lon: number}>} cells Cells to probe.
* @returns {{heightM: number, sampled: number, requested: number}} The reading.
*/
export function probeMeshFloorM(viewer, cells) {
const requested = Array.isArray(cells) ? cells.length : 0;
const empty = { heightM: Number.NaN, sampled: 0, requested };
if (!viewer || !requested) return empty;
const heights = heightsOf(viewer);
let heightM = Number.NaN;
let sampled = 0;
for (const cell of cells) {
// A miss is a cell whose tiles are not ready.
const height = heights.now({ lon: cell.lon, lat: cell.lat });
if (height === null) continue;
sampled += 1;
heightM = Number.isFinite(heightM) ? Math.max(heightM, height) : height;
}
return { heightM, sampled, requested };
}
/**
* Build the state for one cinematic route flight.
* @param {Object} options
* @param {Array<{x: number, y: number, z: number}>} options.pts Route
* vertices, ECEF.
* @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 = toCartographicRadians(pts[0]).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: Object, direction: Object,
* up: Object, 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 = toCartographicRadians(pos);
const up = surfaceNormal(carto.lon, carto.lat);
// 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);
const outbound = horizontalChord(state, traveled, traveled + halfWindowM, up);
const turnRateDegS =
inbound && outbound
? 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) ||
outbound ||
inbound;
if (gaze && !state.headingDir) state.headingDir = vec(gaze.x, gaze.y, gaze.z);
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 turned = horizontalPart(
rotateAbout(state.headingDir, up, -turnToGaze * k),
up,
);
if (magnitude(turned) > 1e-6) state.headingDir = normalize(turned);
}
// 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 = vec(-pos.y, pos.x, 0);
state.headingDir = magnitude(east) > 1e-6 ? normalize(east) : vec(1, 0, 0);
}
const heading = state.headingDir;
// Locked pitch: heading gives the azimuth, the pitch never wanders.
const pitch = toRadians(ROUTE_PITCH_DEG);
const direction = normalize(
add(scale(heading, Math.cos(pitch)), scale(up, Math.sin(pitch))),
);
// 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 = normalize(cross(direction, up));
const levelUp = normalize(cross(right, direction));
const bankRad = toRadians(appliedBankDeg);
const bankedUp =
Math.abs(bankRad) > 1e-6
? rotateAbout(levelUp, direction, bankRad)
: levelUp;
// 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 aheadCarto = toCartographicRadians(
arcPoint(state, traveled + lookaheadM / 2, _frameAheadPos),
);
try {
const here = state.floorFn(toDegrees(carto.lat), toDegrees(carto.lon));
const ahead = state.floorFn(
toDegrees(aheadCarto.lat),
toDegrees(aheadCarto.lon),
);
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 = fromRadians(carto.lon, carto.lat, heightM);
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;
/** The frame port `_tickRemover` listens to. */
let _tickPort = null;
let _trackingRemover = null;
let _inputRemovers = [];
/** 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; the camera does not cancel a flight on input.
* @returns {number} Manual camera inputs so far.
*/
export function manualCameraInputCount() {
return _manualInputCount;
}
/**
* 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;
listenForFrames();
}
_active = state;
return state;
}
/**
* Run the motions on the frames of the viewer's frame port, the one there
* is now: a renderer bound after `initCameraVerbs` (which replaces the
* port the viewer had) is picked up when the next motion starts.
*/
function listenForFrames() {
const port = _viewer ? findFrame(_viewer) : null;
if (port === _tickPort) return;
_tickRemover?.();
_tickPort = port;
_tickRemover = port?.on('preUpdate', onTick) ?? null;
}
/**
* @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 = toRadians(0.5);
let _provenLook = null;
/** 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 two vectors agree to `tolerance` in every component. */
const within = (a, b, tolerance) =>
Math.abs(a.x - b.x) <= tolerance &&
Math.abs(a.y - b.y) <= tolerance &&
Math.abs(a.z - b.z) <= tolerance;
/** The frame share an in-place turn from `pose` is limited against. */
function lookBaselineShare(pose) {
const share = globeFrameShare(pose, visibleFrame());
const continues =
_lookBaseline &&
within(_lookBaseline.position, pose.position, 1) &&
within(_lookBaseline.direction, pose.direction, 1e-9);
_lookBaseline = {
position: pose.position,
direction: pose.direction,
share: continues ? Math.max(_lookBaseline.share, share) : share,
};
return _lookBaseline.share;
}
/**
* One in-place look step of motion `m` (`look`: 'up', 'down', 'left' or
* 'right'). 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(camera, m, look, angle) {
let allowed = angle;
if (isFreeGlobeCamera(_viewer)) {
const pose = camera.pose();
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) camera.setView(eyeTurned(camera.pose(), look, allowed));
// The pose this turn leaves, for a turn that continues from it.
if (_lookBaseline) _lookBaseline.direction = camera.pose().direction;
if (allowed < angle) interruptCameraMotion('globe-out-of-frame');
}
/**
* The in-place look a pitch change from `fromPitch` to `goalPitch` makes:
* 'up', 'down', 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 'up';
return goalPitch < fromPitch ? 'down' : null;
}
/** Tilt `m` in place to `goalPitch`, as far as the frame limit allows. */
function tiltInPlaceWithinFrame(camera, m, goalPitch) {
const pitch = camera.pose().pitch;
const look = tiltLook(pitch, goalPitch);
if (look) lookWithinFrame(camera, m, look, Math.abs(goalPitch - pitch));
}
/**
* The pitch an in-place tilt from the camera'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(camera, goalPitch) {
const pose = camera.pose();
const look = tiltLook(pose.pitch, goalPitch);
if (!look || !isFreeGlobeCamera(_viewer)) 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;
for (let i = 0; i < 32; i += 1) {
if (tiltLook(probe.pitch, goalPitch) !== look) return goalPitch;
const angle = Math.abs(goalPitch - probe.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 = lookedPose(probe, look, allowed);
if (allowed < angle) return probe.pitch;
}
return probe.pitch;
}
/** The reply's note for a tilt the frame limit stops short of its angle. */
function tiltFrameNote(pitch) {
return `Stopped at ${Math.round(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 &&
pose != null &&
within(_provenLook.position, pose.position, 1) &&
within(_provenLook.direction, pose.direction, 1e-9)
);
}
/**
* The check a voice in-place turn (`look`: 'up', 'down', 'left' or 'right')
* 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(look, { released = false } = {}) {
_provenLook = null;
if (!released && !isFreeGlobeCamera(_viewer)) return null;
const pose = findCamera(_viewer)?.pose();
if (!pose) return null;
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: pose.position,
direction: pose.direction,
};
return null;
}
function clearLookAt() {
try {
findCamera(_viewer)?.release();
} catch {
/* teardown race */
}
}
/**
* Put the horizon back.
*
* The route dolly is the only motion that rolls the camera, and the camera 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 camera = findCamera(_viewer);
if (!camera) return false;
const { heading, pitch, roll } = camera.pose();
if (Math.abs(negativePiToPi(roll || 0)) < 1e-5) return false;
camera.setView({ orientation: { heading, 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 = isFollowing(_viewer);
const wasRoute = wasActive && _active.kind === 'route';
if (
wasActive &&
!tracking &&
(_active.kind === 'orbit' ||
_active.kind === 'route' ||
(_active.kind === 'tilt' && _active.hpr))
)
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;
}
/** A pan's direction as the camera move it makes; any other is down. */
const PAN_MOVES = Object.freeze({ left: 'left', right: 'right', up: 'up' });
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 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 / (m.durationS || ONCE.durationS));
scale = 1 - (1 - t) * (1 - t); // ease-out progress share
if (t >= 1) {
interruptCameraMotion('once-complete');
}
}
try {
const camera = cameraOf(_viewer);
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. Multi-stage flights have GAPS between flights:
// require the camera out of any flight for a
// continuous 0.8 s before capturing the orbit framing at the REAL
// destination (field finding: Eiffel chain orbited from mid-flight).
if (cameraFlying()) {
m.settledS = 0;
return;
}
m.settledS = (m.settledS || 0) + dt;
if (m.settledS < 0.8) return;
const target = _getTarget?.(_viewer);
if (!target) return;
const pose = camera.pose();
m.target = target;
m.hpr = orbitFraming(pose, target);
m.hprStartHeading = pose.heading;
m.pending = false;
m.elapsed = 0; // once-mode budget starts when the orbit actually begins
return;
}
if (m.kind === 'orbit') {
const rate =
toRadians(ORBIT_DEG_S[m.speed]) * (m.direction === 'left' ? -1 : 1);
if (m.mode === 'once') {
const total =
toRadians(ONCE.orbitDeg) * (m.direction === 'left' ? -1 : 1);
m.hpr.heading = m.hprStartHeading + total * scale;
} else {
m.hpr.heading += rate * dt;
}
camera.lookAt(m.target, m.hpr);
} else if (m.kind === 'pan') {
const heightM = Math.max(50, camera.pose().height);
const step =
m.mode === 'once'
? heightM * ONCE.panViewFraction * (scale - (m.lastScale || 0))
: heightM * PAN_VIEW_FRACTION_S[m.speed] * dt;
m.lastScale = scale;
camera.setView(
eyeMoved(camera.pose(), PAN_MOVES[m.direction] ?? 'down', step),
);
} else if (m.kind === 'tilt') {
tickTilt(camera, m, scale, dt);
} else if (m.kind === 'rotate' || m.kind === 'rotate_globe') {
const degS = TILT_DEG_S[m.speed];
const stepRad =
m.mode === 'once'
? toRadians(ONCE.rotateDeg) * (scale - (m.lastScale || 0))
: 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 camera's rotation while the frame is identity.
const pose = camera.pose();
if (!isFreeGlobeCamera(_viewer) || _isCockpitActive?.()) {
interruptCameraMotion('globe-camera-owner-changed');
return;
}
// The camera 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(liveView(camera, pose)) !== true) {
interruptCameraMotion('globe-framing-changed');
return;
}
if (
!globeRotationHasClearance(pose.position) ||
Math.abs(magnitude(pose.position) - m.rotationRadius) > 0.01
) {
interruptCameraMotion('globe-surface-limit');
return;
}
camera.setView(eyeRotatedAbout(pose, m.rotationAxis, angle));
} else {
lookWithinFrame(
camera,
m,
m.direction === 'left' ? 'left' : 'right',
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;
camera.setView({
destination: frame.eye,
orientation: { direction: frame.direction, up: frame.up },
});
if (frame.finished) {
interruptCameraMotion('route-complete');
return;
}
}
} catch {
interruptCameraMotion('tick-error');
}
}
/** Whether the camera is in a flight. */
const cameraFlying = () => Boolean(findCamera(_viewer)?.flying);
/**
* An orbit offset that reproduces the current framing of `target` exactly:
* the view's heading, and pitch and range from the geometry.
*/
function orbitFraming(pose, target) {
const range = distance(pose.position, target);
const dh =
toCartographicRadians(pose.position).height -
toCartographicRadians(target).height;
return {
heading: pose.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(camera, m, scale, dt) {
const pitchNow = () => camera.pose().pitch;
const from = pitchNow();
const want =
m.mode === 'once'
? m.startPitch + (m.goalPitch - m.startPitch) * scale
: from +
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).
camera.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 - pitchNow()) > 1e-6; i += 1) {
const pitch = Math.min(
cap,
Math.max(-PI_OVER_TWO, m.hpr.pitch + limited - pitchNow()),
);
if (pitch === m.hpr.pitch) break;
m.hpr.pitch = pitch;
camera.lookAt(m.target, m.hpr);
}
// A once motion that just completed released the lookAt frame before
// this last step re-took it.
if (_active !== m) clearLookAt();
if (up && m.hpr.pitch >= cap && pitchNow() < 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.
if (_active === m) clearLookAt();
m.hpr = null;
m.target = null;
} else {
// The place is at its horizon limit: stop here, still centred.
atLimit = true;
}
}
}
if (!m.hpr) tiltInPlaceWithinFrame(camera, 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({ target, pivot }) {
if (!pivot || tiltClearanceBinds(pivot.range)) return PITCH_MAX;
return Math.min(
PITCH_MAX,
pivotCameraPitch(
target,
pivot,
Math.max(pivot.pitch, tiltPivotPitchMax(pivot.range)),
),
);
}
/** The camera pitch lookAt gives for this pivot at the given pivot pitch. */
function pivotCameraPitch(target, { heading, range }, pitch) {
const eye = framePoint(eastNorthUp(target), {
x: -range * Math.cos(pitch) * Math.sin(heading),
y: -range * Math.cos(pitch) * Math.cos(heading),
z: -range * Math.sin(pitch),
});
const look = normalize(sub(target, eye));
return Math.asin(clamp(dot(look, geodeticSurfaceNormal(eye)), -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 something is followed (the follow camera owns that frame;
* voice releases it before moving, so a voice tilt still pivots).
*/
function tiltStartFrame(camera) {
const pose = camera.pose();
const target = isFollowing(_viewer) ? null : _getTarget?.(_viewer);
let pivot = target ? tiltPivot(pose, target) : null;
if (pivot && !tiltPivotInReach(pivot.range)) pivot = null;
return { target, pivot, from: pose.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(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(pose, target) {
const local = inverseFramePoint(eastNorthUp(target), pose.position);
const range = 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)
: pose.heading;
return {
heading,
pitch: -Math.asin(Math.min(1, local.z / range)),
range,
};
}
/** Rigid origin-centred rotation stays outside the ellipsoid's bounding sphere. */
function globeRotationHasClearance(position) {
const radius = magnitude(position);
return Number.isFinite(radius) && radius > WGS84.radii.x * (1 + 1e-12);
}
/**
* The camera's view for the keyhole test: its pose, its projection, and
* whether it is the live camera (whose Earth disc the overlay projects).
*/
function liveView(camera, pose = camera.pose()) {
let projection = null;
try {
projection = camera.matrices().projection;
} catch {
/* no projection for these depth limits: unsupported below */
}
return { ...pose, projection, live: true };
}
/** The canvas the renderer draws in (the viewer's own when none is bound). */
const canvasOf = (viewer) => rendererOf(viewer)?.canvas ?? viewer.canvas;
/**
* Whether a projection is a perspective one centred on the view: what the
* keyhole cone below assumes. Column-major, so element 11 is row 3 of
* column 2 (−1 for a perspective divide), 15 row 3 of column 3 (0), and 8
* and 9 the off-centre shifts.
*/
const centredPerspective = (p) =>
p?.[11] === -1 && p[15] === 0 && p[8] === 0 && p[9] === 0;
/** Use the existing WGS84/CSS-pixel projection; null means unsupported, not close-up. */
function globeRotationFitsKeyhole(view) {
const canvas = canvasOf(_viewer);
const width = canvas.clientWidth;
const height = canvas.clientHeight;
if (
!Number.isFinite(width) ||
!Number.isFinite(height) ||
width <= 0 ||
height <= 0 ||
!centredPerspective(view.projection) ||
!Number.isFinite(view.near) ||
view.near <= 0 ||
!Number.isFinite(view.far) ||
view.far <= view.near
)
return null;
try {
const distanceM = magnitude(view.position);
const sphereRadius = WGS84.radii.x;
if (!Number.isFinite(distanceM) || distanceM <= 0) return null;
if (distanceM <= sphereRadius) return false; // Near-surface polar views are close-up too.
const radiusPx = earthDiscScreenRadius(distanceM, 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 query port would read the live camera instead.
if (view.live && !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 = vec(-view.position.x, -view.position.y, -view.position.z);
const depth = dot(toCenter, view.direction);
const right = Math.abs(dot(toCenter, view.right));
const up = Math.abs(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 / distanceM);
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: the
* view the Globe View preset sets above the current point, with the live
* camera's projection. Its axes are the camera convention's: heading,
* pitch and roll in the east-north-up frame, the view along the frame's x
* once heading is turned a quarter back.
*/
function globeResetFitsKeyhole() {
try {
const camera = cameraOf(_viewer);
const pose = camera.pose();
const here = toCartographicRadians(pose.position);
const position = fromRadians(here.lon, here.lat, GLOBE_VIEW.heightM);
const axes = headingPitchRollFrame(position, {
heading: 0 - Math.PI / 2,
pitch: toRadians(GLOBE_VIEW.pitchDeg),
roll: 0,
});
const direction = axes.x;
const up = axes.z;
return (
globeRotationFitsKeyhole({
...liveView(camera, pose),
live: false,
position,
direction,
up,
right: cross(direction, up),
}) === 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;
_lookBaseline = null;
listenForFrames();
if (_trackingRemover) _trackingRemover();
// Cockpit can acquire then clear tracking before the next clock tick.
// Yield on acquisition itself without changing legacy camera motions.
_trackingRemover = onFollowChanged(viewer, (followed) => {
if (followed && _active?.kind === 'rotate_globe')
interruptCameraMotion('globe-camera-owner-changed');
// A pivoting tilt's lookAt would fight the follow camera every frame.
else if (followed && _active?.kind === 'tilt' && _active.hpr)
interruptCameraMotion('tilt-camera-owner-changed');
});
for (const rm of _inputRemovers) rm();
_inputRemovers = [];
const canvas = canvasOf(viewer);
// ANY manual camera input reclaims control — the cancelFlight reflex.
for (const evt of ['pointerdown', 'touchstart', 'wheel']) {
const h = () => {
_manualInputCount += 1;
interruptCameraMotion('manual-input');
};
canvas.addEventListener(evt, h, { passive: true });
_inputRemovers.push(() => canvas.removeEventListener(evt, h));
}
}
/**
* 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 clamp(toRadians(-Math.abs(requested)), PITCH_MIN, PITCH_MAX);
return direction === null ? 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 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 = cameraOf(_viewer).pose().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) < 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(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(toDegrees(tiltToPitch));
const now = Math.round(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(cameraOf(_viewer))) - 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 = cameraOf(_viewer).pose().pitch;
if (
direction === 'up' &&
pitch >= tiltUpLimit(tiltStartFrame(cameraOf(_viewer))) - toRadians(0.5)
) {
return tiltUpLimitRefusal();
}
if (direction === 'down' && pitch <= PITCH_MIN + 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(
cameraOf(_viewer).pose().pitch,
tiltToPitch ??
cameraOf(_viewer).pose().pitch +
toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1),
)
: motion === 'rotate'
? direction === 'left'
? 'left'
: 'right'
: 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(look, { released: typeof runNavigation === 'function' });
if (lookRefusal) return lookRefusal;
if (
(motion === 'rotate_globe' ||
(motion === 'orbit' && typeof runNavigation !== 'function')) &&
isFollowing(_viewer)
) {
// 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 followed = followedOf(_viewer);
const label =
followed?.name || followed?.labelModel?.title || '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') {
const camera = cameraOf(_viewer);
let pose;
try {
pose = camera.pose();
} catch {
// A frustum the camera cannot describe (depth limits out of order).
return {
ok: false,
action: 'move_camera',
reason: 'unsupported-view',
error: 'Globe rotation requires a supported perspective view.',
};
}
globePose = {
position: vec(pose.position.x, pose.position.y, pose.position.z),
direction: vec(pose.direction.x, pose.direction.y, pose.direction.z),
up: normalize(pose.up),
};
if (_isCockpitActive?.())
return {
ok: false,
action: 'move_camera',
reason: 'camera-owned',
error: 'Exit Cockpit before rotating the globe.',
};
if (!Number.isFinite(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(liveView(camera, pose));
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.',
};
}
// 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(findCamera(_viewer)?.pose(), look)) {
const refusal = checkLookFromOrbit(look);
if (refusal) return refusal;
}
const state = {
kind: motion,
direction: direction || 'right',
speed,
mode,
};
if (motion === 'tilt') {
const frame = tiltStartFrame(cameraOf(_viewer));
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(cameraOf(_viewer), 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(toDegrees(goal - from)) / TILT_TO_DEG_S,
);
if (goal !== tiltToPitch) stoppedAt = goal;
} else {
// A nudge stops at the limit it travels toward.
const step = 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') {
// Convert an inherited ground-target frame without changing the world
// pose. Rotation must pivot about Earth, never the previous local target.
const camera = cameraOf(_viewer);
camera.cancelFlight();
camera.release();
// Handoff may level a route's bank. Keep the caller's world pose, but
// write it only when the handoff changed it: a heading and pitch
// conversion inside the camera is singular at nadir, so an unchanged
// pose is left exactly as it is.
const now = camera.pose();
if (
distance(now.position, globePose.position) > 1e-6 ||
distance(now.direction, globePose.direction) > 1e-9 ||
distance(normalize(now.up), globePose.up) > 1e-9
)
camera.setView({
destination: globePose.position,
orientation: { direction: globePose.direction, up: globePose.up },
});
state.rotationAxis = globePose.up;
state.rotationRadius = magnitude(globePose.position);
}
if (motion === 'orbit') {
if (cameraFlying()) {
// A camera flight is in progress — ALWAYS arm and capture 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.
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',
};
}
// Pitch from geometry so lookAt reproduces the CURRENT framing exactly.
const pose = cameraOf(_viewer).pose();
state.target = target;
state.hpr = orbitFraming(pose, target);
state.hprStartHeading = pose.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: state.mode,
...(tiltToPitch !== null && {
pitchDeg: Math.round(toDegrees(stoppedAt ?? tiltToPitch)),
}),
...(stopNote !== null && { note: stopNote }),
};
};
const preserveCameraFlight =
motion === 'orbit' && cameraFlying() && !isFollowing(_viewer);
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 = cameraOf(_viewer).pose().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.target, m.hpr, m.hpr.pitch);
if (Math.abs(error) < 1e-7) break;
const pitch = clamp(m.hpr.pitch + error, -PI_OVER_TWO, cap);
if (pitch === m.hpr.pitch) break;
m.hpr.pitch = pitch;
}
from = Math.min(from, pivotCameraPitch(m.target, m.hpr, m.hpr.pitch));
}
const limit =
m.hpr && !tiltClearanceBinds(m.hpr.range)
? Math.min(
PITCH_MAX,
pivotCameraPitch(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(toDegrees(goal - from)) / TILT_TO_DEG_S,
);
const limited = goal !== m.askedPitch;
return {
pitchDeg: Math.round(toDegrees(goal)),
note: limited
? tiltHorizonNote(goal)
: `The tilt now reaches ${Math.round(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.
*/
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';
// 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) => 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] + 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, cells),
cameraHeightM: findCamera(_viewer)?.pose().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();
}