Files
gods-eye-view/src/globe/follow.js
T
German Khokhlov b03edaaf2b Check the globe contract by behaviour on every engine
The contract suite is split into one module per area and grows from 87
to 114 checks, each named after the member it exercises: a gesture during
a flight does not cut it, a render request inside a frame draws the next
one, a pure rotation raises changed, ground corridors are as wide in CSS
pixels at device scale 2, imagery replans on resize, drapes draw only on
their surface, sampleTerrainMostDetailed keeps order and passes on a
rejection, terrainRevision changes on a new terrain and on fallback,
follows raise followChanged on retarget, and a mesh, a ground fill and an
imagery pixel draw the colour asked for. In the browser Cesium passes all
113 it runs at device scale 1 and 2; Navara passes 110 of 111 and reports
its single-colour mesh, drawn before tone mapping, as a known failure.

scripts/contract-mutants.test.mjs breaks one promise of the fake engine
at a time, 30 mutants in all, and names the check that catches each; the
list of contract members the suite never calls is down to five.

maps.errors reports tile and terrain errors where an engine has them
(the tileErrors capability: Cesium yes, Navara no), and the map
controller falls back to another map only where it does; movers.list()
rows tell whether a set is shown, as the other families do; FollowHandle
.name and PickResult.primitive are marked deprecated. qa-contract-suite
takes --dpr and the ANGLE backend from QA_ANGLE.
2026-11-10 15:26:55 +04:00

445 lines
15 KiB
JavaScript

