From 90e73f2ef21cbdf5d050e423964e8d04d76ad8d8 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 7 Nov 2026 21:30:21 -0800 Subject: [PATCH] Read the eye's follow frame through the camera port and take share-follow off the Cesium list The camera port gains an optional followFrame() (capability followFrame): the frame the eye is placed in now, as a column-major 4x4 matrix to ECEF. Once a follow has framed the camera it is the follow's own frame (east-north-up, or the orbit frame an autodetect follow chose), under lookAt the target's east-north-up frame, otherwise the identity. setView places a world pose and keeps that frame. The Cesium port reads it from camera.transform, only when the capability is on; the stub from its own eye frame. A conformance check covers the world, lookAt and enu-follow frames, the offset in it, and setView keeping it. src/ui/shareFollow.js now reads the pose, the frame and the follow offset through the camera and frame ports: a shared offset is re-expressed in the follow's own frame as before, satellites included, and the eye is placed with setView at exact heading, pitch and roll, so a near-vertical view keeps its roll. placeFollowEye returns false on a camera that cannot say its frame. offsetFromHeadingPitchRange moves to src/geo/frames.js, shared with the stub. --- docs/RENDERER-CONTRACT.md | 6 + src/geo/frames.js | 25 ++- src/render/cesium/camera.js | 23 ++- src/render/cesium/cameraPort.test.mjs | 10 + src/render/cesium/harness.js | 1 + src/render/cesium/ports.js | 9 +- src/render/cesium/ports.test.mjs | 1 + src/render/cesiumAllowList.json | 3 +- src/render/conformance/checks/camera.js | 112 +++++++++++ src/render/contract/camera.d.ts | 14 ++ src/render/contract/common.d.ts | 2 + src/render/contract/contract.test.mjs | 6 + src/render/contract/index.js | 8 +- src/render/stub/camera.js | 9 + src/render/stub/index.js | 2 + src/render/stub/math.js | 15 -- src/ui/shareFollow.js | 247 +++++++++++++++--------- src/ui/shareFollow.test.mjs | 163 ++++++++++++++++ src/ui/shareLinks.test.mjs | 83 ++++++-- 19 files changed, 596 insertions(+), 143 deletions(-) create mode 100644 src/ui/shareFollow.test.mjs diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index c6071b1ab..aac2d9cb4 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -36,6 +36,12 @@ optional, so a renderer written before it still conforms: - `globe.isGlobeVisible()` (capability `globeVisibility`) reads back whether the globe surface is shown, for code that holds only the scene. +- `camera.followFrame()` (capability `followFrame`) reads the frame the eye + is placed in, as a column-major 4×4 matrix to ECEF: a follow's own frame + (east-north-up, or the orbit frame `autodetect` chose), a `lookAt` + target's east-north-up frame, or the identity. `setView` keeps that frame + while it places a world pose. A share link's follow offset is + re-expressed in it, satellites included. The renderer itself (`renderer.d.ts`) adds capture, pixel reads, settling, resize, context loss and `destroy`. `common.d.ts` holds the shared shapes diff --git a/src/geo/frames.js b/src/geo/frames.js index f0a94829b..8693582c5 100644 --- a/src/geo/frames.js +++ b/src/geo/frames.js @@ -1,19 +1,25 @@ /** * @module geo/frames * @description Rigid frames (unit axes and an origin, local to ECEF), the - * east-north-up frame at a point, and rotation about an axis. + * east-north-up frame at a point, rotation about an axis, and the offset a + * heading, pitch and range puts an eye at. */ import { geodeticSurfaceNormal } from './ellipsoid.js'; import { EPSILON14, + PI_OVER_TWO, add, + clamp, clone, cross, dot, equalsEpsilon, + negate, normalize, + scale, sub, vec, + zeroToTwoPi, } from './vector.js'; /** @@ -90,3 +96,20 @@ export function rotate(v, axis, angle) { v.z * c + k.z * s + axis.z * d * (1 - c), ); } + +/** + * The offset from a target a heading, pitch and range put the eye at, in + * the target's east-north-up frame: heading clockwise from north, pitch + * negative looking down (clamped to straight up or down), as `lookAt` takes + * them. + */ +export function offsetFromHeadingPitchRange(heading, pitch, range) { + const p = clamp(pitch, -PI_OVER_TWO, PI_OVER_TWO); + const h = zeroToTwoPi(heading) - PI_OVER_TWO; + const offset = rotate( + rotate(vec(1, 0, 0), vec(0, 1, 0), -p), + vec(0, 0, 1), + -h, + ); + return scale(negate(offset), range); +} diff --git a/src/render/cesium/camera.js b/src/render/cesium/camera.js index b5463699b..e4da681d5 100644 --- a/src/render/cesium/camera.js +++ b/src/render/cesium/camera.js @@ -83,13 +83,21 @@ const NO_FOLLOW_OFFSET = Object.freeze({ get: () => null, set() {} }); /** * @param {{scene: object, camera: object, report: (error: unknown) => void, - * widget?: object}} options `scene` gives `requestRender` and the - * `postUpdate` tick `changed` is measured on; `widget`, the Viewer or - * CesiumWidget, gives the entity tracking `follow` runs on (without it the - * camera cannot follow). + * widget?: object, capabilities?: ReadonlySet}} options `scene` + * gives `requestRender` and the `postUpdate` tick `changed` is measured + * on; `widget`, the Viewer or CesiumWidget, gives the entity tracking + * `follow` runs on (without it the camera cannot follow); + * `capabilities`, the renderer's, gates the optional members (a camera + * with none given has them all). * @returns {{port: import('../contract/camera').CameraPort, dispose: () => void}} */ -export function createCesiumCamera({ scene, camera, report, widget }) { +export function createCesiumCamera({ + scene, + camera, + report, + widget, + capabilities, +}) { const removers = []; // Camera events: Cesium's own moveStart and moveEnd (500 ms after the // last change, never while following), and `changed` measured per @@ -379,6 +387,11 @@ export function createCesiumCamera({ scene, camera, report, widget }) { }; }, }; + // Cesium keeps the eye in `camera.transform`: a tracked entity's frame, a + // `lookAt` target's, or the identity. + if (!capabilities || capabilities.has('followFrame')) + cameraPort.followFrame = () => + Float64Array.from(Cesium.Matrix4.toArray(camera.transform)); return { port: cameraPort, diff --git a/src/render/cesium/cameraPort.test.mjs b/src/render/cesium/cameraPort.test.mjs index 01e8524d6..4630ee558 100644 --- a/src/render/cesium/cameraPort.test.mjs +++ b/src/render/cesium/cameraPort.test.mjs @@ -254,3 +254,13 @@ test('setFov holds the vertical angle across resizes, and waits for a first one' assert.throws(() => port.setFov({ vertical: Math.PI }), RangeError); assert.throws(() => port.setFov({ vertical: NaN }), RangeError); }); + +test('followFrame is there only with its capability', () => { + const { scene, camera } = headlessCamera(); + scene.postUpdate = new Cesium.Event(); + const make = (capabilities) => + createCesiumCamera({ scene, camera, report: () => {}, capabilities }).port; + assert.equal(make(new Set()).followFrame, undefined); + assert.equal(typeof make(new Set(['followFrame'])).followFrame, 'function'); + assert.equal(typeof make(undefined).followFrame, 'function'); +}); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index 48865269f..a59debed3 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -26,6 +26,7 @@ export const CESIUM_CHECKS = new Set([ 'camera.controls.holds', 'camera.controls.settings', 'camera.follow', + 'camera.followFrame', 'camera.trace.flyTo with a duration of 0 completes inside the call', 'camera.trace.flyTo where the camera already is completes inside the call', 'camera.viewRectangle', diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index c414b5b0c..c8b98cec0 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -60,6 +60,7 @@ const GLOBE_CAPABILITIES = [ export function cesiumCapabilities(scene, only) { const all = [ 'models', + 'followFrame', ...GPU_ICON_CAPABILITIES, 'styles', 'bloom', @@ -305,7 +306,13 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) { }); const { port: draw, sets, tilesets } = drawPart; - const cameraPart = createCesiumCamera({ scene, camera, report, widget }); + const cameraPart = createCesiumCamera({ + scene, + camera, + report, + widget, + capabilities, + }); const cameraPort = cameraPart.port; const effectsPart = createCesiumEffects(scene, { capabilities, diff --git a/src/render/cesium/ports.test.mjs b/src/render/cesium/ports.test.mjs index 721518c0e..14bd66327 100644 --- a/src/render/cesium/ports.test.mjs +++ b/src/render/cesium/ports.test.mjs @@ -10,6 +10,7 @@ import { updateCameraChanged } from './internals.js'; test('capabilities follow what the scene supports', () => { const effects = [ + 'followFrame', 'columns', 'motionSegments', 'courseGlide', diff --git a/src/render/cesiumAllowList.json b/src/render/cesiumAllowList.json index 01d2ba903..6fef63f35 100644 --- a/src/render/cesiumAllowList.json +++ b/src/render/cesiumAllowList.json @@ -46,6 +46,5 @@ "src/services/groundSnap.js", "src/services/meshFloorSampler.js", "src/sky/starrySky.js", - "src/ui/applicationShell.js", - "src/ui/shareFollow.js" + "src/ui/applicationShell.js" ] diff --git a/src/render/conformance/checks/camera.js b/src/render/conformance/checks/camera.js index 202958f43..1e00a0904 100644 --- a/src/render/conformance/checks/camera.js +++ b/src/render/conformance/checks/camera.js @@ -447,6 +447,118 @@ export function cameraChecks() { r.destroy(); }, }, + { + id: 'camera.followFrame', + port: 'camera', + title: + 'the eye’s frame reads back: the world, a lookAt target’s east-north-up, a follow’s with the offset in it', + async run(h) { + const r = await fresh(h); + if (!r.capabilities.has('followFrame')) { + r.destroy(); + return { skip: 'no followFrame' }; + } + const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]; + const frameOf = () => { + const m = r.camera.followFrame(); + equal(m.length, 16, 'a 4×4 matrix'); + return { + m, + x: { x: m[0], y: m[1], z: m[2] }, + y: { x: m[4], y: m[5], z: m[6] }, + z: { x: m[8], y: m[9], z: m[10] }, + origin: { x: m[12], y: m[13], z: m[14] }, + }; + }; + // The eye's position in a frame, from its world position. + const inFrame = (f, p) => { + const d = { + x: p.x - f.origin.x, + y: p.y - f.origin.y, + z: p.z - f.origin.z, + }; + const dot = (a, b) => a.x * b.x + a.y * b.y + a.z * b.z; + return { x: dot(f.x, d), y: dot(f.y, d), z: dot(f.z, d) }; + }; + const world = frameOf(); + IDENTITY.forEach((v, i) => near(world.m[i], v, 1e-12, `world [${i}]`)); + + const target = h.toEcef({ lon: -97.74, lat: 30.27, height: 1000 }); + r.camera.lookAt(target, { + heading: 0, + pitch: -Math.PI / 2, + range: 900, + }); + const looked = frameOf(); + nearVec(looked.origin, target, 1e-6, 'lookAt origin'); + // Straight down from 900 m: the eye is 900 m up the frame's z. + nearVec( + inFrame(looked, r.camera.pose().position), + { x: 0, y: 0, z: 900 }, + 1e-6, + 'lookAt eye', + ); + const up = Math.hypot(target.x, target.y, target.z); + ok( + (looked.z.x * target.x + + looked.z.y * target.y + + looked.z.z * target.z) / + up > + 0.99, + 'its z is up', + ); + r.camera.release(); + + const start = r.frame.time(); + const mover = { + key: 'test:frame', + position: (t) => ({ + x: target.x + (t - start) * 0.2, + y: target.y, + z: target.z, + }), + frame: 'enu', + viewFrom: { x: 0, y: -800, z: 400 }, + }; + r.camera.follow(mover); + await h.frame(r); + r.frame.setTime(start + 5000); + await h.frame(r); + const followed = frameOf(); + nearVec( + followed.origin, + mover.position(r.frame.time()), + 1e-3, + 'the follow frame stands on the target', + ); + nearVec( + inFrame(followed, r.camera.pose().position), + r.camera.followOffset.get(), + 1e-3, + 'followOffset is the eye in it', + ); + // setView places a world pose and keeps the follow's frame. + const placed = { + x: followed.origin.x + 300, + y: followed.origin.y - 200, + z: followed.origin.z + 500, + }; + r.camera.setView({ + destination: placed, + orientation: { heading: 0.3, pitch: -0.5, roll: 0 }, + }); + frameOf().m.forEach((v, i) => + near(v, followed.m[i], 1e-6, `setView keeps the frame [${i}]`), + ); + nearVec(r.camera.pose().position, placed, 1e-6, 'setView places it'); + r.camera.follow(null); + const after = frameOf(); + IDENTITY.forEach((v, i) => + near(after.m[i], v, 1e-12, `world again [${i}]`), + ); + r.destroy(); + }, + }, { id: 'camera.rect', port: 'camera', diff --git a/src/render/contract/camera.d.ts b/src/render/contract/camera.d.ts index 63f7f6a74..dc48ebff4 100644 --- a/src/render/contract/camera.d.ts +++ b/src/render/contract/camera.d.ts @@ -244,6 +244,20 @@ export interface CameraPort { get(): Vec3 | null; set(offset: Vec3): void; }; + /** + * `followFrame`: the frame the eye is placed in now, as a column-major + * 4×4 matrix from that frame to ECEF (a rigid frame: unit axes, then the + * origin). Once a follow has framed the camera (`followFramed`) it is the + * follow's frame, whose origin is the target and in which `followOffset` + * is the eye: east-north-up for an `enu` follow, the renderer's own orbit + * frame for `autodetect`; until then it is whatever frame the eye was in + * before. Under `lookAt` it is the target's east-north-up frame; in the + * world frame, the identity. A follow's frame moves with its target, so a + * reading is valid only for the tick it is read in. `setView` places a + * world pose and keeps this frame, so code can re-express an offset in + * the follow's own frame, whichever frame that is, and place the eye there. + */ + followFrame?(): Float64Array; readonly controls: CameraControls; on(event: CameraEvent, cb: () => void, options?: { threshold?: number }): Off; /** Runs before each camera command, so an owner can yield to another. */ diff --git a/src/render/contract/common.d.ts b/src/render/contract/common.d.ts index 50faf956e..2e8dab2e2 100644 --- a/src/render/contract/common.d.ts +++ b/src/render/contract/common.d.ts @@ -208,5 +208,7 @@ export type Capability = | 'followAutodetect' /** Reading back whether the globe surface is shown (`globe.isGlobeVisible`). */ | 'globeVisibility' + /** Reading the frame the eye is placed in (`camera.followFrame`). */ + | 'followFrame' /** A built-in quality benchmark. */ | 'benchmark'; diff --git a/src/render/contract/contract.test.mjs b/src/render/contract/contract.test.mjs index fc887c78b..015f191d8 100644 --- a/src/render/contract/contract.test.mjs +++ b/src/render/contract/contract.test.mjs @@ -174,6 +174,12 @@ test('a draw set’s events: ready with the id, loadFailed with the id and why', }); }); +test('members added to version 0 later are optional, each behind its capability', () => { + // A renderer written before an addition still conforms without it. + assert.equal(PORTS.globe.isGlobeVisible, 'globeVisibility'); + assert.equal(PORTS.camera.followFrame, 'followFrame'); +}); + test('the shape check names what is missing and what a capability does not allow', () => { assert.deepEqual(checkRendererShape(null), ['renderer is not an object']); assert.deepEqual(checkRendererShape({}), [ diff --git a/src/render/contract/index.js b/src/render/contract/index.js index 25e5f8542..15be4b58b 100644 --- a/src/render/contract/index.js +++ b/src/render/contract/index.js @@ -47,6 +47,7 @@ export const CAPABILITIES = Object.freeze([ 'sharpen', 'followAutodetect', 'globeVisibility', + 'followFrame', 'benchmark', ]); @@ -173,8 +174,8 @@ export const PORTS = deepFreeze({ ['agents', 'agents'], ['orbits', 'orbits'], ]), - camera: Object.fromEntries( - required( + camera: Object.fromEntries([ + ...required( 'pose', 'setView', 'setFov', @@ -214,7 +215,8 @@ export const PORTS = deepFreeze({ 'onCommand', 'matrices', ), - ), + ['followFrame', 'followFrame'], + ]), query: Object.fromEntries( required( 'pick', diff --git a/src/render/stub/camera.js b/src/render/stub/camera.js index bf183e4b1..7d37ae3f9 100644 --- a/src/render/stub/camera.js +++ b/src/render/stub/camera.js @@ -867,6 +867,15 @@ export function createStubCamera({ near, }), holds: () => [...holds.values()], + /** The frame the eye is in, column-major from it to the world. */ + eyeFrame: () => + Float64Array.of( + ...[frame.x, frame.y, frame.z].flatMap((a) => [a.x, a.y, a.z, 0]), + frame.origin.x, + frame.origin.y, + frame.origin.z, + 1, + ), setViewRectangle(fn) { port.viewRectangle = fn; }, diff --git a/src/render/stub/index.js b/src/render/stub/index.js index f83ce0005..b5676490e 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -174,6 +174,8 @@ export function createStubRenderer(options = {}) { drawnPosition: (ref, aheadMs) => drawnPosition(ref, aheadMs), }); camera.setViewRectangle(viewRectangle); + if (capabilities.has('followFrame')) + camera.port.followFrame = camera.eyeFrame; camera.port.setView({ destination: { lon: -97.7431, lat: 30.2672, height: 15000000 }, }); diff --git a/src/render/stub/math.js b/src/render/stub/math.js index b879b551b..748348474 100644 --- a/src/render/stub/math.js +++ b/src/render/stub/math.js @@ -11,11 +11,8 @@ import { PI_OVER_TWO, TWO_PI, acosClamped, - clamp, equalsEpsilon, - negate, rotate, - scale, vec, zeroToTwoPi, } from '../../geo/index.js'; @@ -63,16 +60,4 @@ export function rollOf(direction, up, right) { return zeroToTwoPi(Math.atan2(-right.z, up.z) + TWO_PI); } -/** The local offset a heading, pitch and range puts the eye at. */ -export function offsetFromHeadingPitchRange(heading, pitch, range) { - const p = clamp(pitch, -PI_OVER_TWO, PI_OVER_TWO); - const h = zeroToTwoPi(heading) - PI_OVER_TWO; - const offset = rotate( - rotate(vec(1, 0, 0), vec(0, 1, 0), -p), - vec(0, 0, 1), - -h, - ); - return scale(negate(offset), range); -} - export { EPSILON10 }; diff --git a/src/ui/shareFollow.js b/src/ui/shareFollow.js index 798e249d9..7a77d6724 100644 --- a/src/ui/shareFollow.js +++ b/src/ui/shareFollow.js @@ -1,6 +1,26 @@ -import * as Cesium from 'cesium'; -import { findCamera } from '../render/rendererOf.js'; +import { findCamera, findFrame } from '../render/rendererOf.js'; import { followedOf, followedPosition } from '../data/followed.js'; +import { toLonLatH } from '../geo/ellipsoid.js'; +import { + eastNorthUp, + framePoint, + frameVector, + inverseFramePoint, + inverseFrameVector, + isIdentity, + offsetFromHeadingPitchRange, +} from '../geo/frames.js'; +import { + add, + cross, + dot, + magnitude, + negate, + normalize, + scale, + sub, + vec, +} from '../geo/vector.js'; import { SHARE_VIEW_ENTITY_KINDS, followOffsetFromEnu, @@ -17,24 +37,93 @@ const KIND_BY_LAYER = new Map( SHARE_VIEW_ENTITY_KINDS.map((entry) => [entry.layerId, entry.kind]), ); const MAX_FRAMES = 120; +const EPSILON10 = 1e-10; -/** Where `followed` is shown now, as a Cesium position, or null. */ +/** Where `followed` is shown now, as an ECEF position, or null. */ function shownAt(viewer, followed) { const p = followedPosition(viewer, followed); - return p ? new Cesium.Cartesian3(p.x, p.y, p.z) : null; + return p ? vec(p.x, p.y, p.z) : null; } /** `position`'s local east/north/up offset from `origin`, in metres. */ function enuOffset(origin, position) { - const frame = Cesium.Transforms.eastNorthUpToFixedFrame(origin); - const local = Cesium.Matrix4.multiplyByPoint( - Cesium.Matrix4.inverseTransformation(frame, new Cesium.Matrix4()), - position, - new Cesium.Cartesian3(), - ); + const local = inverseFramePoint(eastNorthUp(origin), position); return { east: local.x, north: local.y, up: local.z }; } +/** A column-major 4×4 frame-to-ECEF matrix as a frame of axes and origin. */ +const frameOfMatrix = (m) => ({ + x: vec(m[0], m[1], m[2]), + y: vec(m[4], m[5], m[6]), + z: vec(m[8], m[9], m[10]), + origin: vec(m[12], m[13], m[14]), +}); + +/** The frame the camera's eye is in now, or null when it cannot say. */ +function eyeFrame(camera) { + const matrix = camera?.followFrame?.(); + return matrix ? frameOfMatrix(matrix) : null; +} + +/** The angle between two vectors, as the default renderer measures it. */ +function angleBetween(a, b) { + const unitA = normalize(a); + const unitB = normalize(b); + return Math.atan2(magnitude(cross(unitA, unitB)), dot(unitA, unitB)); +} + +/** + * The eye at `offset` in `frame`, looking at the frame's origin with the + * frame's z as up, in the world: where a look at a frame's origin from an + * offset puts it. + */ +function lookingAtOrigin(frame, offset) { + const direction = normalize(negate(offset)); + let right = cross(direction, vec(0, 0, 1)); + if (dot(right, right) < EPSILON10) right = vec(1, 0, 0); + right = normalize(right); + const up = normalize(cross(right, direction)); + return { + position: framePoint(frame, offset), + direction: frameVector(frame, direction), + up: frameVector(frame, up), + }; +} + +/** + * The heading, pitch and roll that turn the east-north-up frame at + * `position` onto `direction` and `up`, exactly: straight down included, + * where a renderer reading angles off a direction rounds the roll away. + */ +function anglesAt(position, direction, up) { + const enu = eastNorthUp(position); + const d = inverseFrameVector(enu, direction); + const u = inverseFrameVector(enu, up); + // From both components: near straight down `asin` would lose precision. + const pitch = Math.atan2(d.z, Math.hypot(d.x, d.y)); + // Straight up or down, any heading will do: the roll takes the rest. + const a = Math.abs(d.x) + Math.abs(d.y) > 0 ? Math.atan2(d.y, d.x) : 0; + const across = vec(-Math.sin(a), Math.cos(a), 0); + const lifted = vec( + Math.cos(a) * -Math.sin(pitch), + Math.sin(a) * -Math.sin(pitch), + Math.cos(pitch), + ); + return { + heading: Math.PI / 2 - a, + pitch, + roll: Math.atan2(-dot(u, across), dot(u, lifted)), + }; +} + +/** Put the eye at a world pose, keeping the frame the camera is in. */ +function placeEye(camera, eye) { + camera.setView({ + destination: eye.position, + orientation: anglesAt(eye.position, eye.direction, eye.up), + }); +} + /** * The entity the camera follows as `{ kind, id, offset, lastKnown }`, with * the camera's offset from it and its displayed position as of `nowMs`; null @@ -43,7 +132,7 @@ function enuOffset(origin, position) { * keeps its own camera. */ export function readShareFollowSubject({ viewer, nowMs = Date.now() }) { - const cameraPosition = viewer?.camera?.positionWC; + const cameraPosition = viewer ? findCamera(viewer)?.pose().position : null; if (!cameraPosition) return null; const followed = followedOf(viewer); const trackedId = String(followed?.key || ''); @@ -54,15 +143,15 @@ export function readShareFollowSubject({ viewer, nowMs = Date.now() }) { const target = kind ? shownAt(viewer, followed) : null; if (!kind || !id || !target) return null; const offset = followOffsetFromEnu(enuOffset(target, cameraPosition)); - const fix = Cesium.Cartographic.fromCartesian(target); + const fix = toLonLatH(target); if (!offset || !fix) return null; return { kind, id, offset, lastKnown: { - lat: Cesium.Math.toDegrees(fix.latitude), - lon: Cesium.Math.toDegrees(fix.longitude), + lat: fix.lat, + lon: fix.lon, alt: fix.height, observedAtMs: nowMs, }, @@ -74,71 +163,55 @@ const MAX_TURN_PER_FRAME = Math.PI / 3; /** * Put the camera at a shared follow offset from `followed` (what - * `followedOf` gave) once following it has framed the camera. Cesium keeps the offset afterwards, as it keeps one + * `followedOf` gave) once following it has framed the camera. The renderer keeps the offset afterwards, as it keeps one * the user orbits to. The camera swings round the entity at most 60° a frame: * the follow's own guard treats a jump to the far side as the camera crossing * through the entity and puts it back. Returns a disposer. */ export function applyShareFollowOffset(viewer, followed, offset) { - if (!viewer?.scene?.preUpdate || !followed || !(offset?.range > 0)) - return () => {}; + const frames = viewer ? findFrame(viewer) : null; + if (!frames || !followed || !(offset?.range > 0)) return () => {}; const local = followOffsetToEnu(offset); - let frames = 0; + let count = 0; let remove = null; const stop = () => { remove?.(); remove = null; }; - remove = viewer.scene.preUpdate.addEventListener(() => { - if (viewer.isDestroyed?.() || followedOf(viewer) !== followed) { + remove = frames.on('preUpdate', () => { + if (followedOf(viewer) !== followed) { stop(); return; } - frames += 1; - const camera = viewer.camera; + count += 1; // Let the follow frame the camera first (its first frame), then move it. - const port = findCamera(viewer); + const camera = findCamera(viewer); + const frame = eyeFrame(camera); + const ported = camera?.followed === followed; const framed = - frames > 1 && - (port?.followed === followed - ? port.followFramed - : !Cesium.Matrix4.equals(camera.transform, Cesium.Matrix4.IDENTITY)); - const target = framed ? shownAt(viewer, followed) : null; + count > 1 && + (ported ? camera.followFramed : frame !== null && !isIdentity(frame)); + const target = framed && frame ? shownAt(viewer, followed) : null; if (!target) { - if (frames >= MAX_FRAMES) stop(); + if (count >= MAX_FRAMES) stop(); return; } // The offset is east/north/up at the entity; the follow's own frame may // differ, so place the camera in world space and re-express it there. - const world = Cesium.Matrix4.multiplyByPoint( - Cesium.Transforms.eastNorthUpToFixedFrame(target), - new Cesium.Cartesian3(local.east, local.north, local.up), - new Cesium.Cartesian3(), + const world = framePoint( + eastNorthUp(target), + vec(local.east, local.north, local.up), ); - const goal = Cesium.Matrix4.multiplyByPoint( - Cesium.Matrix4.inverseTransformation( - camera.transform, - new Cesium.Matrix4(), - ), - world, - new Cesium.Cartesian3(), - ); - const from = Cesium.Cartesian3.clone( - camera.position, - new Cesium.Cartesian3(), - ); - const angle = - Cesium.Cartesian3.magnitude(from) > 0 - ? Cesium.Cartesian3.angleBetween(from, goal) - : 0; + const goal = inverseFramePoint(frame, world); + const from = + (ported && camera.followOffset.get()) || + inverseFramePoint(frame, camera.pose().position); + const angle = magnitude(from) > 0 ? angleBetween(from, goal) : 0; const done = !(angle > MAX_TURN_PER_FRAME); const next = done ? goal : turnToward(from, goal, MAX_TURN_PER_FRAME); // Through the port when it follows: its close-range guard keeps the eye. - if (port?.followed === followed) port.followOffset.set(next); - else { - camera.lookAtTransform(camera.transform, next); - viewer.scene.requestRender?.(); - } + if (ported) camera.followOffset.set(next); + else placeEye(camera, lookingAtOrigin(frame, next)); if (done) stop(); }); return stop; @@ -149,65 +222,47 @@ export function applyShareFollowOffset(viewer, followed, offset) { * fraction of the way: one frame of the swing round the entity. */ function turnToward(from, to, step) { - const angle = Cesium.Cartesian3.angleBetween(from, to); - const unitFrom = Cesium.Cartesian3.normalize(from, new Cesium.Cartesian3()); + const angle = angleBetween(from, to); + const unitFrom = normalize(from); // The direction perpendicular to `from` in the plane toward `to` (or any // perpendicular when they are opposite). - let toward = Cesium.Cartesian3.subtract( - Cesium.Cartesian3.normalize(to, new Cesium.Cartesian3()), - Cesium.Cartesian3.multiplyByScalar( + let toward = sub(normalize(to), scale(unitFrom, Math.cos(angle))); + if (magnitude(toward) < 1e-9) + toward = cross( unitFrom, - Math.cos(angle), - new Cesium.Cartesian3(), - ), - new Cesium.Cartesian3(), - ); - if (Cesium.Cartesian3.magnitude(toward) < 1e-9) - toward = Cesium.Cartesian3.cross( - unitFrom, - Math.abs(unitFrom.z) < 0.9 - ? Cesium.Cartesian3.UNIT_Z - : Cesium.Cartesian3.UNIT_X, - new Cesium.Cartesian3(), + Math.abs(unitFrom.z) < 0.9 ? vec(0, 0, 1) : vec(1, 0, 0), ); - Cesium.Cartesian3.normalize(toward, toward); + toward = normalize(toward); const length = - Cesium.Cartesian3.magnitude(from) + - (Cesium.Cartesian3.magnitude(to) - Cesium.Cartesian3.magnitude(from)) * - (step / angle); - const direction = Cesium.Cartesian3.add( - Cesium.Cartesian3.multiplyByScalar( - unitFrom, - Math.cos(step), - new Cesium.Cartesian3(), - ), - Cesium.Cartesian3.multiplyByScalar( - toward, - Math.sin(step), - new Cesium.Cartesian3(), - ), - new Cesium.Cartesian3(), + magnitude(from) + (magnitude(to) - magnitude(from)) * (step / angle); + const direction = add( + scale(unitFrom, Math.cos(step)), + scale(toward, Math.sin(step)), ); - return Cesium.Cartesian3.multiplyByScalar(direction, length, direction); + return scale(direction, length); } /** * Put the eye of a camera that follows something at `offset` (heading, * pitch, range) from `target`, keeping the follow's own reference frame * (a satellite's included): the follow's next update carries the new offset - * along with the target. Returns true. + * along with the target. False when the camera cannot say which frame it + * is in. * @param {object} viewer * @param {{x: number, y: number, z: number}} target * @param {{heading: number, pitch: number, range: number}} offset */ export function placeFollowEye(viewer, target, offset) { - const camera = viewer.camera; - const trackedTransform = Cesium.Matrix4.clone(camera.transform); - camera.lookAt( - new Cesium.Cartesian3(target.x, target.y, target.z), - new Cesium.HeadingPitchRange(offset.heading, offset.pitch, offset.range), + const camera = findCamera(viewer); + if (!eyeFrame(camera)) return false; + // Where looking at `target` from `offset` in its east-north-up frame puts + // the eye, placed in the world while the camera stays in its frame. + placeEye( + camera, + lookingAtOrigin( + eastNorthUp(vec(target.x, target.y, target.z)), + offsetFromHeadingPitchRange(offset.heading, offset.pitch, offset.range), + ), ); - camera.lookAtTransform(trackedTransform); - viewer.scene?.requestRender?.(); return true; } diff --git a/src/ui/shareFollow.test.mjs b/src/ui/shareFollow.test.mjs new file mode 100644 index 000000000..147fc3b02 --- /dev/null +++ b/src/ui/shareFollow.test.mjs @@ -0,0 +1,163 @@ +// The share follow in a follow's own frame: a satellite's is not +// east-north-up, and the eye placed in it must land where Cesium's own +// calls put it. +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import { applyShareFollowOffset, placeFollowEye } from './shareFollow.js'; +import { followOffsetToEnu } from '../share/viewCodec.js'; +import { withEntityRecord } from '../data/entityRecords.js'; +import { followedOf } from '../data/followed.js'; +import { bindFakeCesiumCamera } from '../testSupport/fakeCameraPort.mjs'; +import { findCamera } from '../render/rendererOf.js'; + +function realCamera() { + const scene = { + canvas: { clientWidth: 1200, clientHeight: 800, width: 1200, height: 800 }, + drawingBufferWidth: 1200, + drawingBufferHeight: 800, + mapProjection: new Cesium.GeographicProjection(Cesium.Ellipsoid.WGS84), + globe: { ellipsoid: Cesium.Ellipsoid.WGS84 }, + mapMode2D: Cesium.MapMode2D.INFINITE_SCROLL, + mode: Cesium.SceneMode.SCENE3D, + pixelRatio: 1, + preUpdate: new Cesium.Event(), + requestRender() {}, + }; + const camera = new Cesium.Camera(scene); + scene.camera = camera; + return { camera, scene }; +} + +const TARGET = Cesium.Cartesian3.fromDegrees(-97, 30, 400_000); +const START = new Cesium.Cartesian3(900, -1500, 700); + +/** + * An orbit frame at the target, turned away from east-north-up as a + * satellite's frame from its motion is. + */ +function orbitFrame() { + const enu = Cesium.Transforms.eastNorthUpToFixedFrame(TARGET); + const turn = Cesium.Matrix3.multiply( + Cesium.Matrix3.fromRotationZ(0.7), + Cesium.Matrix3.fromRotationX(0.3), + new Cesium.Matrix3(), + ); + return Cesium.Matrix4.multiply( + enu, + Cesium.Matrix4.fromRotation(turn), + new Cesium.Matrix4(), + ); +} + +/** A real camera following in the orbit frame, its viewer bound to ports. */ +function following(start = START) { + const { camera, scene } = realCamera(); + camera.lookAtTransform(orbitFrame(), start); + const viewer = { + camera, + scene, + clock: { currentTime: Cesium.JulianDate.now() }, + trackedEntity: withEntityRecord( + {}, + { trackedId: 'satellites:25544', displayPosition: () => TARGET }, + ), + }; + bindFakeCesiumCamera(viewer, { + frame: { + on: (phase, cb) => + phase === 'preUpdate' ? scene.preUpdate.addEventListener(cb) : () => {}, + }, + }); + return viewer; +} + +function samePose(actual, expected) { + for (const key of ['positionWC', 'directionWC', 'upWC']) + assert.ok( + Cesium.Cartesian3.equalsEpsilon( + actual[key], + expected[key], + 0, + key === 'positionWC' ? 1e-6 : 1e-9, + ), + `${key}: ${actual[key]} vs ${expected[key]}`, + ); + assert.ok( + Cesium.Matrix4.equalsEpsilon(actual.transform, expected.transform, 1e-9), + 'the camera stays in the follow frame', + ); +} + +const snapshot = (camera) => ({ + positionWC: Cesium.Cartesian3.clone(camera.positionWC), + directionWC: Cesium.Cartesian3.clone(camera.directionWC), + upWC: Cesium.Cartesian3.clone(camera.upWC), + transform: Cesium.Matrix4.clone(camera.transform), +}); + +for (const [label, offset] of [ + ['oblique', { heading: 0.4, pitch: -0.6, range: 2500 }], + // The top-down view: angles read off a direction would lose its roll. + ['straight down', { heading: 0, pitch: -89 * (Math.PI / 180), range: 2500 }], +]) + test(`placing the follow eye keeps an orbit frame and lands where lookAt puts it (${label})`, () => { + // What Cesium's own calls did: look at the target, then re-enter the + // follow's frame keeping the world pose. + const { camera: reference } = realCamera(); + reference.lookAtTransform(orbitFrame(), START); + const tracked = Cesium.Matrix4.clone(reference.transform); + reference.lookAt( + TARGET, + new Cesium.HeadingPitchRange(offset.heading, offset.pitch, offset.range), + ); + reference.lookAtTransform(tracked); + + const viewer = following(); + assert.equal(placeFollowEye(viewer, TARGET, offset), true); + samePose(snapshot(viewer.camera), snapshot(reference)); + }); + +for (const offset of [ + { range: 1800, heading: 20, pitch: -30 }, + { range: 1800, heading: 20, pitch: -88 }, +]) + test(`a shared offset is re-expressed in an orbit frame as Cesium’s own calls did (pitch ${offset.pitch})`, () => { + const local = followOffsetToEnu(offset); + // What Cesium's own calls did in one frame: the goal in the follow frame, + // and the eye looking at its origin from there. The eye starts a little + // off the goal, so one frame's turn reaches it. + const world = Cesium.Matrix4.multiplyByPoint( + Cesium.Transforms.eastNorthUpToFixedFrame(TARGET), + new Cesium.Cartesian3(local.east, local.north, local.up), + new Cesium.Cartesian3(), + ); + const goal = Cesium.Matrix4.multiplyByPoint( + Cesium.Matrix4.inverseTransformation(orbitFrame(), new Cesium.Matrix4()), + world, + new Cesium.Cartesian3(), + ); + const start = new Cesium.Cartesian3(goal.x * 1.2, goal.y, goal.z * 0.8); + const { camera: reference } = realCamera(); + reference.lookAtTransform(orbitFrame(), start); + reference.lookAtTransform(reference.transform, goal); + + const viewer = following(start); + applyShareFollowOffset(viewer, followedOf(viewer), offset); + viewer.scene.preUpdate.raiseEvent(); + viewer.scene.preUpdate.raiseEvent(); + assert.equal(viewer.scene.preUpdate.numberOfListeners, 0, 'it arrives'); + samePose(snapshot(viewer.camera), snapshot(reference)); + }); + +test('placing the follow eye does nothing on a camera that cannot say its frame', () => { + const viewer = following(); + const port = findCamera(viewer); + Object.defineProperty(port, 'followFrame', { value: undefined }); + const before = snapshot(viewer.camera); + assert.equal( + placeFollowEye(viewer, TARGET, { heading: 0, pitch: -0.5, range: 900 }), + false, + ); + samePose(snapshot(viewer.camera), before); +}); diff --git a/src/ui/shareLinks.test.mjs b/src/ui/shareLinks.test.mjs index d2c9e5dfc..70194d47b 100644 --- a/src/ui/shareLinks.test.mjs +++ b/src/ui/shareLinks.test.mjs @@ -123,12 +123,53 @@ function fakeViewer() { const flush = () => new Promise((resolve) => setImmediate(resolve)); +/** A frame port whose preUpdate is the fake viewer's scene's, read when subscribed. */ +const preUpdateFrame = (viewer) => ({ + on: (phase, cb) => + phase === 'preUpdate' + ? (viewer.scene?.preUpdate?.addEventListener(cb) ?? (() => {})) + : () => {}, +}); + +/** + * A Cesium-shaped camera in `transform` with its eye at `position` there: + * a view set on it (a world pose) lands in that frame, and each eye it is + * given is recorded in `looks`, in the frame. + */ +function cameraInFrame(transform, position, looks) { + return { + transform, + position, + get positionWC() { + return Cesium.Matrix4.multiplyByPoint( + this.transform, + this.position, + new Cesium.Cartesian3(), + ); + }, + setView({ destination }) { + const local = Cesium.Matrix4.multiplyByPoint( + Cesium.Matrix4.inverseTransformation( + this.transform, + new Cesium.Matrix4(), + ), + destination, + new Cesium.Cartesian3(), + ); + looks.push(local); + this.position = local; + }, + }; +} + /** A ShareRestoration over a real ShareLinkManager, as the shell wires them. */ function openPage(t, href, { managerOptions = {}, tracking = null } = {}) { const page = installPage(t, href); const clock = installManualTimers(t); const viewer = fakeViewer(); const restores = []; + // Bound first with a frame port: the share follow runs on its preUpdate. + bindFakeCesiumCamera(viewer, { frame: preUpdateFrame(viewer) }); const manager = new ShareLinkManager(bindFakeCesiumCamera(viewer), { onRestore: async (state) => restores.push(state), isNavigationCurrent: () => true, @@ -272,15 +313,16 @@ test('a thing view turns its layer on, follows by id and frames the shared offse }, isDestroyed: () => false, }); - Object.assign(page.viewer.camera, { - transform: Cesium.Transforms.eastNorthUpToFixedFrame(target), - // The app's own follow framing: south of the aircraft and above it. - position: new Cesium.Cartesian3(0, -4800, 3300), - lookAtTransform(transform, offset) { - looks.push(offset); - this.position = Cesium.Cartesian3.clone(offset); - }, - }); + // The app's own follow framing: south of the aircraft and above it. + const followCamera = cameraInFrame( + Cesium.Transforms.eastNorthUpToFixedFrame(target), + new Cesium.Cartesian3(0, -4800, 3300), + looks, + ); + Object.defineProperties( + page.viewer.camera, + Object.getOwnPropertyDescriptors(followCamera), + ); entity = withEntityRecord({}, { trackedId: 'flights:a1b2c3', displayPosition: () => target }); const parsed = page.manager._parseShareCode(aircraftCode()); @@ -302,7 +344,8 @@ test('a thing view turns its layer on, follows by id and frames the shared offse Math.abs(Cesium.Math.toDegrees(destination.longitude) - camera.lon) < 1e-3, ); // Once followed, the camera takes the shared offset after the follow's - // own first frame. + // own first frame. (The restore's own views do not count.) + looks.length = 0; assert.equal(listeners.length, 1); listeners[0](); assert.equal(looks.length, 0); @@ -449,11 +492,11 @@ test('the followed entity is read in the share format, and its offset round-trip new Cesium.Cartesian3(local.east, local.north, local.up), new Cesium.Cartesian3(), ); - const viewer = { + const viewer = bindFakeCesiumCamera({ camera: { positionWC: cameraPosition }, clock: { currentTime: Cesium.JulianDate.now() }, trackedEntity: withEntityRecord({}, { trackedId: 'military:ae1234', displayPosition: () => target }), - }; + }); const subject = readShareFollowSubject({ viewer, nowMs: NOW_MS }); assert.equal(subject.kind, 'military_aircraft'); assert.equal(subject.id, 'ae1234'); @@ -484,15 +527,13 @@ test('a shared offset on the far side swings round, never jumping through the en }, }, trackedEntity: entity, - camera: { - transform: Cesium.Transforms.eastNorthUpToFixedFrame(target), - position: new Cesium.Cartesian3(0, -4800, 3300), - lookAtTransform(transform, offset) { - looks.push(Cesium.Cartesian3.clone(offset)); - this.position = Cesium.Cartesian3.clone(offset); - }, - }, + camera: cameraInFrame( + Cesium.Transforms.eastNorthUpToFixedFrame(target), + new Cesium.Cartesian3(0, -4800, 3300), + looks, + ), }; + bindFakeCesiumCamera(viewer, { frame: preUpdateFrame(viewer) }); // Looking south at the nose: the opposite side of the app's framing. const offset = { range: 5800, heading: 180, pitch: -35 }; applyShareFollowOffset(viewer, followedOf(viewer), offset); @@ -525,7 +566,9 @@ test('applying a follow offset gives up when the follow ends', () => { }, }, trackedEntity: null, + camera: {}, }; + bindFakeCesiumCamera(viewer, { frame: preUpdateFrame(viewer) }); applyShareFollowOffset(viewer, {}, OFFSET); listeners[0](); assert.equal(listeners.length, 0);