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

+6
View File
@@ -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
+24 -1
View File
@@ -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);
}
+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 };
+151 -96
View File
@@ -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;
}
+163
View File
@@ -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);
});
+63 -20
View File
@@ -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);