Files
gods-eye-view/src/globeInView.js
T
Sameh Khamis 96764f85ca 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.
2026-11-09 21:34:03 -08:00

201 lines
7.9 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.
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;
}