diff --git a/src/render/cesium/camera.js b/src/render/cesium/camera.js index d8347946f..efb25ed92 100644 --- a/src/render/cesium/camera.js +++ b/src/render/cesium/camera.js @@ -64,6 +64,13 @@ export function toOrientation(o = {}) { /** The follow offset of a camera that cannot follow. */ const NO_FOLLOW_OFFSET = Object.freeze({ get: () => null, set() {} }); +/** A Cesium matrix's 16 values, column by column, as `Matrix4.toArray` lists them. */ +function matrixArray(matrix) { + const out = new Float64Array(16); + for (let i = 0; i < 16; i++) out[i] = matrix[i]; + return out; +} + /** * @param {{scene: object, camera: object, report: (error: unknown) => void, * widget?: object, capabilities?: ReadonlySet}} options `scene` @@ -351,10 +358,8 @@ export function createCesiumCamera({ // 2D and Columbus view frames are projected map coordinates). matrices() { return { - view: Float64Array.from(Cesium.Matrix4.toArray(camera.viewMatrix)), - projection: Float64Array.from( - Cesium.Matrix4.toArray(camera.frustum.projectionMatrix), - ), + view: matrixArray(camera.viewMatrix), + projection: matrixArray(camera.frustum.projectionMatrix), }; }, viewRectangle() { @@ -369,15 +374,14 @@ export function createCesiumCamera({ }; }, pose() { - // 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. + // An unmoved camera answers from the pose last read: 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(); + // Outside 3D, Cesium measures heading, pitch and roll by moving the + // camera into the eye's frame and back, which can change its last + // bits: keyed as it is left. + if (scene.mode !== Cesium.SceneMode.SCENE3D) poseKeyHolds(); } return copyPose(poseMemo); }, @@ -432,9 +436,54 @@ export function createCesiumCamera({ for (let i = 0; i < 16; i++) put(t[i]); return same; } + const enuScratch = new Cesium.Matrix4(); + /** + * Heading, pitch and roll as Cesium's camera measures them: the eye's + * direction and up in its east-north-up frame, put through Cesium's own + * formulas. Cesium moves the camera into that frame and back for each of + * the three; in 3D this reads the frame once and leaves the camera be + * (the same heading, and pitch and roll to the last bit or so). In other + * modes Cesium's frames differ, and it is asked. + */ + function headingPitchRoll() { + if (scene.mode !== Cesium.SceneMode.SCENE3D) + return { + heading: camera.heading, + pitch: camera.pitch, + roll: camera.roll, + }; + const m = Cesium.Transforms.eastNorthUpToFixedFrame( + camera.positionWC, + scene.mapProjection?.ellipsoid ?? Cesium.Ellipsoid.default, + enuScratch, + ); + // Into the frame as Cesium's inverse transformation takes them. + const d = camera.directionWC; + const u = camera.upWC; + const dx = m[0] * d.x + m[1] * d.y + m[2] * d.z; + const dy = m[4] * d.x + m[5] * d.y + m[6] * d.z; + const dz = m[8] * d.x + m[9] * d.y + m[10] * d.z; + const ux = m[0] * u.x + m[1] * u.y + m[2] * u.z; + const uy = m[4] * u.x + m[5] * u.y + m[6] * u.z; + const uz = m[8] * u.x + m[9] * u.y + m[10] * u.z; + // Right as Cesium crosses it there: direction × up. + const rz = dx * uy - dy * ux; + const M = Cesium.Math; + const level = !M.equalsEpsilon(Math.abs(dz), 1.0, M.EPSILON3); + const heading = + M.TWO_PI - + M.zeroToTwoPi( + (level ? Math.atan2(dy, dx) : Math.atan2(uy, ux)) - M.PI_OVER_TWO, + ); + const pitch = M.PI_OVER_TWO - M.acosClamped(dz); + const roll = level ? M.zeroToTwoPi(Math.atan2(-rz, uz) + M.TWO_PI) : 0.0; + return { heading, pitch, roll }; + } + /** 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 }); + const { heading, pitch, roll } = headingPitchRoll(); // Cesium has no cartographic position for an eye at the earth's // centre; the pose then says so with NaN. const carto = camera.positionCartographic ?? { @@ -449,9 +498,9 @@ export function createCesiumCamera({ direction: v(camera.directionWC), up: v(camera.upWC), right: v(camera.rightWC), - heading: camera.heading, - pitch: camera.pitch, - roll: camera.roll, + heading, + pitch, + roll, height: carto.height, fovy: camera.frustum.fovy, aspectRatio: camera.frustum.aspectRatio, @@ -474,8 +523,7 @@ export function createCesiumCamera({ // 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)); + cameraPort.followFrame = () => matrixArray(camera.transform); return { port: cameraPort, diff --git a/src/render/cesium/cameraPort.test.mjs b/src/render/cesium/cameraPort.test.mjs index 1902dc137..30fe8fd1e 100644 --- a/src/render/cesium/cameraPort.test.mjs +++ b/src/render/cesium/cameraPort.test.mjs @@ -305,6 +305,53 @@ test('setFov holds the vertical angle across resizes, and waits for a first one' assert.throws(() => port.setFov({ vertical: NaN }), RangeError); }); +test('a pose measures heading, pitch and roll as Cesium does, and leaves the camera as it was', () => { + const { camera, port } = headlessPort(); + const bits = () => + [ + camera.positionWC, + camera.directionWC, + camera.upWC, + camera.rightWC, + camera.position, + camera.direction, + camera.up, + ].flatMap((v) => [v.x, v.y, v.z]); + const views = [ + { heading: 0.3, pitch: -0.7, roll: 0 }, + { heading: 5.9, pitch: -Math.PI / 2, roll: 0 }, + { heading: 2.1, pitch: -0.05, roll: 0.4 }, + { heading: 0, pitch: Math.PI / 2 - 1e-5, roll: 0 }, + { heading: 4, pitch: 0.6, roll: 6 }, + ]; + for (const [k, orientation] of views.entries()) { + port.setView({ + destination: { + lon: -170 + 70 * k, + lat: -80 + 40 * k, + height: 3e3 * 10 ** k, + }, + orientation, + }); + if (k === 4) + camera.lookAtTransform( + Cesium.Transforms.eastNorthUpToFixedFrame(camera.positionWC), + ); + const before = bits(); + const pose = port.pose(); + assert.deepEqual(bits(), before, 'the camera is not moved to measure it'); + // Cesium's own reads move the camera there and back three times; the + // first, heading, is read as the pose reads it. + const heading = camera.heading; + const pitch = camera.pitch; + const roll = camera.roll; + assert.equal(pose.heading, heading, `heading ${k}`); + assert.ok(Math.abs(pose.pitch - pitch) < 1e-12, `pitch ${k}`); + const turn = Math.abs(pose.roll - roll); + assert.ok(Math.min(turn, 2 * Math.PI - turn) < 1e-12, `roll ${k}`); + } +}); + test('an unmoved camera answers its pose from the last read; any change reads it anew', () => { const { camera, port } = headlessPort(); port.setView({ @@ -315,7 +362,7 @@ test('an unmoved camera answers its pose from the last read; any change reads it // 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; + const carto = cartographic.get.call(camera); return { lon: Cesium.Math.toDegrees(carto.longitude), lat: Cesium.Math.toDegrees(carto.latitude), @@ -336,16 +383,17 @@ test('an unmoved camera answers its pose from the last read; any change reads it `${name}: ${got[name]} vs ${value}`, ); }; - // Counts Cesium's heading reads: an answer from the memo makes none. + // Counts the camera's cartographic position read: an answer from the + // memo reads none. let reads = 0; - const heading = Object.getOwnPropertyDescriptor( + const cartographic = Object.getOwnPropertyDescriptor( Cesium.Camera.prototype, - 'heading', + 'positionCartographic', ); - Object.defineProperty(camera, 'heading', { + Object.defineProperty(camera, 'positionCartographic', { get() { reads += 1; - return heading.get.call(this); + return cartographic.get.call(this); }, }); const a = port.pose();