Files
gods-eye-view/src/ui/cockpitOrbitalView.js
T

912 lines
32 KiB
JavaScript

/** The orbital (satellite) view of the Cockpit controller: camera, zoom, look and HUD. */
import * as Cesium from 'cesium';
import { formatNumber, msg, t } from '../i18n/index.js';
import {
ORBITAL_DEFAULT_ZOOM,
ORBITAL_PREFETCH_INTERVAL_MS,
centreLinesFirst,
ORBITAL_PREFETCH_MAX_TILES,
ORBITAL_PREFETCH_MIN_ZOOM,
ORBITAL_SETTLE_BLUR_PX,
ORBITAL_ZOOM_LADDER,
ORBITAL_ZOOM_TRANSITION_MS,
cesiumFrustumFovRad,
footprintWidthKm,
fovForZoom,
groundTrackAhead,
imageryLevelForView,
interpolateZoomFov,
nadirOrientation,
nextOrbitalZoom,
offNadirAngleDeg,
offNadirOrientation,
offNadirCentreMeetsEarth,
offNadirSwathScale,
orbitalBaseFovRad,
orbitalMaxZoom,
previousOrbitalZoom,
sensorStripFraction,
sensorSwathZoom,
tilesForPoints,
wheelZoomStep,
zoomSettleHolding,
zoomTransitionState,
} from '../cockpitOrbital.js';
import {
clampOrbitalLook,
lookIsOffset,
orbitalLookReadoutParts,
stepOrbitalLook,
} from '../cockpitLook.js';
import { cockpitUiUpdateDue } from '../cockpitMath.js';
import { createPlaceTracker, nearPlaceRadiusKm } from '../data/placeBelow.js';
import { isPointerFree } from '../data/inputOwnership.js';
import { zoomableSwathKm } from '../layers/satellites/sensors.js';
import {
easeOrbitalLook,
orbitalFocusReadout,
releaseOrbitalFocus,
updateOrbitalFocus,
} from './cockpitOrbitalFocus.js';
import { orbitalEyePosition } from './cockpitOrbitalSatellites.js';
import {
COCKPIT_CONTEXT_UPDATE_MS,
COCKPIT_HUD_UPDATE_MS,
compassPointLabel,
formatCockpitCoordinate,
} from './cockpitPresentation.js';
/**
* How often the orbital view asks for a regional brief. A low orbit crosses
* the briefing's 25 km refresh distance every few seconds, so the sub-satellite
* point is briefed on a clock instead.
*/
export const ORBITAL_BRIEF_REFRESH_MS = 60_000;
/** Whether the user asked for reduced motion: zoom steps and tilts cut. */
function prefersReducedMotion() {
return Boolean(
globalThis.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches,
);
}
const IDLE_TRANSITION = Object.freeze({
active: false,
blurPx: 0,
lockTick: false,
});
const NADIR_LOOK = Object.freeze({ yawDeg: 0, pitchDeg: 0 });
/**
* Start an orbital session's state. Keeps the camera's own field of view so
* the exit can put it back exactly.
*/
export function beginOrbital() {
const frustum = this.viewer.camera?.frustum;
const state = {
imagery: acquireOrbitImagery(this.services),
zoom: ORBITAL_DEFAULT_ZOOM,
// Wheel scrolling summed toward the next zoom step (wheelZoomStep).
wheel: null,
// Imagery pre-loaded ahead of the ground track from 16x: when it last
// looked ahead, and the tiles already asked for (oldest first).
prefetchMs: -Infinity,
prefetched: new Set(),
// The provider those tiles came from, and the requests still in flight.
prefetchProvider: null,
prefetchRequests: new Set(),
// A zoom step in flight: the magnification it started from and when.
transition: null,
previousUp: null,
savedFov: Number.isFinite(frustum?.fov) ? frustum.fov : null,
altitudeM: null,
verticalFov: null,
lastBriefMs: 0,
lookTarget: { ...NADIR_LOOK },
lookView: { ...NADIR_LOOK },
lookLastMs: performance.now(),
// What the sub-satellite point is over: undefined until the first
// lookup lands, then a place or null (nothing named there).
place: undefined,
placeTracker: null,
};
state.placeTracker = createPlaceTracker({
lookup: this.services.placeBelow,
onPlace: (place) => {
if (this.orbital !== state) return;
state.place = place;
if (this.lastSubjectInfo?.kind === 'satellite')
publishOrbitalView.call(this, this.lastSubjectInfo);
},
});
this.orbital = state;
}
/** End the orbital session: restore the field of view and clear the HUD. */
export function endOrbital() {
const state = this.orbital;
if (!state) return;
this.orbital = null;
state.placeTracker?.reset();
// Pre-loads still queued or in flight are for a view no longer shown.
for (const request of state.prefetchRequests) request.cancel?.();
state.prefetchRequests.clear();
const frustum = this.viewer.camera?.frustum;
if (frustum && state.savedFov !== null) frustum.fov = state.savedFov;
// Back to the map the operator had, unless they picked another meanwhile.
state.imagery?.release?.()?.catch?.(() => {});
this.publishOrbital(null);
}
/**
* Offer the sub-satellite point to the place tracker, with the radius a
* populated place may lie in to be named (half the settled view's smaller
* ground dimension, from NEAR_PLACE_MIN_ZOOM on), so a zoom step refreshes
* the place at once.
*/
function trackPlace(info, nowMs) {
const state = this.orbital;
if (!state?.placeTracker) return;
let nearKm = null;
if (Number.isFinite(info.altitudeM)) {
const frustum = this.viewer.camera?.frustum;
const aspect = Number.isFinite(frustum?.aspectRatio)
? frustum.aspectRatio
: canvasAspect(this.viewer);
const fov = fovForZoom(orbitalBaseFovRad(info.altitudeM), state.zoom);
// The field of view is vertical: aspect 1 gives the ground height.
nearKm = nearPlaceRadiusKm(
state.zoom,
footprintWidthKm(info.altitudeM, fov, aspect),
footprintWidthKm(info.altitudeM, fov, 1),
);
}
state.placeTracker.update(info.latitude, info.longitude, nowMs, nearKm);
}
/**
* Lease the map for flat imagery while in orbit. Another owner already
* holding it (an imagery comparison) keeps the map as it is.
* @returns {{release: () => Promise<void>}|null}
*/
function acquireOrbitImagery(services) {
try {
const lease = services?.acquireOrbitImagery?.() ?? null;
lease?.ready?.catch?.(() => {});
return lease;
} catch {
return null;
}
}
/** The magnification the view shows at `nowMs`, mid-step included. */
function currentMagnification(state, baseFov, nowMs) {
const fov = verticalFovAt(state, baseFov, nowMs).fov;
return Math.tan(baseFov / 2) / Math.tan(fov / 2);
}
/**
* The vertical field of view at `nowMs` and the step's HUD state. Once the
* field of view lands, the focus pull holds until the imagery has loaded
* (see `zoomSettleHolding`), then the reticle locks. A step that has settled
* (lock tick over) is retired.
*/
function verticalFovAt(state, baseFov, nowMs, tilesLoaded = true) {
const target = fovForZoom(baseFov, state.zoom);
const step = state.transition;
if (!step) return { fov: target, transition: IDLE_TRANSITION, moving: false };
const elapsedMs = nowMs - step.startMs;
const landedMs = elapsedMs - ORBITAL_ZOOM_TRANSITION_MS;
if (landedMs >= 0 && step.heldMs === undefined) {
if (zoomSettleHolding(landedMs, tilesLoaded)) {
return {
fov: target,
transition: {
active: true,
blurPx: ORBITAL_SETTLE_BLUR_PX,
lockTick: false,
},
moving: true,
};
}
step.heldMs = landedMs;
}
// The lock tick runs from the end of the hold, not the end of the move.
const now = zoomTransitionState(elapsedMs - (step.heldMs ?? 0));
const fov = interpolateZoomFov(
fovForZoom(baseFov, step.fromZoom),
target,
now.progress,
);
return {
fov,
transition: {
active: now.active,
// Settled steps carry no residue of the blur curve (sin π ≠ 0).
blurPx: now.active ? now.blurPx : 0,
lockTick: now.lockTick,
},
moving: now.active || now.lockTick,
};
}
/** Apply the field of view for the altitude and time; returns the HUD state. */
function applyFov(state, altitudeM, nowMs) {
const baseFov = orbitalBaseFovRad(altitudeM);
const reading = verticalFovAt(
state,
baseFov,
nowMs,
tilesLoaded(this.viewer),
);
// The step's last frame (its lock tick over) publishes the idle state.
if (state.transition && !reading.moving) {
state.transition = null;
reading.transition = IDLE_TRANSITION;
}
state.verticalFov = reading.fov;
const frustum = this.viewer.camera?.frustum;
if (frustum && 'fov' in frustum) {
const aspect = Number.isFinite(frustum.aspectRatio)
? frustum.aspectRatio
: canvasAspect(this.viewer);
frustum.fov = cesiumFrustumFovRad(reading.fov, aspect);
}
return reading;
}
/**
* Whether the imagery under the view has loaded. Flat imagery drapes the
* globe; with the globe hidden (Google 3D kept) there is nothing to wait for.
*/
function tilesLoaded(viewer) {
const globe = viewer.scene?.globe;
return !globe?.show || globe.tilesLoaded !== false;
}
function canvasAspect(viewer) {
const canvas = viewer.scene?.canvas;
const width = canvas?.clientWidth;
const height = canvas?.clientHeight;
return width > 0 && height > 0 ? width / height : 1;
}
/** Copy a plain vector into a Cesium scratch. */
function intoCartesian(vector, result) {
result.x = vector.x;
result.y = vector.y;
result.z = vector.z;
return result;
}
/**
* Drive the orbital camera for one rendered frame: at the satellite's own
* per-frame position, looking at the Earth's centre with the ground track at
* the top (north at the top for a satellite with none), tilted by the
* off-nadir look. A low orbit moves ~7.6 km/s, so there is no cadence
* gate here; only the HUD and briefing keep theirs.
* @param {number} nowMs Frame time.
*/
export function updateOrbital(nowMs) {
// Tracking anything from orbit (an aircraft, another satellite) ends the
// view and leaves Cesium tracking with that target.
if (this.viewer.trackedEntity?.position) {
this.exit({ restoreTracking: false });
return;
}
const info = this.readSatelliteInfo();
if (!info || info.noradId !== this.subjectId || !this.orbital) {
this.exit({ restoreTracking: false });
return;
}
const position = this.services.satellitesLayer?.getCockpitPosition?.(
this.scratchTarget,
);
if (!position) return;
const state = this.orbital;
// On the satellite, or on the way to it after Previous/Next.
const eye = orbitalEyePosition(state, position, nowMs);
// Track-up: the ground track at the top, so the picture scrolls along it.
// A geostationary satellite has no track and stays north-up.
const nadir = nadirOrientation(eye, {
previousUp: state.previousUp,
headingDeg: Number.isFinite(info.groundTrackDeg)
? info.groundTrackDeg
: null,
});
if (!nadir) return;
state.previousUp = nadir.north;
state.altitudeM = info.altitudeM;
// The top step follows live altitude and the window's shape: when it
// falls below the zoom shown, step back to it rather than show finer
// ground than the sensor images.
const maxZoom = orbitalMaxZoomFor.call(this, info);
if (state.zoom > maxZoom) {
this.lastSubjectInfo = info;
goToZoom.call(this, maxZoom);
}
// A ground focus aims the look itself (src/ui/cockpitOrbitalFocus.js).
if (!updateOrbitalFocus.call(this, state, nadir, eye, nowMs))
state.lookView = easeOrbitalLook(
state,
nowMs - (state.lookLastMs || nowMs),
{ immediate: prefersReducedMotion() },
);
state.lookLastMs = nowMs;
const view = offNadirOrientation(nadir, {
northDeg: state.lookView.pitchDeg,
eastDeg: state.lookView.yawDeg,
});
const zoomStepping = Boolean(state.transition);
const reading = applyFov.call(this, state, info.altitudeM, nowMs);
this.viewer.camera.setView({
destination: eye,
orientation: {
direction: intoCartesian(view.direction, this.scratchForward),
up: intoCartesian(view.up, this.scratchUp),
},
});
this.lastSubjectInfo = info;
if (
zoomStepping ||
cockpitUiUpdateDue(nowMs, this.lastHudUpdateMs, COCKPIT_HUD_UPDATE_MS)
) {
this.lastHudUpdateMs = nowMs;
trackPlace.call(this, info, nowMs);
publishOrbitalView.call(this, info, reading.transition);
}
if (
cockpitUiUpdateDue(
nowMs,
this.lastContextUpdateMs,
COCKPIT_CONTEXT_UPDATE_MS,
)
) {
this.lastContextUpdateMs = nowMs;
updateOrbitalContext.call(this, info, nowMs);
}
prefetchImageryAhead.call(this, info, nowMs);
}
/** Tiles remembered as asked for in one orbital session. */
const PREFETCH_MEMORY = 512;
/** How far the shown time may be from now for the look-ahead to run, ms. */
const PREFETCH_LIVE_TOLERANCE_MS = 60_000;
/**
* From 16x the view is 10 to 40 km wide while the ground track moves about
* 7 km/s, so the imagery under it arrives late. Every
* ORBITAL_PREFETCH_INTERVAL_MS ask the globe's base imagery for the tiles
* the view will need 5 to 20 s ahead (`groundTrackAhead`), at the level
* Cesium will draw there (`imageryLevelForView`), so the browser has them
* cached when the view gets there. The requests are throttled at the
* lowest priority: Cesium's request scheduler declines one while the
* imagery server's slots are taken by the tiles on screen or the scheduler
* is full, and a declined tile is asked again on a later look-ahead. At most
* ORBITAL_PREFETCH_MAX_TILES a time; the last PREFETCH_MEMORY tiles asked
* for are not asked again unless their request failed, and a new base map
* starts the memory over. Exit cancels the requests still pending. Nothing
* below 16x, while the view is tilted off nadir (it no longer looks at the
* track), with the world clock away from now (paused, played back), after
* the exit, or with the globe hidden (Google 3D tiles drawn instead).
* @returns {number} The tiles asked for.
*/
export function prefetchImageryAhead(info, nowMs) {
const state = this.orbital;
if (!state || !(state.zoom >= ORBITAL_PREFETCH_MIN_ZOOM)) return 0;
// Tilted, the view looks off the track the pre-load follows.
if (lookIsOffset(state.lookTarget, 0) || lookIsOffset(state.lookView, 0))
return 0;
if (nowMs - state.prefetchMs < ORBITAL_PREFETCH_INTERVAL_MS) return 0;
// The look-ahead runs at live speed: with the world clock paused, played
// back or moved, the view will not pass where it points.
if (
Number.isFinite(info.atMs) &&
Math.abs(info.atMs - Date.now()) > PREFETCH_LIVE_TOLERANCE_MS
)
return 0;
state.prefetchMs = nowMs;
try {
const globe = this.viewer.scene?.globe;
if (!globe || globe.show === false) return 0;
const provider = baseImageryProvider(this.viewer);
if (!provider) return 0;
// Another base map: its tiles have not been asked for.
// A fresh set, so a late failure from the old map's requests cannot
// drop a tile the new one has fetched.
if (provider !== state.prefetchProvider) {
for (const request of state.prefetchRequests) request.cancel?.();
state.prefetchRequests = new Set();
state.prefetched = new Set();
state.prefetchProvider = provider;
}
const fov = fovForZoom(orbitalBaseFovRad(info.altitudeM), state.zoom);
const viewKm = footprintWidthKm(
info.altitudeM,
fov,
viewAspect(this.viewer),
);
// The ground one CSS pixel covers at the nadir point, as Cesium's
// screen-space error measures it: the vertical field of view over the
// canvas height, at the satellite's altitude.
const canvas = this.viewer.scene?.canvas;
const heightPx = canvas?.clientHeight || canvas?.height;
const terrain =
this.viewer.terrainProvider ?? this.viewer.scene?.globe?.terrainProvider;
const level = imageryLevelForView(provider.tilingScheme, {
metresPerPixel: (info.altitudeM * 2 * Math.tan(fov / 2)) / heightPx,
latitudeDeg: info.latitude,
geographic:
provider.tilingScheme.projection instanceof Cesium.GeographicProjection,
tileWidthPx: provider.tileWidth,
minimumLevel: provider.minimumLevel,
maximumLevel: provider.maximumLevel,
maximumScreenSpaceError: globe.maximumScreenSpaceError,
terrainLevelErrorM:
typeof terrain?.getLevelMaximumGeometricError === 'function'
? (terrainLevel) =>
terrain.getLevelMaximumGeometricError(terrainLevel)
: undefined,
});
if (level === null) return 0;
const memory = state.prefetched;
const tiles = tilesForPoints(
provider.tilingScheme,
centreLinesFirst(groundTrackAhead(info, viewKm)),
level,
{
maxTiles: ORBITAL_PREFETCH_MAX_TILES,
skip: (key) => memory.has(key),
},
);
let asked = 0;
for (const tile of tiles) {
let pending;
let request;
try {
// The tiles on screen keep their slots: Cesium's scheduler declines
// this request while the imagery server's slots are taken (shared
// with the globe's own tile requests, throttleByServer) or the
// scheduler is full, and at the lowest priority it is the first
// dropped from the priority heap, never one the screen asked for.
pending = provider.requestImage(
tile.x,
tile.y,
tile.level,
(request = new Cesium.Request({
throttle: true,
throttleByServer: true,
priority: Number.MAX_VALUE,
type: Cesium.RequestType.IMAGERY,
})),
);
} catch {
continue;
}
// A provider that declines now (throttled) is asked again later.
if (!pending) continue;
const requests = state.prefetchRequests;
requests.add(request);
Promise.resolve(pending).then(
() => requests.delete(request),
(error) => {
requests.delete(request);
// Dropped by the scheduler (rejected with no error): asked again
// later. A tile that failed to load stays remembered, so one
// missing from the map is not asked for every look-ahead.
if (error === undefined) memory.delete(tile.key);
},
);
memory.add(tile.key);
if (memory.size > PREFETCH_MEMORY)
memory.delete(memory.values().next().value);
asked += 1;
}
return asked;
} catch {
return 0;
}
}
/**
* The provider of the lowest shown imagery layer, the base map the globe
* drapes, when it can be asked for a tile; else null.
*/
function baseImageryProvider(viewer) {
const layers = viewer.imageryLayers ?? viewer.scene?.imageryLayers;
const count = Number.isInteger(layers?.length) ? layers.length : 0;
for (let i = 0; i < count; i += 1) {
const layer = layers.get(i);
if (!layer || layer.show === false || layer.alpha === 0) continue;
const provider = layer.imageryProvider;
if (
typeof provider?.requestImage === 'function' &&
typeof provider.tilingScheme?.positionToTileXY === 'function'
)
return provider;
return null;
}
return null;
}
/**
* Brief the sub-satellite point: the local page every context beat, the
* regional brief on its own slower clock.
*/
function updateOrbitalContext(info, nowMs, force = false) {
this.updateLocalPosition(info);
const state = this.orbital;
if (
state &&
(force || nowMs - state.lastBriefMs >= ORBITAL_BRIEF_REFRESH_MS)
) {
state.lastBriefMs = nowMs;
this.maybeRefreshRegionalBrief(info);
}
}
/**
* A track-up view tilts along and across the ground track, not toward the
* compass: the look's north/east axes are the frame's top and right.
*/
const TRACK_LOOK_LABELS = Object.freeze({
N: msg('FWD'),
S: msg('AFT'),
E: msg('RIGHT'),
W: msg('LEFT'),
});
function lookDirectionLabel(code, trackUp) {
return trackUp ? t(TRACK_LOOK_LABELS[code]) : compassPointLabel(code);
}
/**
* Word the off-nadir look with its total angle from nadir first, or '' at
* nadir: `OFF-NADIR 18.0° · FWD 15° · RIGHT 10°`.
*/
function wordOffNadir(look, { trackUp = false } = {}) {
const parts = orbitalLookReadoutParts(look);
const words = [];
if (parts.northSouth)
words.push(
t('{direction} {angle}°', {
direction: lookDirectionLabel(parts.northSouth, trackUp),
angle: formatNumber(parts.northSouthDeg),
}),
);
if (parts.eastWest)
words.push(
t('{direction} {angle}°', {
direction: lookDirectionLabel(parts.eastWest, trackUp),
angle: formatNumber(parts.eastWestDeg),
}),
);
if (!words.length) return '';
return t('OFF-NADIR {angle}° · {offset}', {
angle: formatNumber(offNadirAngleDeg(lookTilt(parts)), {
minimumFractionDigits: 1,
maximumFractionDigits: 1,
}),
offset: words.join(' · '),
});
}
/** The look's tilt as worded: whole degrees, signed north and east. */
function lookTilt(parts) {
return {
northDeg: (parts.northSouth === 'S' ? -1 : 1) * parts.northSouthDeg,
eastDeg: (parts.eastWest === 'W' ? -1 : 1) * parts.eastWestDeg,
};
}
/**
* Word a ground focus's off-nadir angle, as image metadata gives it:
* `OFF-NADIR 23.4°`.
*/
function wordFocusOffNadir(focus) {
return t('OFF-NADIR {angle}°', {
angle: formatNumber(focus.offNadirDeg, {
minimumFractionDigits: 1,
maximumFractionDigits: 1,
}),
});
}
/**
* Publish the orbital HUD. The swath is the nadir footprint, so it is left
* out while the view is tilted off nadir. A ground focus reads the single
* off-nadir angle to its target and scales the swath by the tilt onto it.
* @param {object} info Satellite subject (`readSatelliteInfo`).
* @param {{active: boolean, blurPx: number, lockTick: boolean}} transition
*/
export function publishOrbitalView(info, transition = IDLE_TRANSITION) {
const state = this.orbital;
if (!state || !info) return;
const focus = orbitalFocusReadout.call(this);
const offset = Boolean(focus) || lookIsOffset(state.lookTarget, 0);
const aspect = Number.isFinite(this.viewer.camera?.frustum?.aspectRatio)
? this.viewer.camera.frustum.aspectRatio
: canvasAspect(this.viewer);
const settledFov = fovForZoom(orbitalBaseFovRad(info.altitudeM), state.zoom);
const footprintKm = footprintWidthKm(info.altitudeM, settledFov, aspect);
// The strip is drawn over the picture, so it follows the view as a step
// zooms (republished every frame then), not the step it is heading for.
const shownKm = Number.isFinite(state.verticalFov)
? footprintWidthKm(info.altitudeM, state.verticalFov, aspect)
: footprintKm;
const maxZoom = orbitalMaxZoomFor.call(this, info);
const swathKm = sensorSwathKm(info);
const trackUp = Number.isFinite(info.groundTrackDeg);
// A ground focus sets the tilt; otherwise the look target does.
const tilt = focus
? { northDeg: focus.pitchDeg, eastDeg: focus.yawDeg }
: offset
? lookTilt(orbitalLookReadoutParts(state.lookTarget))
: null;
const swathScale = tilt ? offNadirSwathScale(tilt) : 1;
// Tilted past the limb, the view's centre looks into space: no swath. The
// camera eases toward the target, so both must meet the Earth; the HUD
// republishes on its cadence, so the swath appears once the view arrives.
// Exact angles here, not the whole degrees the readout rounds to; a ground
// focus aims the look itself, so its angles are the target.
const target = focus
? { pitchDeg: focus.pitchDeg, yawDeg: focus.yawDeg }
: clampOrbitalLook(state.lookTarget);
// The eased view is tested even with the target at nadir: on the way back
// from past the limb it still looks into space.
const seesEarth =
(!offset ||
offNadirCentreMeetsEarth(info.altitudeM, {
northDeg: target.pitchDeg,
eastDeg: target.yawDeg,
})) &&
offNadirCentreMeetsEarth(info.altitudeM, {
northDeg: state.lookView?.pitchDeg ?? 0,
eastDeg: state.lookView?.yawDeg ?? 0,
});
this.publishOrbital({
name: info.name,
classLabel: info.classLabel || '',
altitudeM: info.altitudeM,
velocityMps: Number.isFinite(info.velocityMps) ? info.velocityMps : null,
latitude: info.latitude,
longitude: info.longitude,
zoom: state.zoom,
zoomSteps: ORBITAL_ZOOM_LADDER.filter((step) => step <= maxZoom),
maxZoom,
footprintKm: offset ? null : footprintKm,
// The imaging sensor's swath, drawn to scale; null without one. The
// SENSOR step's zoom is null when the swath lies outside 1x..maxZoom.
// Looking past the limb there is no ground for it to cover: no sensor.
sensor:
swathKm === null || !seesEarth
? null
: {
label: info.sensor?.label ?? null,
swathKm,
// Off nadir the view and the swath widen alike: the strip
// keeps its share of the frame. No strip where it would
// mislead: a geostationary view has no ground track to run
// along, and a SAR images to one side of nadir, not under it.
stripFraction:
trackUp && info.sensor?.type !== 'SAR'
? sensorStripFraction(swathKm, shownKm)
: null,
zoom: sensorSwathZoom(info.altitudeM, swathKm, aspect, maxZoom),
},
transition: { ...transition },
look: {
offset,
readout: focus
? wordFocusOffNadir(focus)
: offset
? wordOffNadir(state.lookTarget, { trackUp })
: '',
// The mapped point the view is held on, or null.
focus: focus ? { key: focus.key, label: focus.label } : null,
// Off nadir, the ground width at the view's centre, approximated from
// the nadir footprint (`offNadirSwathScale`); 1 and null at nadir.
swathScale,
swathKm:
offset && seesEarth && Number.isFinite(footprintKm)
? footprintKm * swathScale
: null,
},
// Track-up turns the frame to the ground track; north then sits at
// `northDeg` clockwise from the top. A geostationary view stays north-up.
trackUp,
northDeg: trackUp ? (360 - info.groundTrackDeg) % 360 : 0,
place: state.place,
noradId: info.noradId ?? null,
cosparId: info.cosparId ?? null,
tle: info.tle ?? null,
// Read on the HUD's cadence, so the age stays current without a timer.
// The gap between the TLE's epoch and the time the satellite is shown
// at (the world clock's), either side: SGP4 drifts both ways.
tleAgeMs: Number.isFinite(info.tle?.epochMs)
? Math.abs(
(Number.isFinite(info.atMs) ? info.atMs : Date.now()) -
info.tle.epochMs,
)
: null,
owner: info.owner ?? null,
operator: info.operator ?? null,
});
}
/**
* Present the orbital view on entry and after a language switch: the HUD,
* the local page and a regional brief for the sub-satellite point.
* @param {object} info Satellite subject.
*/
export function updateOrbitalHud(info, nowMs = performance.now()) {
this.lastSubjectInfo = info;
// A satellite has no flight plan and no Contact card.
this.routeView.visible = false;
this.clearPredictiveRoute();
this.showContextCard(false);
trackPlace.call(this, info, nowMs);
publishOrbitalView.call(this, info);
updateOrbitalContext.call(this, info, nowMs, true);
}
/** Re-apply the field of view and publish after a zoom or look change. */
function presentNow() {
const state = this.orbital;
const info = this.lastSubjectInfo;
if (!state || info?.kind !== 'satellite') return;
const nowMs = performance.now();
const reading = Number.isFinite(state.altitudeM ?? info.altitudeM)
? applyFov.call(this, state, state.altitudeM ?? info.altitudeM, nowMs)
: null;
publishOrbitalView.call(this, info, reading?.transition ?? IDLE_TRANSITION);
}
/**
* Step the optical zoom one step in (`direction` > 0) or out. The step
* animates over ORBITAL_ZOOM_TRANSITION_MS with a focus-pull blur and a
* lock tick, or cuts at once under reduced motion. The ends stay put.
* @param {number} direction Positive to zoom in, negative to zoom out.
* @returns {boolean} True when the zoom changed.
*/
export function stepOrbitalZoom(direction) {
if (!this.active || this.subjectKind !== 'satellite' || !this.orbital)
return false;
const state = this.orbital;
const next =
direction > 0
? nextOrbitalZoom(
state.zoom,
orbitalMaxZoomFor.call(this, this.lastSubjectInfo),
)
: previousOrbitalZoom(state.zoom);
return goToZoom.call(this, next);
}
/**
* Jump to the zoom at which the view is exactly as wide as the imaging
* sensor's swath (the SENSOR step), when that zoom is in range.
* @returns {boolean} True when the zoom changed.
*/
export function jumpToSensorSwath() {
if (!this.active || this.subjectKind !== 'satellite' || !this.orbital)
return false;
const info = this.lastSubjectInfo;
const swathKm = sensorSwathKm(info);
if (swathKm === null || !Number.isFinite(info?.altitudeM)) return false;
const zoom = sensorSwathZoom(
info.altitudeM,
swathKm,
viewAspect(this.viewer),
orbitalMaxZoomFor.call(this, info),
);
return zoom === null ? false : goToZoom.call(this, zoom);
}
/**
* Step the zoom with the mouse wheel over the picture: one step per notch,
* trackpad scrolling summed to a step (`wheelZoomStep`). Only in orbit, and
* never while a tool owns the pointer.
* @param {WheelEvent} event
* @returns {boolean} True when the zoom changed.
*/
export function onOrbitalWheel(event) {
if (!this.active || this.subjectKind !== 'satellite' || !this.orbital)
return false;
if (!isPointerFree()) return false;
const state = this.orbital;
const { accumulator, step } = wheelZoomStep(
state.wheel,
event,
performance.now(),
);
state.wheel = accumulator;
if (!step) return false;
const changed = stepOrbitalZoom.call(this, step);
if (changed) event.preventDefault?.();
return changed;
}
/** The sensor swath the view draws and the SENSOR step targets, km, or null. */
function sensorSwathKm(info) {
const swathKm = info?.sensor?.narrowestSwathKm;
return Number.isFinite(swathKm) && swathKm > 0 ? swathKm : null;
}
/**
* The satellite's tightest zoom step at its live altitude. Only a swath
* confirmed on a cited page opens steps past 8x.
*/
function orbitalMaxZoomFor(info) {
return orbitalMaxZoom(
info?.altitudeM,
zoomableSwathKm(info?.sensor),
viewAspect(this.viewer),
);
}
function viewAspect(viewer) {
return Number.isFinite(viewer.camera?.frustum?.aspectRatio)
? viewer.camera.frustum.aspectRatio
: canvasAspect(viewer);
}
/**
* Move the zoom to `next`, animated from the magnification shown now unless
* reduced motion is on.
* @returns {boolean} True when the zoom changed.
*/
function goToZoom(next) {
const state = this.orbital;
if (!Number.isFinite(next) || next === state.zoom) return false;
const nowMs = performance.now();
const altitudeM = state.altitudeM ?? this.lastSubjectInfo?.altitudeM;
const fromZoom = Number.isFinite(altitudeM)
? currentMagnification(state, orbitalBaseFovRad(altitudeM), nowMs)
: state.zoom;
state.zoom = next;
state.transition = prefersReducedMotion()
? null
: { fromZoom, startMs: nowMs };
presentNow.call(this);
return true;
}
/**
* Tilt the orbital view one arrow step off nadir (see `lookKeyStep`); each
* axis stops at ±45°. The view eases there unless reduced motion is on.
* @param {{axis: 'yaw'|'pitch', sign: number, stepDeg: number}} step
* @returns {boolean} True in an orbital view.
*/
export function turnOrbitalLook(step) {
if (!this.active || this.subjectKind !== 'satellite' || !this.orbital)
return false;
if (!step) return false;
const state = this.orbital;
// An arrow takes the view over from a ground focus where it is.
releaseOrbitalFocus.call(this, { handOver: true });
state.lookTarget = stepOrbitalLook(state.lookTarget, step);
if (prefersReducedMotion()) state.lookView = { ...state.lookTarget };
presentNow.call(this);
return true;
}
/**
* Bring the orbital view back to pure nadir (Home, 0 or the NADIR button).
* @param {{immediate?: boolean}} [options] Jump instead of easing.
* @returns {boolean} True in an orbital view.
*/
export function resetOrbitalLook({ immediate = false } = {}) {
if (!this.active || this.subjectKind !== 'satellite' || !this.orbital)
return false;
const state = this.orbital;
// Ends a ground focus too, easing back on its clock.
releaseOrbitalFocus.call(this);
state.lookTarget = { ...NADIR_LOOK };
if (immediate || prefersReducedMotion()) state.lookView = { ...NADIR_LOOK };
presentNow.call(this);
return true;
}