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:
Sameh Khamis committed 2026-11-09 21:34:03 -08:00
commit 96764f85ca
28 files changed
+4764 -145

No files matched your search

+200
View File
@@ -0,0 +1,200 @@
import { isFollowing } from './data/followed.js';
import { geodeticSurfaceNormal, rayEllipsoid } from './geo/ellipsoid.js';
import { rotate } from './geo/frames.js';
import { clamp, dot, normalize, toRadians } from './geo/vector.js';
import { findCamera } from './render/rendererOf.js';
// The camera's free look (Shift+drag) turns the camera in place. Near the
// ground that surveys a city; from orbit a few drags turn the whole planet out
// of frame and leave only stars.
export const FREE_LOOK_MAX_HEIGHT_METERS = 1_000_000;
// A voice turn from orbit stops when about this share of the frame still shows
// the planet's surface.
export const MIN_GLOBE_FRAME_SHARE = 0.1;
/**
* A free globe camera: the viewer follows nothing, and its camera is not
* locked to a reference frame.
*/
export function isFreeGlobeCamera(viewer) {
const camera = findCamera(viewer);
return (
Boolean(camera) && !isFollowing(viewer) && camera.pose().frameIsIdentity
);
}
const GRID_COLUMNS = 32;
const GRID_ROWS = 18;
// A turn across a sliver of planet moves its edge through sample points, so
// the share wobbles by a cell or two without the planet leaving.
const GRID_NOISE_CELLS = 2;
// Whatever the baseline, a voice turn never takes the planet below this share
// of the frame; a view that already shows less may only keep what it has.
const LOOK_ABSOLUTE_FLOOR_SHARE = 0.01;
const sampleRay = { origin: null, direction: { x: 0, y: 0, z: 0 } };
/**
* Cast a 32×18 grid of view rays, one through the centre of each cell, at the
* WGS84 ellipsoid. With `keyholeRadius` (a radius around the frame centre, in
* units of half the frame height) only the cells inside that circle count: the
* scope mask hides the rest. Returns the surface hits and the cells counted, or
* null for a pose with no perspective view to sample.
* @param {import('./render/contract/camera').CameraPose} pose
*/
function sampleFrame(pose, keyholeRadius) {
if (!Number.isFinite(pose?.fovy) || !Number.isFinite(pose.aspectRatio))
return null;
const aspect = pose.aspectRatio;
const tanY = Math.tan(pose.fovy / 2);
const tanX = tanY * aspect;
const keyholeSquared = keyholeRadius > 0 ? keyholeRadius * keyholeRadius : 0;
const { direction, right, up } = pose;
sampleRay.origin = pose.position;
const ray = sampleRay.direction;
let hits = 0;
let cells = 0;
for (let row = 0; row < GRID_ROWS; row += 1) {
const rowY = (2 * (row + 0.5)) / GRID_ROWS - 1;
for (let column = 0; column < GRID_COLUMNS; column += 1) {
const columnX = (2 * (column + 0.5)) / GRID_COLUMNS - 1;
if (
keyholeSquared &&
(columnX * aspect) ** 2 + rowY * rowY > keyholeSquared
)
continue;
cells += 1;
const x = columnX * tanX;
const y = rowY * tanY;
ray.x = direction.x + right.x * x + up.x * y;
ray.y = direction.y + right.y * x + up.y * y;
ray.z = direction.z + right.z * x + up.z * y;
const length = Math.hypot(ray.x, ray.y, ray.z);
ray.x /= length;
ray.y /= length;
ray.z /= length;
if (rayEllipsoid(sampleRay)) hits += 1;
}
}
return { hits, cells };
}
/**
* Share of the frame, from 0 to 1, that shows the planet's surface: the
* fraction of a 32×18 grid of view rays, one through the centre of each cell,
* that hit the WGS84 ellipsoid. With `keyholeRadius` (see `sampleFrame`) it is
* the share of the visible circle instead. A pose with no perspective view
* counts as fully covered.
* @param {import('./render/contract/camera').CameraPose} pose
*/
export function globeFrameShare(pose, { keyholeRadius = 0 } = {}) {
const sample = sampleFrame(pose, keyholeRadius);
if (!sample || sample.cells === 0) return 1;
return sample.hits / sample.cells;
}
/** True when none of the planet's surface is in `pose`'s visible frame. */
export function globeOutOfFrame(pose, options) {
return globeFrameShare(pose, options) === 0;
}
/**
* `pose` after an in-place look (`'up'`, `'down'`, `'left'` or `'right'`) by
* `angle` radians, as the camera port's `look` turns it: up and down about
* the view's right axis, left and right about its up axis. The eye stays.
* @param {import('./render/contract/camera').CameraPose} pose
* @returns {import('./render/contract/camera').CameraPose} With `direction`,
* `up`, `right` and `pitch` turned; the other angles are not recomputed.
*/
export function lookedPose(pose, look, angle) {
const vertical = look === 'up' || look === 'down';
const axis = vertical ? pose.right : pose.up;
const turn = look === 'up' || look === 'left' ? angle : -angle;
const direction = normalize(rotate(pose.direction, axis, turn));
const next = {
...pose,
direction,
...(vertical
? { up: normalize(rotate(pose.up, axis, turn)) }
: { right: normalize(rotate(pose.right, axis, turn)) }),
};
next.pitch = posePitch(next);
return next;
}
/**
* The pitch of a world-frame pose: its direction's angle above the local
* horizontal at the eye (negative looking down).
* @param {import('./render/contract/camera').CameraPose} pose
*/
export function posePitch(pose) {
return Math.asin(
clamp(dot(pose.direction, geodeticSurfaceNormal(pose.position)), -1, 1),
);
}
const LOOK_EDGE_TOLERANCE = toRadians(0.05);
/**
* How much of one in-place look step (`'up'`, `'down'`, `'left'` or `'right'`
* by a non-negative `angle` in radians) keeps the planet in frame from orbit.
* Above the free-look height the step may not leave less than
* `MIN_GLOBE_FRAME_SHARE` of the visible frame on the planet, or less than
* `startShare` when that is lower, give or take two grid cells of sampling
* noise. However the baseline was taken, it never leaves less than 1% of the
* frame, and a view that already shows less may only keep or gain what it has.
* `startShare` is the baseline the turn is measured against (the current share
* by default): callers pass one value to every step of a motion, and to every
* turn that continues from where the last one left off, so the limit cannot
* slide down a step or a command at a time. `keyholeRadius` limits the measure
* to the scope's visible circle, as in `globeFrameShare`.
* With nothing on screen the limit is nothing either, so the step is left to
* the move-end recovery. Returns `angle` when the whole step fits, otherwise a
* smaller angle that fits, found by bisection to within 0.05°, so a stopped
* motion rests at the limit. Steps are tried on the pose; no camera is moved.
* @param {import('./render/contract/camera').CameraPose} pose
*/
export function lookAngleWithinFrame(
pose,
look,
angle,
{ startShare, keyholeRadius = 0 } = {},
) {
if (!(angle > 0) || !(pose?.height > FREE_LOOK_MAX_HEIGHT_METERS))
return angle;
const sample = sampleFrame(pose, keyholeRadius);
if (!sample || sample.cells === 0) return angle;
const share = sample.hits / sample.cells;
const baseline = startShare ?? share;
// Capped at what is on screen now, so a step that keeps or gains surface is
// never refused, even when the frame has shrunk since the baseline was taken
// (a resized window or a turned phone).
const floor = Math.min(
share,
Math.max(
Math.min(MIN_GLOBE_FRAME_SHARE, baseline) -
GRID_NOISE_CELLS / sample.cells,
Math.min(LOOK_ABSOLUTE_FLOOR_SHARE, baseline),
),
);
// Shares are whole grid cells; the epsilon keeps rounding in `floor` from
// costing a cell.
const fits = (step) =>
globeFrameShare(lookedPose(pose, look, step), { keyholeRadius }) >=
floor - 1e-9;
if (fits(angle)) return angle;
let inside = 0;
let outside = angle;
while (outside - inside > LOOK_EDGE_TOLERANCE) {
const middle = (inside + outside) / 2;
if (fits(middle)) inside = middle;
else outside = middle;
}
return inside;
}
/** True when an in-place look step of `angle` would lose part of its turn. */
export function lookStepLosesGlobe(pose, look, angle, options) {
return lookAngleWithinFrame(pose, look, angle, options) < angle;
}