Files
gods-eye-view/src/globeInView.js
T
German Khokhlov 92c8f8d9da Merge origin/main into german/navara
Main's camera, voice, Cockpit and layer work now runs on the globe
contract where this branch draws through it:

- The voice tilt to an angle, its pivot about the place under the
  crosshair and the frame limit from orbit run through the camera rig;
  src/globeInView.js measures a camera pose with src/geo instead of a
  Cesium camera. The free-look height limit and the globe-in-view
  recovery stay Cesium-only for now.
- Cockpit takes main's own-layer entry rule. Double-clicking the
  followed track goes through cockpitHost.routeDoubleClick, so it works
  on both engines.
- Space Missions' failed-entry rollback and GhostMaps' age filter run
  in the engine-neutral layer code. On Cesium an expired report is
  dropped in place; on Navara its product is redrawn.
- Wildlife Sightings joins the catalog Cesium-only: Navara leaves it
  out, and the shell builds its card only for the real layer, so a
  Navara page no longer fails to start on its stand-in.
- One instruction sentence is shorter, which keeps the Realtime prompt
  within its 55,500-character budget with the Sentinel-2 basemap.
2026-11-07 01:07:26 +04:00

272 lines
10 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.
// Engine-neutral: a camera here is a pose (see `CameraPose` below), and the
// maths run on src/geo, so the same checks hold for Cesium, Navara and the
// fake engine. Never imports Cesium.
import * as geo from './geo/index.js';
const { cartesian3, math } = geo;
const WGS84 = geo.ellipsoid.WGS84;
// Cesium'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;
/**
* @typedef {object} CameraPose A camera, as the globe contract's
* `camera.pose()` gives it plus the eye's height.
* @property {{x:number,y:number,z:number}} position Earth-fixed metres.
* @property {{x:number,y:number,z:number}} direction Unit view direction.
* @property {{x:number,y:number,z:number}} up Unit screen up.
* @property {{x:number,y:number,z:number}} [right] Unit screen right
* (direction × up when absent).
* @property {number} fovy Vertical field of view, radians.
* @property {number} aspectRatio Width over height.
* @property {number} height Ellipsoid height of the eye, metres.
* @property {boolean} [perspective] False for a frustum other than a
* perspective one.
*/
/**
* A free globe camera: the engine's camera follows nothing and is not locked
* to a reference frame (identity transform). Both engines draw only the 3D
* globe.
* @param {import('./globe/contract.js').GlobeEngine} engine
*/
export function isFreeGlobeCamera(engine) {
const camera = engine?.camera;
if (!camera) return false;
return (
!camera.following() &&
camera
.transform()
.every((value, index) => value === geo.matrix4.IDENTITY[index])
);
}
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 sampleDirection = cartesian3.create();
const sampleOffset = cartesian3.create();
const scratchQ = cartesian3.create();
const scratchW = cartesian3.create();
/**
* Whether a ray from `origin` along `direction` meets the WGS84 ellipsoid:
* Cesium's IntersectionTests.rayEllipsoid, answering only hit or miss.
*/
function rayHitsEllipsoid(origin, direction) {
const inverseRadii = WGS84.oneOverRadii;
const q = cartesian3.multiplyComponents(inverseRadii, origin, scratchQ);
const w = cartesian3.multiplyComponents(inverseRadii, direction, scratchW);
const q2 = cartesian3.magnitudeSquared(q);
const qw = cartesian3.dot(q, w);
if (q2 > 1.0) {
// Outside the ellipsoid: looking outward or tangent misses; otherwise it
// hits unless the roots are imaginary.
if (qw >= 0.0) return false;
const product = cartesian3.magnitudeSquared(w) * (q2 - 1.0);
return !(qw * qw < product);
}
// Inside the ellipsoid every ray hits; on it, only one looking inward.
if (q2 < 1.0) return true;
return qw < 0.0;
}
/** The pose's screen-right vector. */
function rightOf(camera) {
return (
camera.right ??
cartesian3.normalize(
cartesian3.cross(camera.direction, camera.up, cartesian3.create()),
cartesian3.create(),
)
);
}
/**
* 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 frustum other than a perspective one, or a pose with no view
* basis to cast rays along.
*/
function sampleFrame(camera, keyholeRadius) {
if (
camera.perspective === false ||
!(camera.fovy > 0) ||
!(camera.aspectRatio > 0) ||
!camera.position ||
!camera.direction ||
!camera.up
)
return null;
const aspect = camera.aspectRatio;
const tanY = Math.tan(camera.fovy / 2);
const tanX = tanY * aspect;
const keyholeSquared = keyholeRadius > 0 ? keyholeRadius * keyholeRadius : 0;
const right = rightOf(camera);
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;
cartesian3.multiplyByScalar(right, columnX * tanX, sampleOffset);
cartesian3.add(camera.direction, sampleOffset, sampleDirection);
cartesian3.multiplyByScalar(camera.up, rowY * tanY, sampleOffset);
cartesian3.add(sampleDirection, sampleOffset, sampleDirection);
cartesian3.normalize(sampleDirection, sampleDirection);
if (rayHitsEllipsoid(camera.position, sampleDirection)) 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 frustum other than a perspective
* one (or a pose with no view basis) counts as fully covered.
* @param {CameraPose} camera
*/
export function globeFrameShare(camera, { keyholeRadius = 0 } = {}) {
const sample = sampleFrame(camera, keyholeRadius);
if (!sample || sample.cells === 0) return 1;
return sample.hits / sample.cells;
}
/** True when none of the planet's surface is in `camera`'s visible frame. */
export function globeOutOfFrame(camera, options) {
return globeFrameShare(camera, options) === 0;
}
/**
* `camera` after an in-place look (`lookUp`, `lookDown`, `lookLeft` or
* `lookRight` by `angle` radians), as Cesium's camera turns: direction, up and
* right rotate about the right vector (up/down) or the up vector (left/right);
* the position stays. Returns a new pose; `camera` is not changed.
* @param {CameraPose} camera
* @returns {CameraPose}
*/
export function lookPose(camera, look, angle) {
const right = rightOf(camera);
const vertical = look === 'lookUp' || look === 'lookDown';
const sign = look === 'lookUp' || look === 'lookLeft' ? 1 : -1;
const rotation = geo.matrix3.fromQuaternion(
geo.quaternion.fromAxisAngle(
vertical ? right : camera.up,
sign * angle,
geo.quaternion.create(),
),
geo.matrix3.create(),
);
const turn = (vector) =>
geo.matrix3.multiplyByVector(rotation, vector, cartesian3.create());
return {
...camera,
position: cartesian3.clone(camera.position),
direction: turn(camera.direction),
up: turn(camera.up),
right: turn(right),
};
}
/**
* The camera's pitch, as Cesium's camera reports it: the angle of the view
* direction above the local horizontal (the geodetic normal's plane) at the
* eye.
* @param {CameraPose} camera
*/
export function posePitch(camera) {
const frame = geo.transforms.eastNorthUpToFixedFrame(camera.position, WGS84);
const up = cartesian3.create(frame[8], frame[9], frame[10]);
return (
math.PI_OVER_TWO -
Math.acos(math.clamp(cartesian3.dot(up, camera.direction), -1, 1))
);
}
const LOOK_EDGE_TOLERANCE = math.toRadians(0.05);
/**
* How much of one in-place look step (`lookUp`, `lookDown`, `lookLeft` or
* `lookRight` 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 a copy of the pose (see
* `lookPose`); `camera` is not moved.
* @param {CameraPose} camera
*/
export function lookAngleWithinFrame(
camera,
look,
angle,
{ startShare, keyholeRadius = 0 } = {},
) {
if (!(angle > 0) || !(camera.height > FREE_LOOK_MAX_HEIGHT_METERS))
return angle;
const sample = sampleFrame(camera, 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),
),
);
const fits = (step) =>
// Shares are whole grid cells; the epsilon keeps rounding in `floor` from
// costing a cell.
globeFrameShare(lookPose(camera, 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(camera, look, angle, options) {
return lookAngleWithinFrame(camera, look, angle, options) < angle;
}