diff --git a/src/data/trackedCamera.js b/src/data/trackedCamera.js index 5ba9fdba5..94a1f3db0 100644 --- a/src/data/trackedCamera.js +++ b/src/data/trackedCamera.js @@ -2,8 +2,10 @@ import { distance, eastNorthUp, inverseFrameVector, + magnitude, normalize, scale, + vec, } from '../geo/index.js'; /** @@ -36,3 +38,40 @@ export function keptViewFrom(pose, at) { const look = normalize(inverseFrameVector(eastNorthUp(at), pose.direction)); return scale(look, -range); } + +/** + * The least level share of a followed view: a view straight down keeps its + * heading only through a level part of its own, since a follow's framing + * turns the eye's right out of it (render/camera/followTransition.js). + */ +const MIN_LEVEL = 1e-4; + +/** + * `keptViewFrom` for a follow: the same range and the same tilt to the + * target's horizon, turned to the camera's own heading. A follow frames the + * eye from its offset alone, its heading the way the offset leans. Seen from + * straight down, the eye's view leans at a target off the centre only as far + * as the Earth curves between them, and towards the eye: kept as it is, the + * camera would turn to face the target's bearing. Null as `keptViewFrom`. + * @param {{position: object, direction: object, heading?: number}|null|undefined} pose + * The camera port's pose; `heading` in radians, clockwise from north. + * @param {{x: number, y: number, z: number}|null|undefined} at The target. + * @returns {{x: number, y: number, z: number}|null} + */ +export function followViewFrom(pose, at) { + const kept = keptViewFrom(pose, at); + if (!kept || !Number.isFinite(pose.heading)) return kept; + const range = magnitude(kept); + const lookUp = -kept.z / range; + const level = Math.max( + Math.sqrt(Math.max(0, 1 - lookUp * lookUp)), + MIN_LEVEL, + ); + const up = Math.sign(lookUp) * Math.sqrt(Math.max(0, 1 - level * level)); + const look = vec( + level * Math.sin(pose.heading), + level * Math.cos(pose.heading), + up, + ); + return scale(look, -range); +} diff --git a/src/data/trackedCamera.test.mjs b/src/data/trackedCamera.test.mjs index 60e452b11..c34c53714 100644 --- a/src/data/trackedCamera.test.mjs +++ b/src/data/trackedCamera.test.mjs @@ -1,7 +1,8 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import * as Cesium from 'cesium'; -import { keptViewFrom } from './trackedCamera.js'; +import { followViewFrom, keptViewFrom } from './trackedCamera.js'; +import { followFramingEye } from '../render/camera/followTransition.js'; import { distance, eastNorthUp, @@ -74,3 +75,60 @@ test('a kept view needs an eye apart from the target', () => { null, ); }); + +/** Heading, radians clockwise from north, of a framing eye's up in its frame. */ +const framedHeading = (offset) => { + const { up } = followFramingEye(offset); + return Math.atan2(up.x, up.y); +}; + +test("a followed view from straight down keeps the camera's heading, not the target's bearing", () => { + // The camera 60 km up, straight down, heading north; the target 40 km to + // the west-north-west of the point under it. + const under = fromDegrees(-122.38, 37.62, 0); + const eye = framePoint(eastNorthUp(under), { x: 0, y: 0, z: 60_000 }); + const direction = normalize( + frameVector(eastNorthUp(under), { x: 0, y: 0, z: -1 }), + ); + const at = framePoint(eastNorthUp(under), { x: -37_000, y: 15_000, z: 0 }); + const pose = { position: eye, direction, heading: 0 }; + // Kept as it is, the view leans only as the Earth curves, towards the eye: + // the framing would face the target's bearing. + const kept = keptViewFrom(pose, at); + assert.ok(Math.abs(framedHeading(kept)) > 1, 'kept: turned'); + const followed = followViewFrom(pose, at); + assert.ok(Math.abs(framedHeading(followed)) < 1e-9, 'followed: still north'); + assert.ok( + Math.abs(magnitude(followed) - magnitude(kept)) < 1e-6, + 'its range', + ); + for (const heading of [Math.PI / 2, 2.5]) { + const turned = followViewFrom({ ...pose, heading }, at); + const h = framedHeading(turned); + assert.ok( + Math.abs(Math.atan2(Math.sin(h - heading), Math.cos(h - heading))) < 1e-9, + `heading ${heading} kept, not ${h}`, + ); + } +}); + +test("a followed view keeps its range and its tilt to the target's horizon", () => { + const at = fromDegrees(-122.2, 37.7, 600); + const enu = eastNorthUp(at); + const eye = framePoint(enu, { x: 300, y: -1600, z: 1100 }); + const direction = normalize(frameVector(enu, { x: -250, y: 1600, z: -1150 })); + const kept = keptViewFrom({ position: eye, direction }, at); + const followed = followViewFrom( + { position: eye, direction, heading: 0.1 }, + at, + ); + assert.ok(Math.abs(magnitude(followed) - magnitude(kept)) < 1e-6); + assert.ok(Math.abs(followed.z - kept.z) < 1e-6, 'the same tilt'); + assert.ok( + Math.abs(framedHeading(followed) - 0.1) < 1e-9, + "the pose's heading", + ); + // A pose with no heading keeps the view as it is. + assert.deepEqual(followViewFrom({ position: eye, direction }, at), kept); + assert.equal(followViewFrom(null, at), null); +}); diff --git a/src/data/trackingClickGesture.test.mjs b/src/data/trackingClickGesture.test.mjs index 51ee0074c..0da21c93c 100644 --- a/src/data/trackingClickGesture.test.mjs +++ b/src/data/trackingClickGesture.test.mjs @@ -121,7 +121,7 @@ test('a click on an aircraft follows it keeping the camera’s view; other selec ); assert.match( source, - /keepView\s*\?\s*keptViewFrom\(camera\.pose\(\), getTrackedPosition\(\)\)/, + /keepView\s*\?\s*followViewFrom\(camera\.pose\(\), getTrackedPosition\(\)\)/, ); assert.match(source, /transitionS: SELECTION_FOLLOW_TRANSITION_S/); } diff --git a/src/layers/flights/tracking.js b/src/layers/flights/tracking.js index bbfbee255..8017e0517 100644 --- a/src/layers/flights/tracking.js +++ b/src/layers/flights/tracking.js @@ -84,7 +84,7 @@ export function createTracking({ const { clearFocusTarget } = services.focus; const { isMilitaryLayerActive, isMilitaryIcao } = services.militaryRegistry; const { trackedLabelModelFromText, refreshTrackedReadout } = services.readout; - const { FOLLOW_MIN_RANGE_M, SELECTION_FOLLOW_TRANSITION_S, keptViewFrom } = + const { FOLLOW_MIN_RANGE_M, SELECTION_FOLLOW_TRANSITION_S, followViewFrom } = services.camera; const { resolvePickId, isOwnedByOtherLayer } = services.picking; const flightsLayer = layer; @@ -1145,7 +1145,7 @@ export function createTracking({ const camera = cameraOf(flightState._viewer); camera.cancelFlight(); const kept = keepView - ? keptViewFrom(camera.pose(), getTrackedPosition()) + ? followViewFrom(camera.pose(), getTrackedPosition()) : null; flightState._followTarget = entityFollowTarget(flightState._trackedEntity, { position: getTrackedPosition, diff --git a/src/layers/military/tracking.js b/src/layers/military/tracking.js index 42d564d88..ef8e7d867 100644 --- a/src/layers/military/tracking.js +++ b/src/layers/military/tracking.js @@ -85,7 +85,7 @@ export function createTracking({ const { createTrail } = services.trails; const { ensureGeoidReady, geoidHeight } = services.geoid; const { clearFocusTarget } = services.focus; - const { FOLLOW_MIN_RANGE_M, SELECTION_FOLLOW_TRANSITION_S, keptViewFrom } = + const { FOLLOW_MIN_RANGE_M, SELECTION_FOLLOW_TRANSITION_S, followViewFrom } = services.camera; const { resolvePickId, isOwnedByOtherLayer } = services.picking; /** The tracked contact's billboard (an icon set on the draw port). */ @@ -1108,7 +1108,7 @@ export function createTracking({ const camera = cameraOf(flightState._viewer); camera.cancelFlight(); const kept = keepView - ? keptViewFrom(camera.pose(), getTrackedPosition()) + ? followViewFrom(camera.pose(), getTrackedPosition()) : null; flightState._followTarget = entityFollowTarget(flightState._trackedEntity, { position: getTrackedPosition, diff --git a/src/layers/rail/follow.js b/src/layers/rail/follow.js index db9033134..0793b60e4 100644 --- a/src/layers/rail/follow.js +++ b/src/layers/rail/follow.js @@ -1,7 +1,7 @@ import { findCamera } from '../../render/rendererOf.js'; import { FOLLOW_MIN_RANGE_M, - keptViewFrom, + followViewFrom, SELECTION_FOLLOW_TRANSITION_S, } from '../../data/trackedCamera.js'; import { copyInto, lerpInto } from '../../geo/vector.js'; @@ -113,7 +113,7 @@ export function createFollow({ state, services, parts }) { function startFollow(entry, position, port) { const offset = - keptViewFrom(port.pose(), position) ?? + followViewFrom(port.pose(), position) ?? railFollowOffset(camera.framing, port.pose()?.heading); const follow = { key: entry.key, diff --git a/src/layers/rail/follow.test.mjs b/src/layers/rail/follow.test.mjs index 52075a824..3d6aa1e1f 100644 --- a/src/layers/rail/follow.test.mjs +++ b/src/layers/rail/follow.test.mjs @@ -6,7 +6,7 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import { FOLLOW_MIN_RANGE_M, - keptViewFrom, + followViewFrom, SELECTION_FOLLOW_TRANSITION_S, } from '../../data/trackedCamera.js'; import { fromDegrees } from '../../geo/ellipsoid.js'; @@ -166,7 +166,7 @@ test('selecting a moving train hands the camera a follow target that rides on it assert.equal(target.frame, 'enu'); assert.equal(target.minRange, FOLLOW_MIN_RANGE_M); assert.equal(target.transitionS, SELECTION_FOLLOW_TRANSITION_S); - const expected = keptViewFrom(pose, at); + const expected = followViewFrom(pose, at); assert.ok(Math.abs(target.viewFrom.x - expected.x) < 1e-6); assert.ok(Math.abs(target.viewFrom.y - expected.y) < 1e-6); assert.ok(Math.abs(target.viewFrom.z - expected.z) < 1e-6);