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.
This commit is contained in:
Sameh Khamis committed 2026-11-07 21:49:25 -08:00
1 parent b0ed9d7e90
commit 90e73f2ef2
19 files changed
+596 -143

No files matched your search

+18 -5
View File
@@ -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<string>}} 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,
+10
View File
@@ -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');
});
+1
View File
@@ -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',
+8 -1
View File
@@ -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,
+1
View File
@@ -10,6 +10,7 @@ import { updateCameraChanged } from './internals.js';
test('capabilities follow what the scene supports', () => {
const effects = [
'followFrame',
'columns',
'motionSegments',
'courseGlide',
+1 -2
View File
@@ -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"
]
+112
View File
@@ -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',
+14
View File
@@ -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. */
+2
View File
@@ -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';
+6
View File
@@ -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({}), [
+5 -3
View File
@@ -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',
+9
View File
@@ -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;
},
+2
View File
@@ -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 },
});
-15
View File
@@ -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 };