Files
gods-eye-view/src/render/cesium/camera.js
T
Sameh Khamis 1d4e4ebe90 Fly the remaining flights through the camera port, on any viewer
The embed view, the celestial-ring focus, the ground-guard lift, the
Bhote Koshi approach and orbit, launch selection and replay flights, and
the cockpit's view and takeover now drive the renderer's camera port.
The contract gains a sineInOut easing, pinned by a conformance trace.

A viewer with no renderer bound, such as one a caller of a public
export brings, now gets a camera port too, as it already got an input
port: cameraOf builds one over the viewer's own Cesium camera and keeps
it for the viewer's life, until a renderer is bound. The Cesium adapter
provides the factory as it loads; code that reaches Cesium takes cameraOf
from the adapter so the factory comes with it, and findCamera answers
null where a missing camera is not an error (HUD, share link, world
focus, Recent Imagery's ZOOM IN). A test walks every package export and
fails one that can reach the bridge without loading the factory.

A destroyed viewer gets no camera and lets go of a built one, and the
application renderer stays bound until its viewer is destroyed.
2026-11-06 08:21:57 -08:00

292 lines
9.2 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.
*/
import * as Cesium from 'cesium';
import { createCameraEvents } from '../camera/events.js';
import { listenerList, toCartesian, uncaught } from './common.js';
import { cameraFlightActive } from './internals.js';
import { cameraOf, provideUnboundCamera } from '../rendererOf.js';
/**
* `cameraOf`, for code that already reaches Cesium: importing it from here
* loads the factory a viewer with no renderer bound gets its camera from.
*/
export { cameraOf };
/** 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,
});
/** 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,
};
}
/**
* @param {{scene: object, camera: object, report: (error: unknown) => void}}
* options `scene` gives `requestRender` and the `postUpdate` tick
* `changed` is measured on.
* @returns {{port: import('../contract/camera').CameraPort, dispose: () => void}}
*/
export function createCesiumCamera({ scene, camera, report }) {
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.
const cameraEvents = createCameraEvents({
pose: () => cameraPort.pose(),
report,
});
removers.push(
scene.postUpdate.addEventListener(() => cameraEvents.stepChanged()),
camera.moveStart.addEventListener(() => cameraEvents.emit('moveStart')),
camera.moveEnd.addEventListener(() => cameraEvents.emit('moveEnd')),
);
// 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;
}
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();
},
release() {
command('release');
camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
scene.requestRender();
},
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,
),
};
},
};
return {
port: cameraPort,
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,
})
: null,
);