From 0a0645e28e7ab56081dc22ba3e1125a02a410f09 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Tue, 10 Nov 2026 14:47:05 -0800 Subject: [PATCH] Answer an unmoved camera's pose from the last read Cesium measures heading, pitch and roll by moving the camera into the eye's east-north-up frame and back, twice each, and a frame reads the pose many times over (the range ring's rim check reads it every frame). The Cesium camera port keys the last pose on everything it is read from: eye, axes, transform, frustum and mode, and answers from it while they hold, with objects of the caller's own. --- src/render/cesium/camera.js | 128 ++++++++++++++++++++------ src/render/cesium/cameraPort.test.mjs | 83 +++++++++++++++++ 2 files changed, 183 insertions(+), 28 deletions(-) diff --git a/src/render/cesium/camera.js b/src/render/cesium/camera.js index e1558c9c5..d8347946f 100644 --- a/src/render/cesium/camera.js +++ b/src/render/cesium/camera.js @@ -369,36 +369,108 @@ export function createCesiumCamera({ }; }, pose() { - const v = (c) => ({ x: c.x, y: c.y, z: c.z }); - // Cesium has no cartographic position for an eye at the earth's - // centre; the pose then says so with NaN. - const carto = camera.positionCartographic ?? { - longitude: NaN, - latitude: NaN, - height: NaN, - }; - return { - lon: Cesium.Math.toDegrees(carto.longitude), - lat: Cesium.Math.toDegrees(carto.latitude), - position: v(camera.positionWC), - direction: v(camera.directionWC), - up: v(camera.upWC), - right: v(camera.rightWC), - heading: camera.heading, - pitch: camera.pitch, - roll: camera.roll, - height: carto.height, - fovy: camera.frustum.fovy, - aspectRatio: camera.frustum.aspectRatio, - near: camera.frustum.near, - far: camera.frustum.far, - frameIsIdentity: Cesium.Matrix4.equals( - camera.transform, - Cesium.Matrix4.IDENTITY, - ), - }; + // An unmoved camera answers from the pose last read: Cesium measures + // each of heading, pitch and roll by moving the camera into the + // eye's east-north-up frame and back, and a frame reads the pose + // many times over. Each caller gets objects of its own. + if (!poseKeyHolds() || !poseMemo) { + poseMemo = readPose(); + // Measuring heading, pitch and roll moves the camera there and + // back, which can change its last bits: keyed as it is left. + poseKeyHolds(); + } + return copyPose(poseMemo); }, }; + // The camera as the memoised pose was read: eye, axes, transform, + // frustum and mode, compared value for value. + const poseKey = new Float64Array(37); + let poseMemo = null; + /** + * Whether the camera is as `poseKey` holds, writing it as the camera now + * is: everything a pose is read from. + */ + function poseKeyHolds() { + const p = camera.positionWC; + const d = camera.directionWC; + const u = camera.upWC; + const r = camera.rightWC; + const f = camera.frustum; + const t = camera.transform; + let same = true; + let at = 0; + const put = (value) => { + if (!Object.is(poseKey[at], value)) { + same = false; + poseKey[at] = value; + } + at += 1; + }; + put(p.x); + put(p.y); + put(p.z); + put(d.x); + put(d.y); + put(d.z); + put(u.x); + put(u.y); + put(u.z); + // Cesium lets right drift a little from direction × up. + put(r.x); + put(r.y); + put(r.z); + put(f.fovy ?? NaN); + put(f.aspectRatio ?? NaN); + put(f.near ?? NaN); + put(f.far ?? NaN); + // A 2D camera's height is its off-centre frustum's width. + put(f.left ?? NaN); + put(f.right ?? NaN); + put(f.top ?? NaN); + put(f.bottom ?? NaN); + put(scene.mode ?? NaN); + for (let i = 0; i < 16; i++) put(t[i]); + return same; + } + /** A pose read from Cesium's camera (after `poseKeyHolds` keyed it). */ + function readPose() { + const v = (c) => ({ x: c.x, y: c.y, z: c.z }); + // Cesium has no cartographic position for an eye at the earth's + // centre; the pose then says so with NaN. + const carto = camera.positionCartographic ?? { + longitude: NaN, + latitude: NaN, + height: NaN, + }; + return { + lon: Cesium.Math.toDegrees(carto.longitude), + lat: Cesium.Math.toDegrees(carto.latitude), + position: v(camera.positionWC), + direction: v(camera.directionWC), + up: v(camera.upWC), + right: v(camera.rightWC), + heading: camera.heading, + pitch: camera.pitch, + roll: camera.roll, + height: carto.height, + fovy: camera.frustum.fovy, + aspectRatio: camera.frustum.aspectRatio, + near: camera.frustum.near, + far: camera.frustum.far, + frameIsIdentity: Cesium.Matrix4.equals( + camera.transform, + Cesium.Matrix4.IDENTITY, + ), + }; + } + /** A pose of the caller's own, its vectors too. */ + const copyPose = (pose) => ({ + ...pose, + position: { ...pose.position }, + direction: { ...pose.direction }, + up: { ...pose.up }, + right: { ...pose.right }, + }); // Cesium keeps the eye in `camera.transform`: a tracked entity's frame, a // `lookAt` target's, or the identity. if (!capabilities || capabilities.has('followFrame')) diff --git a/src/render/cesium/cameraPort.test.mjs b/src/render/cesium/cameraPort.test.mjs index 92fd34773..1902dc137 100644 --- a/src/render/cesium/cameraPort.test.mjs +++ b/src/render/cesium/cameraPort.test.mjs @@ -305,6 +305,89 @@ test('setFov holds the vertical angle across resizes, and waits for a first one' assert.throws(() => port.setFov({ vertical: NaN }), RangeError); }); +test('an unmoved camera answers its pose from the last read; any change reads it anew', () => { + const { camera, port } = headlessPort(); + port.setView({ + destination: { lon: 10, lat: 20, height: 5e5 }, + orientation: { heading: 0.3, pitch: -0.7, roll: 0 }, + }); + // Read as Cesium answers now, without the memo. (Cesium measures heading, + // pitch and roll by moving the camera there and back, which can change + // its last bits, so the two are compared to within a whisker.) + const fresh = () => { + const carto = camera.positionCartographic; + return { + lon: Cesium.Math.toDegrees(carto.longitude), + lat: Cesium.Math.toDegrees(carto.latitude), + height: carto.height, + heading: camera.heading, + pitch: camera.pitch, + roll: camera.roll, + fovy: camera.frustum.fovy, + x: camera.positionWC.x, + }; + }; + const near = (pose) => { + const want = fresh(); + const got = { ...pose, x: pose.position.x }; + for (const [name, value] of Object.entries(want)) + assert.ok( + Math.abs(got[name] - value) < 1e-6, + `${name}: ${got[name]} vs ${value}`, + ); + }; + // Counts Cesium's heading reads: an answer from the memo makes none. + let reads = 0; + const heading = Object.getOwnPropertyDescriptor( + Cesium.Camera.prototype, + 'heading', + ); + Object.defineProperty(camera, 'heading', { + get() { + reads += 1; + return heading.get.call(this); + }, + }); + const a = port.pose(); + reads = 0; + // A caller's own objects: changing them changes no later pose. + a.position.x = 0; + a.heading = 99; + const b = port.pose(); + assert.equal(reads, 0, 'answered from the memo'); + assert.notEqual(b, a); + assert.notEqual(b.position, a.position); + assert.notEqual(b.heading, 99); + near(b); + camera.moveRight(1000); + near(port.pose()); + camera.twistRight(0.2); + near(port.pose()); + // Cesium lets right drift a little from direction × up. + const right = port.pose().right; + camera.right = Cesium.Cartesian3.add( + camera.right, + Cesium.Cartesian3.multiplyByScalar( + camera.up, + 0.05, + new Cesium.Cartesian3(), + ), + new Cesium.Cartesian3(), + ); + const drifted = camera.rightWC.x; + const after = port.pose().right.x; + assert.notEqual(after, right.x); + assert.equal(after, drifted); + camera.frustum.fov = 0.4; + assert.ok(Math.abs(port.pose().fovy - camera.frustum.fovy) < 1e-12); + assert.notEqual(port.pose().fovy, b.fovy); + camera.lookAtTransform( + Cesium.Transforms.eastNorthUpToFixedFrame(camera.positionWC), + ); + assert.equal(port.pose().frameIsIdentity, false); + near(port.pose()); +}); + test('followFrame is there only with its capability', () => { const { scene, camera } = headlessCamera(); scene.postUpdate = new Cesium.Event();