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.
This commit is contained in:
Sameh Khamis committed 2026-11-10 14:50:57 -08:00
1 parent 6c49ffe825
commit 0a0645e28e
2 files changed
+183 -28

No files matched your search

+100 -28
View File
@@ -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'))
+83
View File
@@ -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();