mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
Merge main through #1532 into the renderer seam
Brings in voice camera tilt (#1520) and free look with globe-in-view recovery (#1532). The tilt and look maths in cameraVerbs.js and globeInView.js run on camera poses and the geo helpers instead of Cesium. The free-look height limit lives in the Cesium adapter (render/cesium/freeLookLimit.js), installed through the application viewer hooks; the globe-in-view recovery that main added to app/viewer.js runs on the camera port in app/globeInViewRecovery.js. The scene-mode checks are gone with the 2D and Columbus modes the seam does not draw.
This commit is contained in:
commit
96764f85ca
28 files changed
+4764
-145
No files matched your search
+710
-78
@@ -20,31 +20,47 @@
|
||||
|
||||
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,
|
||||
@@ -77,6 +93,33 @@ const ONCE = {
|
||||
};
|
||||
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
|
||||
@@ -908,6 +951,17 @@ 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
|
||||
@@ -964,6 +1018,177 @@ export function interruptCameraMotionIfActive(
|
||||
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.look(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();
|
||||
@@ -1006,7 +1231,9 @@ export function interruptCameraMotion(reason = 'interrupt') {
|
||||
if (
|
||||
wasActive &&
|
||||
!tracking &&
|
||||
(_active.kind === 'orbit' || _active.kind === 'route')
|
||||
(_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.
|
||||
@@ -1060,7 +1287,7 @@ function onTick() {
|
||||
let scale = 1;
|
||||
if (m.mode === 'once') {
|
||||
m.elapsed = (m.elapsed || 0) + dt;
|
||||
const t = Math.min(1, m.elapsed / ONCE.durationS);
|
||||
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');
|
||||
@@ -1117,16 +1344,13 @@ function onTick() {
|
||||
: heightM * PAN_VIEW_FRACTION_S[m.speed] * dt;
|
||||
m.lastScale = scale;
|
||||
camera.move(PAN_MOVES[m.direction] ?? 'down', step);
|
||||
} else if (
|
||||
m.kind === 'tilt' ||
|
||||
m.kind === 'rotate' ||
|
||||
m.kind === 'rotate_globe'
|
||||
) {
|
||||
} 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(m.kind === 'tilt' ? ONCE.tiltDeg : ONCE.rotateDeg) *
|
||||
(scale - (m.lastScale || 0))
|
||||
? toRadians(ONCE.rotateDeg) * (scale - (m.lastScale || 0))
|
||||
: toRadians(degS) * dt;
|
||||
m.lastScale = scale;
|
||||
if (m.kind === 'rotate_globe') {
|
||||
@@ -1134,11 +1358,7 @@ function onTick() {
|
||||
// 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 (
|
||||
isFollowing(_viewer) ||
|
||||
_isCockpitActive?.() ||
|
||||
!pose.frameIsIdentity
|
||||
) {
|
||||
if (!isFreeGlobeCamera(_viewer) || _isCockpitActive?.()) {
|
||||
interruptCameraMotion('globe-camera-owner-changed');
|
||||
return;
|
||||
}
|
||||
@@ -1158,16 +1378,14 @@ function onTick() {
|
||||
return;
|
||||
}
|
||||
camera.rotateAround(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 = camera.pose().pitch + (up ? stepRad : -stepRad);
|
||||
if (next > PITCH_MAX || next < PITCH_MIN) {
|
||||
interruptCameraMotion('tilt-clamp');
|
||||
return;
|
||||
}
|
||||
camera.look(up ? 'up' : 'down', stepRad);
|
||||
} else camera.look(m.direction === 'left' ? 'left' : 'right', stepRad);
|
||||
} 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.
|
||||
@@ -1209,6 +1427,169 @@ function orbitFraming(pose, target) {
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 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);
|
||||
@@ -1381,6 +1762,7 @@ export function initCameraVerbs(
|
||||
_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.
|
||||
@@ -1388,18 +1770,102 @@ export function initCameraVerbs(
|
||||
_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 = () => interruptCameraMotion('manual-input');
|
||||
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.
|
||||
@@ -1432,54 +1898,59 @@ export function moveCamera(args = {}, runNavigation = null) {
|
||||
};
|
||||
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 = cameraOf(_viewer).pose().pitch;
|
||||
if (direction === 'up' && pitch >= PITCH_MAX - toRadians(0.5)) {
|
||||
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:
|
||||
'Already at the upper tilt limit (near the horizon) — tilt down, or zoom/pan instead.',
|
||||
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,
|
||||
@@ -1488,6 +1959,33 @@ export function moveCamera(args = {}, runNavigation = null) {
|
||||
};
|
||||
}
|
||||
}
|
||||
// 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')) &&
|
||||
@@ -1567,14 +2065,69 @@ export function moveCamera(args = {}, runNavigation = null) {
|
||||
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.
|
||||
@@ -1600,9 +2153,11 @@ export function moveCamera(args = {}, runNavigation = null) {
|
||||
}
|
||||
if (motion === 'orbit') {
|
||||
if (cameraFlying()) {
|
||||
// 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).
|
||||
// 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',
|
||||
@@ -1659,7 +2214,11 @@ export function moveCamera(args = {}, runNavigation = null) {
|
||||
motion,
|
||||
direction: state.direction,
|
||||
speed,
|
||||
mode,
|
||||
mode: state.mode,
|
||||
...(tiltToPitch !== null && {
|
||||
pitchDeg: Math.round(toDegrees(stoppedAt ?? tiltToPitch)),
|
||||
}),
|
||||
...(stopNote !== null && { note: stopNote }),
|
||||
};
|
||||
};
|
||||
const preserveCameraFlight =
|
||||
@@ -1672,16 +2231,89 @@ export function moveCamera(args = {}, runNavigation = null) {
|
||||
/**
|
||||
* 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 {boolean} true when an orbit consumed the zoom.
|
||||
* @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 || _active.kind !== 'orbit' || !_active.hpr) return false;
|
||||
_active.hpr.range = Math.max(
|
||||
80,
|
||||
Math.min(5_000_000, _active.hpr.range * 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),
|
||||
);
|
||||
return true;
|
||||
// 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))}°.`,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
Reference in new issue
Block a user