Files
gods-eye-view/src/render/cesium/camera.js
T
Sameh Khamis 45302e9fbf Bound drillPick's work, pick before styles, and put changed thresholds behind a capability
The query contract now says picks answer against the scene as drawn before
effects, and that a drillPick limit bounds the work as well as the answer:
the renderer stops at `limit` hits and looks through at most
max(limit, 16) things under the pointer. The Cesium query port passes that
depth to Cesium's drill (a pick looking under something unpickable stays
unbounded), a click's drill caches one pass per depth, and the stub counts
unpickable items toward the depth.

CameraPose says fovy and aspectRatio describe the nearest centred
perspective frustum, the exact projection being in matrices().

A changed listener's own threshold is now the capability
cameraChangeThreshold; without it every listener fires at 0.5. The Cesium
and stub cameras have it, measured per listener without touching Cesium's
shared percentageChanged.

Conformance: draw.drillPick checks limit 0, never the surface, nothing over
the bare globe, an unpickable cover, nearest first and a bounded prefix;
query.pickBeforeStyles picks an icon under a mirroring style; the threshold
trace is skipped without its capability.
2026-11-08 12:37:04 -08:00

427 lines
14 KiB
JavaScript

/**
* @module render/cesium/camera
* @description The Cesium renderer's camera port over a Cesium camera:
* poses, views, flights, `lookAt`, events and command hooks, each mapped
* onto Cesium's own camera call, and the user's camera controls
* (`cameraControls.js`) on the scene's camera controller.
*/
import * as Cesium from 'cesium';
import { createCameraEvents } from '../camera/events.js';
import { listenerList, toCartesian, uncaught } from './common.js';
import { cameraFlightActive } from './internals.js';
import { createCesiumFollow } from './follow.js';
import { createCesiumControls } from './cameraControls.js';
import { cameraOf, findCamera, provideUnboundCamera } from '../rendererOf.js';
// Loads the factories an unbound viewer gets its credits, draw, frame and
// query ports from.
import './credits.js';
import './draw.js';
import './frame.js';
import './query.js';
/**
* `cameraOf` and `findCamera`, for code that already reaches Cesium:
* importing them from here loads the factory a viewer with no renderer
* bound gets its camera from.
*/
export { cameraOf, findCamera };
/** The contract's easings as Cesium's. */
export const EASINGS = Object.freeze({
linear: Cesium.EasingFunction.LINEAR_NONE,
quadraticInOut: Cesium.EasingFunction.QUADRATIC_IN_OUT,
cubicInOut: Cesium.EasingFunction.CUBIC_IN_OUT,
cubicOut: Cesium.EasingFunction.CUBIC_OUT,
quinticInOut: Cesium.EasingFunction.QUINTIC_IN_OUT,
sineInOut: Cesium.EasingFunction.SINUSOIDAL_IN_OUT,
});
/**
* The contract's moves and looks as Cesium camera method names, called by
* name: a caller's camera may come from another copy of Cesium.
*/
const MOVES = Object.freeze({
forward: 'moveForward',
back: 'moveBackward',
left: 'moveLeft',
right: 'moveRight',
up: 'moveUp',
down: 'moveDown',
});
const LOOKS = Object.freeze({
left: 'lookLeft',
right: 'lookRight',
up: 'lookUp',
down: 'lookDown',
});
/** A contract destination as Cesium's: a Cartesian3, or a Rectangle. */
export function toDestination(d) {
if ('rect' in d) {
const r = d.rect;
return Cesium.Rectangle.fromDegrees(r.west, r.south, r.east, r.north);
}
return toCartesian(d);
}
/**
* A contract orientation as Cesium's; omitted angles are heading 0, pitch
* straight down and roll 0, as the contract says.
*/
export function toOrientation(o = {}) {
if ('direction' in o)
return { direction: toCartesian(o.direction), up: toCartesian(o.up) };
return {
heading: o.heading ?? 0,
pitch: o.pitch ?? -Math.PI / 2,
roll: o.roll ?? 0,
};
}
/** The follow offset of a camera that cannot follow. */
const NO_FOLLOW_OFFSET = Object.freeze({ get: () => null, set() {} });
/**
* @param {{scene: object, camera: object, report: (error: unknown) => void,
* 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,
capabilities,
}) {
const removers = [];
// Camera events: Cesium's own moveStart and moveEnd (500 ms after the
// last change, never while following), and `changed` measured per
// listener on every tick, where Cesium measures its single threshold
// (`camera.percentageChanged`, which this leaves as it is for everyone
// else listening to Cesium's own event).
const cameraEvents = createCameraEvents({
pose: () => cameraPort.pose(),
report,
thresholds: capabilities?.has('cameraChangeThreshold') ?? true,
});
removers.push(
scene.postUpdate.addEventListener(() => {
applyFov();
cameraEvents.stepChanged();
}),
camera.moveStart.addEventListener(() => cameraEvents.emit('moveStart')),
camera.moveEnd.addEventListener(() => cameraEvents.emit('moveEnd')),
);
const following = widget?.trackedEntityChanged
? createCesiumFollow({
widget,
scene,
camera,
onChanged: () => cameraEvents.emit('followChanged'),
})
: null;
const controlsPart = createCesiumControls({ scene });
// Camera commands: hooks run before each one, so an owner can yield.
const commandHooks = listenerList(report);
const command = (kind) => commandHooks.fire({ kind });
// The flight this port started, while it is in progress. Cesium cancels
// a flight in progress when another starts, including one started on
// its camera directly, and runs the callbacks inside the call or frame
// that ends it. `flying` sees every Cesium flight; `flightEnd` comes for
// the flights this port started (the application's flights all move onto
// the port with the camera family).
let flight = null;
// A flight's end that Cesium raises inside one of this port's own calls
// waits until Cesium's call returns, still inside the port's call: Cesium
// runs a cancelled flight's callback before it lets go of that flight, so
// the callback would read `flying` wrong, and a flight it started would
// be let go of with the old one.
let inCesiumCall = 0;
const pendingEnds = [];
function cesiumCall(fn) {
inCesiumCall += 1;
try {
return fn();
} finally {
inCesiumCall -= 1;
if (inCesiumCall === 0)
for (const deliver of pendingEnds.splice(0)) deliver();
}
}
function startFlight(start, options) {
let resolve;
const done = new Promise((r) => (resolve = r));
let ended = false;
const handle = {
done,
cancel() {
if (flight === handle) cesiumCall(() => camera.cancelFlight());
},
};
const end = (outcome) => {
if (ended) return;
ended = true;
if (flight === handle) flight = null;
const deliver = () => {
const cb =
outcome === 'complete' ? options.onComplete : options.onCancel;
try {
cb?.();
} catch (error) {
report(error);
}
resolve(outcome);
cameraEvents.emit('flightEnd');
};
if (inCesiumCall) pendingEnds.push(deliver);
else deliver();
};
flight = handle;
cesiumCall(() =>
start({
complete: () => end('complete'),
cancel: () => end('cancelled'),
}),
);
// Cesium starts nothing mid scene-mode morph, and calls neither back.
if (!ended && !cameraFlightActive(camera)) end('cancelled');
scene.requestRender();
return handle;
}
/**
* The vertical field of view `setFov` asked for, held across resizes:
* Cesium's `fov` is the wider of the two angles (the horizontal one when
* the view is wider than tall), and it keeps that one when the aspect
* changes. Before the first resize, and on a frustum without a field of
* view, it waits.
*/
let heldFovy = null;
function applyFov() {
const frustum = camera.frustum;
const aspect = frustum?.aspectRatio;
if (heldFovy === null || !('fov' in frustum) || !(aspect > 0)) return;
const fov =
aspect > 1 ? 2 * Math.atan(Math.tan(heldFovy / 2) * aspect) : heldFovy;
if (frustum.fov !== fov) frustum.fov = fov;
}
const cameraPort = {
on: (event, cb, options) => cameraEvents.on(event, cb, options),
onCommand: (cb) => commandHooks.on(cb),
setView(spec) {
command('setView');
const d = spec.destination;
camera.setView({
...(d ? { destination: toDestination(d) } : {}),
orientation: toOrientation(spec.orientation),
});
scene.requestRender();
},
flyTo(destination, options = {}) {
command('flyTo');
return startFlight(
(callbacks) =>
camera.flyTo({
destination: toDestination(destination),
orientation: toOrientation(options.orientation),
duration: options.durationS,
easingFunction: options.easing && EASINGS[options.easing],
maximumHeight: options.maxHeight,
pitchAdjustHeight: options.pitchAdjustHeight,
endTransform:
options.endFrame === 'world'
? Cesium.Matrix4.IDENTITY
: undefined,
...callbacks,
}),
options,
);
},
flyToBounds(sphere, options = {}) {
command('flyToBounds');
const o = options.offset ?? {};
return startFlight(
(callbacks) =>
camera.flyToBoundingSphere(
new Cesium.BoundingSphere(
toCartesian(sphere.center),
sphere.radius,
),
{
offset: new Cesium.HeadingPitchRange(
o.heading ?? 0,
o.pitch ?? -Math.PI / 4,
o.range ?? 0,
),
duration: options.durationS,
easingFunction: options.easing && EASINGS[options.easing],
...callbacks,
},
),
options,
);
},
cancelFlight() {
command('cancelFlight');
cesiumCall(() => camera.cancelFlight());
},
get flying() {
return cameraFlightActive(camera);
},
lookAt(target, offset) {
command('lookAt');
camera.lookAt(
toCartesian(target),
new Cesium.HeadingPitchRange(
offset.heading,
offset.pitch,
offset.range,
),
);
scene.requestRender();
},
follow(target) {
if (!following)
throw new Error('This camera cannot follow: it has no entity tracking');
command('follow');
following.follow(target);
scene.requestRender();
},
get followed() {
return following?.followed ?? null;
},
get followFramed() {
return following?.followFramed ?? false;
},
followOffset: following?.followOffset ?? NO_FOLLOW_OFFSET,
controls: controlsPart.controls,
release() {
command('release');
camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
scene.requestRender();
},
move(direction, metres) {
camera[MOVES[direction]](metres);
scene.requestRender();
},
look(direction, radians) {
camera[LOOKS[direction]](radians);
scene.requestRender();
},
rotateAround(axis, radians) {
camera.rotate(toCartesian(axis), radians);
scene.requestRender();
},
zoom(metres) {
// Cesium's zoom, not a move: outside 3D it changes the view's width.
if (metres < 0) camera.zoomOut(-metres);
else camera.zoomIn(metres);
scene.requestRender();
},
setFov({ vertical }) {
// Cesium would take a bad angle and draw a garbage projection.
if (!(vertical > 0 && vertical < Math.PI))
throw new RangeError(`no vertical field of view of ${vertical}`);
heldFovy = vertical;
applyFov();
scene.requestRender();
},
// The scene's own frame: ECEF in 3D, the only mode the app runs (Cesium's
// 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),
),
};
},
viewRectangle() {
const rect = camera.computeViewRectangle(Cesium.Ellipsoid.WGS84);
if (!rect) return null;
const deg = Cesium.Math.toDegrees;
return {
west: deg(rect.west),
south: deg(rect.south),
east: deg(rect.east),
north: deg(rect.north),
};
},
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,
),
};
},
};
// 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,
dispose() {
following?.dispose();
controlsPart.dispose();
for (const off of removers.splice(0)) off();
cameraEvents.clear();
commandHooks.clear();
},
};
}
// A Cesium viewer with no renderer bound to it gets a
// camera port over its camera when code first asks `cameraOf` for one.
provideUnboundCamera((viewer) =>
// By shape, not `instanceof`: the viewer may come from another
// copy of Cesium.
typeof viewer.camera?.flyTo === 'function' &&
typeof viewer.camera.moveStart?.addEventListener === 'function' &&
typeof viewer.scene?.postUpdate?.addEventListener === 'function'
? createCesiumCamera({
scene: viewer.scene,
camera: viewer.camera,
report: uncaught,
widget: viewer,
})
: null,
);