mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
A renderer plugin may supply applicationHooks(renderer) for what only its renderer has (map engine, own credits, stale commands, QA handles). What every renderer should do moves onto the contract: controls.keepEarthFramed (behind the keepEarthFramed capability), query.occlusionTest (behind occlusionTest), and panel drawing, which keepPanelRendering now does through resize and frame.renderNow through the contract. renderNow throws when the frame fails to draw. The Cesium port installs its zoom-out guard through keepEarthFramed (a setView no longer cancels its turn) and answers occlusionTest with the scene's probe; the stub answers it with a horizon test.
560 lines
18 KiB
JavaScript
560 lines
18 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,
|
||
// input and query ports from, and a click's own Cesium picks.
|
||
import './credits.js';
|
||
import './draw.js';
|
||
import './frame.js';
|
||
import './input.js';
|
||
import './nativeClick.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,
|
||
});
|
||
|
||
/** 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() {} });
|
||
|
||
/** A Cesium matrix's 16 values, column by column, as `Matrix4.toArray` lists them. */
|
||
function matrixArray(matrix) {
|
||
const out = new Float64Array(16);
|
||
for (let i = 0; i < 16; i++) out[i] = matrix[i];
|
||
return out;
|
||
}
|
||
|
||
/**
|
||
* @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;
|
||
|
||
// Camera commands: hooks run before each one, so an owner can yield.
|
||
const commandHooks = listenerList(report);
|
||
const command = (kind) => commandHooks.fire({ kind });
|
||
|
||
const controlsPart = createCesiumControls({
|
||
scene,
|
||
widget,
|
||
onCommand: (cb) => commandHooks.on(cb),
|
||
});
|
||
|
||
// 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;
|
||
}
|
||
|
||
/**
|
||
* Put the eye at world point `destination` looking along `direction` with
|
||
* `up` up (made square to it), in the camera's frame: a `lookAt` frame
|
||
* stays, as Cesium's setView keeps it.
|
||
*/
|
||
function placeEye(destination, { direction, up }) {
|
||
const at = toCartesian(destination);
|
||
const dir = Cesium.Cartesian3.normalize(
|
||
toCartesian(direction),
|
||
new Cesium.Cartesian3(),
|
||
);
|
||
const right = Cesium.Cartesian3.normalize(
|
||
Cesium.Cartesian3.cross(dir, toCartesian(up), new Cesium.Cartesian3()),
|
||
new Cesium.Cartesian3(),
|
||
);
|
||
const square = Cesium.Cartesian3.cross(right, dir, new Cesium.Cartesian3());
|
||
const transform = camera.transform;
|
||
if (
|
||
transform &&
|
||
!Cesium.Matrix4.equals(transform, Cesium.Matrix4.IDENTITY)
|
||
) {
|
||
const inverse = Cesium.Matrix4.inverseTransformation(
|
||
transform,
|
||
new Cesium.Matrix4(),
|
||
);
|
||
Cesium.Matrix4.multiplyByPoint(inverse, at, camera.position);
|
||
Cesium.Matrix4.multiplyByPointAsVector(inverse, dir, camera.direction);
|
||
Cesium.Matrix4.multiplyByPointAsVector(inverse, square, camera.up);
|
||
Cesium.Matrix4.multiplyByPointAsVector(inverse, right, camera.right);
|
||
return;
|
||
}
|
||
Cesium.Cartesian3.clone(at, camera.position);
|
||
Cesium.Cartesian3.clone(dir, camera.direction);
|
||
Cesium.Cartesian3.clone(square, camera.up);
|
||
Cesium.Cartesian3.clone(right, camera.right);
|
||
}
|
||
|
||
const cameraPort = {
|
||
on: (event, cb, options) => cameraEvents.on(event, cb, options),
|
||
onCommand: (cb) => commandHooks.on(cb),
|
||
setView(spec) {
|
||
command('setView');
|
||
const d = spec.destination;
|
||
const o = spec.orientation;
|
||
// A view by direction and up at a point is placed as given: Cesium's
|
||
// own setView would round it through heading, pitch and roll, which
|
||
// drifts looking straight down, where steps add up (the app's pans,
|
||
// turns and globe turns are setViews).
|
||
if (d && !('rect' in d) && o && 'direction' in o) placeEye(d, o);
|
||
else
|
||
camera.setView({
|
||
...(d ? { destination: toDestination(d) } : {}),
|
||
orientation: toOrientation(o),
|
||
});
|
||
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();
|
||
},
|
||
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: matrixArray(camera.viewMatrix),
|
||
projection: matrixArray(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() {
|
||
// An unmoved camera answers from the pose last read: a frame reads
|
||
// the pose many times over. Each caller gets objects of its own.
|
||
if (!poseKeyHolds() || !poseMemo) {
|
||
poseMemo = readPose();
|
||
// Outside 3D, Cesium measures heading, pitch and roll by moving the
|
||
// camera into the eye's frame and back, which can change its last
|
||
// bits: keyed as it is left.
|
||
if (scene.mode !== Cesium.SceneMode.SCENE3D) 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;
|
||
}
|
||
const enuScratch = new Cesium.Matrix4();
|
||
/**
|
||
* Heading, pitch and roll as Cesium's camera measures them: the eye's
|
||
* direction and up in its east-north-up frame, put through Cesium's own
|
||
* formulas. Cesium moves the camera into that frame and back for each of
|
||
* the three; in 3D this reads the frame once and leaves the camera be
|
||
* (the same heading, and pitch and roll to the last bit or so). In other
|
||
* modes Cesium's frames differ, and it is asked.
|
||
*/
|
||
function headingPitchRoll() {
|
||
if (scene.mode !== Cesium.SceneMode.SCENE3D)
|
||
return {
|
||
heading: camera.heading,
|
||
pitch: camera.pitch,
|
||
roll: camera.roll,
|
||
};
|
||
const m = Cesium.Transforms.eastNorthUpToFixedFrame(
|
||
camera.positionWC,
|
||
scene.mapProjection?.ellipsoid ?? Cesium.Ellipsoid.default,
|
||
enuScratch,
|
||
);
|
||
// Into the frame as Cesium's inverse transformation takes them.
|
||
const d = camera.directionWC;
|
||
const u = camera.upWC;
|
||
const dx = m[0] * d.x + m[1] * d.y + m[2] * d.z;
|
||
const dy = m[4] * d.x + m[5] * d.y + m[6] * d.z;
|
||
const dz = m[8] * d.x + m[9] * d.y + m[10] * d.z;
|
||
const ux = m[0] * u.x + m[1] * u.y + m[2] * u.z;
|
||
const uy = m[4] * u.x + m[5] * u.y + m[6] * u.z;
|
||
const uz = m[8] * u.x + m[9] * u.y + m[10] * u.z;
|
||
// Right as Cesium crosses it there: direction × up.
|
||
const rz = dx * uy - dy * ux;
|
||
const M = Cesium.Math;
|
||
const level = !M.equalsEpsilon(Math.abs(dz), 1.0, M.EPSILON3);
|
||
const heading =
|
||
M.TWO_PI -
|
||
M.zeroToTwoPi(
|
||
(level ? Math.atan2(dy, dx) : Math.atan2(uy, ux)) - M.PI_OVER_TWO,
|
||
);
|
||
const pitch = M.PI_OVER_TWO - M.acosClamped(dz);
|
||
const roll = level ? M.zeroToTwoPi(Math.atan2(-rz, uz) + M.TWO_PI) : 0.0;
|
||
return { heading, pitch, roll };
|
||
}
|
||
|
||
/** 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 });
|
||
const { heading, pitch, roll } = headingPitchRoll();
|
||
// 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,
|
||
pitch,
|
||
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'))
|
||
cameraPort.followFrame = () => matrixArray(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,
|
||
);
|