// camera.follow, the engine-neutral part: a camera that keeps a moving
// target in the centre at an offset in the target's east-north-up frame
// (Cesium's EntityView, trackedEntity's viewFrom), which the user may turn
// and zoom: each frame the offset is re-read from where the camera is
// (the user's gesture moved it) relative to where the target was, carried
// to where the target is now, kept outside the minimum range, and the
// camera aimed at the target. Engines without a native follow (Navara, the
// fake engine) run it on their frames; Cesium follows with trackedEntity.
// A command that takes the camera (setView, flyTo…) ends the follow.
import * as geo from '../geo/index.js';
import { createEngineEvent } from './contract.js';
const { cartesian3, math, matrix4 } = geo;
const WGS84 = geo.ellipsoid.WGS84;
export const MIN_FOLLOW_RANGE_M = 150;
const isCartesian = (value) =>
value != null &&
Number.isFinite(value.x) &&
Number.isFinite(value.y) &&
Number.isFinite(value.z);
/** follow() options checked: position and viewFrom as functions. */
export function normalizeFollowOptions(options) {
if (!options || typeof options.position !== 'function')
throw new TypeError('camera.follow needs position: () => Cartesian3');
const { viewFrom } = options;
const viewFromOf =
typeof viewFrom === 'function'
? viewFrom
: isCartesian(viewFrom)
? () => viewFrom
: null;
if (!viewFromOf)
throw new TypeError('camera.follow needs viewFrom (ENU metres)');
const minRange = options.minRange ?? MIN_FOLLOW_RANGE_M;
if (!(Number.isFinite(minRange) && minRange >= 0))
throw new TypeError(`camera.follow minRange must be >= 0: ${minRange}`);
if (options.frame !== undefined && options.frame !== 'enu')
throw new TypeError("camera.follow frame must be 'enu'");
if (
options.swingTo != null &&
(!isCartesian(options.swingTo) ||
cartesian3.magnitude(options.swingTo) === 0)
)
throw new TypeError('camera.follow swingTo must be a nonzero ENU offset');
const { label } = options;
if (
label !== undefined &&
!(
label &&
typeof label.id === 'string' &&
typeof label.position === 'function'
)
)
throw new TypeError(
'camera.follow label needs { id, model, position: () => Cartesian3 }',
);
return {
position: options.position,
viewFrom: viewFromOf,
minRange,
swingTo: options.swingTo ? cartesian3.clone(options.swingTo) : null,
native: options.native,
label,
};
}
const scratchFrame = matrix4.create();
const scratchInverse = matrix4.create();
const scratchOffset = cartesian3.create();
const scratchWorld = cartesian3.create();
const scratchUp = cartesian3.create();
const scratchBefore = cartesian3.create();
/**
* One follow step: the camera pose that keeps `target` centred at `offset`
* (ENU of the target, metres, kept outside `minRange`).
* @returns {{ position, direction, up }}
*/
export function followPose(target, offset, minRange) {
const range = cartesian3.magnitude(offset);
const local =
range >= minRange || range === 0
? cartesian3.clone(offset, scratchOffset)
: cartesian3.multiplyByScalar(offset, minRange / range, scratchOffset);
const frame = geo.transforms.eastNorthUpToFixedFrame(
target,
WGS84,
scratchFrame,
);
const position = matrix4.multiplyByPoint(frame, local, cartesian3.create());
const direction = cartesian3.normalize(
cartesian3.subtract(target, position, cartesian3.create()),
cartesian3.create(),
);
// The target's local up, made perpendicular to the view direction.
cartesian3.fromElements(frame[8], frame[9], frame[10], scratchUp);
let right = cartesian3.cross(direction, scratchUp, cartesian3.create());
if (cartesian3.magnitude(right) < 1e-9)
right = cartesian3.fromElements(frame[0], frame[1], frame[2]);
cartesian3.normalize(right, right);
const up = cartesian3.normalize(
cartesian3.cross(right, direction, cartesian3.create()),
cartesian3.create(),
);
return { position, direction, up };
}
/**
* Keep a camera (in a target-centred frame: the target at the origin) on the
* same side of its target and outside the minimum range. Cesium's tracked
* camera (cesium/follow.js) runs it after a programmatic zoom.
*
* @param {{position: Cartesian3, direction: Cartesian3}} camera Camera-like
* object, corrected in place.
* @param {Cartesian3} previousPosition The previous frame's camera position.
* @param {number} [minimumRangeM=MIN_FOLLOW_RANGE_M] Minimum target range.
* @returns {boolean} Whether the camera position was corrected.
*/
export function clampTrackedCameraPosition(
camera,
previousPosition,
minimumRangeM = MIN_FOLLOW_RANGE_M,
) {
const crossedOrigin = cartesian3.dot(camera.position, previousPosition) <= 0;
const forwardDistance = -cartesian3.dot(camera.position, camera.direction);
const rangeSquared = cartesian3.magnitudeSquared(camera.position);
if (crossedOrigin) {
cartesian3.normalize(previousPosition, camera.position);
cartesian3.multiplyByScalar(
camera.position,
minimumRangeM,
camera.position,
);
return true;
}
if (
forwardDistance < minimumRangeM ||
rangeSquared < minimumRangeM * minimumRangeM
) {
cartesian3.multiplyByScalar(
camera.direction,
-minimumRangeM,
camera.position,
);
return true;
}
return false;
}
/** The camera's offset from `target` in the target's ENU frame. */
export function enuOffset(
target,
cameraPosition,
result = cartesian3.create(),
) {
const frame = geo.transforms.eastNorthUpToFixedFrame(
target,
WGS84,
scratchFrame,
);
const inverse = matrix4.inverseTransformation(frame, scratchInverse);
return matrix4.multiplyByPoint(
inverse,
cartesian3.clone(cameraPosition, scratchWorld),
result,
);
}
// Elevation of the camera above the target's horizon: kept between these
// (radians), as Cesium's tracked camera stays above the ground plane.
const MIN_ELEVATION = math.toRadians(2);
const MAX_ELEVATION = math.toRadians(89);
/** The ENU offset turned by `dHeading` and raised by `dPitch` (radians), same range. */
export function orbitOffset(
offset,
dHeading,
dPitch,
result = cartesian3.create(),
) {
const range = cartesian3.magnitude(offset);
if (!(range > 0)) return cartesian3.clone(offset, result);
const heading = Math.atan2(offset.x, offset.y) + dHeading;
const elevation = math.clamp(
Math.asin(math.clamp(offset.z / range, -1, 1)) + dPitch,
MIN_ELEVATION,
MAX_ELEVATION,
);
const horizontal = range * Math.cos(elevation);
return cartesian3.fromElements(
horizontal * Math.sin(heading),
horizontal * Math.cos(heading),
range * Math.sin(elevation),
result,
);
}
/** The ENU offset scaled by `factor`, never inside `minRange`. */
function zoomOffset(offset, factor, minRange, result = cartesian3.create()) {
const range = cartesian3.magnitude(offset);
if (!(range > 0) || !(factor > 0)) return cartesian3.clone(offset, result);
const next = Math.max(minRange, range * factor);
return cartesian3.multiplyByScalar(offset, next / range, result);
}
/**
* The ENU offset dollied as Cesium's zoom3D: `ratio` is the drag over the
* canvas height (down closes in), at most a tenth per move; the camera moves
* five times that share of its distance above the floor (closing) or of its
* range (opening), never inside `minRange`.
*/
export function dollyOffset(
offset,
ratio,
minRange,
result = cartesian3.create(),
) {
const range = cartesian3.magnitude(offset);
if (!(range > 0) || !Number.isFinite(ratio))
return cartesian3.clone(offset, result);
const window = Math.min(ratio, 0.1);
const closing = window > 0;
const distance = 5 * (range - (closing ? minRange : 0)) * window;
const next = Math.max(minRange, range - distance);
return cartesian3.multiplyByScalar(offset, next / range, result);
}
const STILL_M = 1e-6;
/**
* @param {{
* camera: { pose: () => object, commanded: object },
* aim: (pose: { position, direction, up }) => void,
* frame: { addEventListener: Function },
* requestRender: () => void,
* gestures?: (handlers: { orbit: (dHeading: number, dPitch: number) => void,
* zoom: (factor: number) => void }) => () => void,
* }} ports `aim` places the camera without camera.commanded; `frame` is
* the event the follow steps on (the engine's preRender, after it read
* the user's camera). `gestures` (Navara): while following, the engine's
* own drag and wheel handling is suspended and its drag and wheel turn
* and scale the offset instead (as Cesium's EntityView orbits the
* target); it returns the release. Without it the offset is re-read from
* the camera each frame (the fake engine).
*/
export function createFollowController({
camera,
aim,
frame,
requestRender,
gestures = null,
}) {
const followChanged = createEngineEvent();
let current = null;
let removeFrame = null;
let removeCommanded = null;
let releaseGestures = null;
let aiming = false;
const end = (handle) => {
if (current !== handle) return;
current = null;
removeFrame?.();
removeCommanded?.();
releaseGestures?.();
removeFrame = null;
removeCommanded = null;
releaseGestures = null;
followChanged.raiseEvent(null);
};
// Drag and wheel (gestures port): applied at the next step.
const gestureHandlers = {
orbit(dHeading, dPitch) {
const handle = current;
if (!handle?.offset) return;
orbitOffset(handle.offset, dHeading, dPitch, handle.offset);
handle.moved = true;
requestRender();
},
dolly(ratio) {
const handle = current;
if (!handle?.offset) return;
dollyOffset(handle.offset, ratio, handle.options.minRange, handle.offset);
handle.moved = true;
requestRender();
},
zoom(factor) {
const handle = current;
if (!handle?.offset) return;
zoomOffset(handle.offset, factor, handle.options.minRange, handle.offset);
handle.moved = true;
requestRender();
},
};
const step = () => {
const handle = current;
if (!handle) return;
let target;
try {
target = handle.options.position();
} catch {
target = null;
}
if (!isCartesian(target)) return;
let changed = handle.moved || !handle.previous;
handle.moved = false;
if (!handle.offset) {
const from = handle.options.viewFrom();
if (!isCartesian(from)) return;
handle.offset = cartesian3.clone(from);
changed = true;
} else if (handle.previous && !gestures) {
// The user may have turned or zoomed the camera since the last step.
const before = cartesian3.clone(handle.offset, scratchBefore);
enuOffset(handle.previous, camera.pose().position, handle.offset);
if (cartesian3.distance(before, handle.offset) > STILL_M) changed = true;
}
if (
handle.previous &&
cartesian3.distance(handle.previous, target) > STILL_M
)
changed = true;
if (handle.swingTo && handle.previous) {
const angle = cartesian3.angleBetween(handle.offset, handle.swingTo);
handle.offset =
angle > MAX_FOLLOW_TURN
? turnFollowOffset(handle.offset, handle.swingTo)
: cartesian3.clone(handle.swingTo);
if (!(angle > MAX_FOLLOW_TURN)) handle.swingTo = null;
changed = true;
}
if (handle.swingTo) changed = true;
const pose = followPose(target, handle.offset, handle.options.minRange);
handle.previous = cartesian3.clone(target, handle.previous ?? undefined);
// The offset in force (the minimum range applied).
enuOffset(target, pose.position, handle.offset);
aiming = true;
try {
aim(pose);
} finally {
aiming = false;
}
// A moving target (or a gesture) needs the next frame; a still one
// lets the engine idle.
if (changed) requestRender();
};
return {
followChanged,
following: () => current,
follow(input) {
const options = normalizeFollowOptions(input);
if (current) end(current);
const handle = {
options,
native: options.native,
label: options.label,
swingTo: options.swingTo,
offset: null,
previous: null,
target() {
try {
return handle.options.position();
} catch {
return undefined;
}
},
stop: () => end(handle),
retarget(next) {
if (current !== handle) return;
const updated = normalizeFollowOptions({
...handle.options,
...next,
});
handle.swingTo = updated.swingTo;
if (Object.keys(next).every((key) => key === 'swingTo')) {
handle.options = updated;
requestRender();
return;
}
handle.options = updated;
handle.native = updated.native;
handle.label = updated.label;
handle.offset = null;
handle.previous = null;
followChanged.raiseEvent(handle);
requestRender();
},
};
current = handle;
removeFrame = frame.addEventListener(step);
if (gestures && !releaseGestures)
releaseGestures = gestures(gestureHandlers);
removeCommanded = camera.commanded.addEventListener(() => {
if (!aiming) end(handle);
});
followChanged.raiseEvent(handle);
requestRender();
return handle;
},
destroy() {
if (current) end(current);
},
};
}
export const MAX_FOLLOW_TURN = Math.PI / 3;
/**
* `from` turned `step` radians toward `to`, with its length moved the same
* fraction of the way: one frame of the swing round the entity.
*/
export function turnFollowOffset(from, to, step = MAX_FOLLOW_TURN) {
const angle = cartesian3.angleBetween(from, to);
const unitFrom = cartesian3.normalize(from, cartesian3.create());
// The direction perpendicular to `from` in the plane toward `to` (or any
// perpendicular when they are opposite).
let toward = cartesian3.subtract(
cartesian3.normalize(to, cartesian3.create()),
cartesian3.multiplyByScalar(unitFrom, Math.cos(angle), cartesian3.create()),
cartesian3.create(),
);
if (cartesian3.magnitude(toward) < 1e-9)
toward = cartesian3.cross(
unitFrom,
Math.abs(unitFrom.z) < 0.9 ? cartesian3.UNIT_Z : cartesian3.UNIT_X,
cartesian3.create(),
);
cartesian3.normalize(toward, toward);
const length =
cartesian3.magnitude(from) +
(cartesian3.magnitude(to) - cartesian3.magnitude(from)) * (step / angle);
const direction = cartesian3.add(
cartesian3.multiplyByScalar(unitFrom, Math.cos(step), cartesian3.create()),
cartesian3.multiplyByScalar(toward, Math.sin(step), cartesian3.create()),
cartesian3.create(),
);
return cartesian3.multiplyByScalar(direction, length, direction);
}