Files
gods-eye-view/src/globe/testing/contractSuite.mjs
T
German Khokhlov 708c96b6f6 fix(globe): tighten the engine contract after review
Engine events get their own documented semantics (single registration,
branded instances); the fake follows Cesium's roll sign, angle ranges,
synchronous zero-duration flights, flyToSphere defaults and
computeViewRectangle. The contract adds viewProjection, horizonVisible,
flightActive, lookAtTransform/transform, zoomIn/zoomOut, input modifiers,
terrainHeight and clampToHeight, with geometric suite checks. Engine
import rules now follow each engine graph transitively.
2026-10-15 17:15:35 +04:00

1171 lines
38 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// Behavioural checks every GlobeEngine must pass. The suite is engine-agnostic
// and imports nothing from Node, so it runs in Node against the fake engine and
// in a headless browser against the Cesium and Navara engines:
//
// const checks = createContractSuite(engine, { waitFrames });
// for (const { name, run } of checks) await run();
//
// `waitFrames(count)` resolves after the engine has rendered `count` frames.
// Checks request renders themselves, so engines in request-render mode work.
// Each check sets the view it needs; checks may leave the camera anywhere.
import * as geo from '../../geo/index.js';
import { INPUT_TYPES, MODIFIERS, assertGlobeEngine } from '../contract.js';
const { cartesian2, cartesian3, cartographic, ellipsoid, math, matrix4 } = geo;
const WGS84 = ellipsoid.WGS84;
class ContractError extends Error {
constructor(message) {
super(message);
this.name = 'ContractError';
}
}
function ensure(condition, message) {
if (!condition) throw new ContractError(message);
}
function near(actual, expected, tolerance, label) {
ensure(
typeof actual === 'number' && Math.abs(actual - expected) <= tolerance,
`${label}: ${actual} is not within ${tolerance} of ${expected}`,
);
}
// Smallest difference between two angles, in radians.
const angleBetween = (a, b) => Math.abs(math.negativePiToPi(a - b));
const isCartesian3 = (value) =>
value != null &&
Number.isFinite(value.x) &&
Number.isFinite(value.y) &&
Number.isFinite(value.z);
// The local east/north/up axes at a position.
function localAxes(position) {
const frame = geo.transforms.eastNorthUpToFixedFrame(position, WGS84);
return {
frame,
east: cartesian3.create(frame[0], frame[1], frame[2]),
north: cartesian3.create(frame[4], frame[5], frame[6]),
up: cartesian3.create(frame[8], frame[9], frame[10]),
};
}
const inRange = (value, low, high, label) =>
ensure(
typeof value === 'number' && value >= low && value < high,
`${label} ${value} is outside [${low}, ${high})`,
);
const unit = (vector) => cartesian3.normalize(vector, cartesian3.create());
const along = (origin, direction, distance) =>
cartesian3.add(
origin,
cartesian3.multiplyByScalar(direction, distance, cartesian3.create()),
cartesian3.create(),
);
/**
* @param {import('../contract.js').GlobeEngine} engine
* @param {{ waitFrames: (count: number) => Promise<void>, maxWaitFrames?: number }} options
* @returns {{ name: string, run: () => Promise<void> }[]}
*/
export function createContractSuite(
engine,
{ waitFrames, maxWaitFrames = 240 },
) {
if (typeof waitFrames !== 'function')
throw new TypeError('createContractSuite needs a waitFrames(count) helper');
const { camera } = engine;
const settle = async (count = 2) => {
for (let index = 0; index < count; index++) {
engine.render.request();
await waitFrames(1);
}
};
const until = async (predicate, label) => {
for (let frame = 0; frame < maxWaitFrames; frame++) {
if (predicate()) return;
await settle(1);
}
ensure(
predicate(),
`${label} did not happen within ${maxWaitFrames} frames`,
);
};
// A view 1000 km above (20°E, 10°N) looking straight down, heading north.
const nadirView = async (height = 1e6) => {
camera.setView({
destination: cartesian3.fromDegrees(20, 10, height),
orientation: { heading: 0, pitch: -math.PI_OVER_TWO, roll: 0 },
});
await settle();
};
const centre = () => {
const { width, height } = engine.host.size();
return cartesian2.create(width / 2, height / 2);
};
const checks = [
[
'shape: the engine has every contract capability',
async () => {
assertGlobeEngine(engine);
},
],
[
'host.size: a positive CSS size',
async () => {
const { width, height } = engine.host.size();
ensure(
width > 0 && height > 0,
`size ${width}x${height} is not positive`,
);
},
],
[
'camera.setView: heading, pitch and roll round-trip through pose',
async () => {
const destination = cartesian3.fromDegrees(-70, 45, 25000);
const orientation = { heading: 1.2, pitch: -0.6, roll: 0.05 };
camera.setView({ destination, orientation });
await settle();
const pose = camera.pose();
near(
cartesian3.distance(pose.position, destination),
0,
0.01,
'position error (m)',
);
near(
angleBetween(pose.heading, orientation.heading),
0,
1e-6,
'heading error',
);
near(pose.pitch, orientation.pitch, 1e-6, 'pitch');
near(angleBetween(pose.roll, orientation.roll), 0, 1e-6, 'roll error');
},
],
[
'camera.setView: direction and up orientation',
async () => {
const destination = cartesian3.fromDegrees(5, 50, 3e5);
const direction = unit(
cartesian3.negate(destination, cartesian3.create()),
);
const north = cartesian3.cross(
cartesian3.cross(direction, cartesian3.UNIT_Z, cartesian3.create()),
direction,
cartesian3.create(),
);
const up = unit(north);
camera.setView({ destination, orientation: { direction, up } });
await settle();
const pose = camera.pose();
near(
cartesian3.dot(pose.direction, direction),
1,
1e-9,
'direction·expected',
);
near(cartesian3.dot(pose.up, up), 1, 1e-9, 'up·expected');
},
],
[
'camera.pose: cartographic, frame vectors and fovy are consistent',
async () => {
camera.setView({
destination: cartesian3.fromDegrees(139.7, 35.6, 8000),
orientation: { heading: 4, pitch: -0.3, roll: 0 },
});
await settle();
const pose = camera.pose();
const expected = cartographic.fromCartesian(pose.position, WGS84);
near(
pose.cartographic.longitude,
expected.longitude,
1e-9,
'longitude',
);
near(pose.cartographic.latitude, expected.latitude, 1e-9, 'latitude');
near(pose.cartographic.height, expected.height, 0.01, 'height');
for (const [name, vector] of [
['direction', pose.direction],
['up', pose.up],
['right', pose.right],
])
near(cartesian3.magnitude(vector), 1, 1e-6, `|${name}|`);
near(cartesian3.dot(pose.direction, pose.up), 0, 1e-6, 'direction·up');
const right = cartesian3.cross(
pose.direction,
pose.up,
cartesian3.create(),
);
near(
cartesian3.dot(right, pose.right),
1,
1e-6,
'right = direction × up',
);
ensure(
pose.fovy > 0 && pose.fovy < Math.PI,
`fovy ${pose.fovy} out of range`,
);
},
],
[
'camera.percentageChanged: readable and writable',
async () => {
const previous = camera.percentageChanged;
try {
camera.percentageChanged = 0.125;
near(camera.percentageChanged, 0.125, 0, 'percentageChanged');
} finally {
camera.percentageChanged = previous;
}
},
],
[
'camera events: changed, moveStart and moveEnd follow a move',
async () => {
await nadirView();
const previous = camera.percentageChanged;
const seen = { changed: 0, moveStart: 0, moveEnd: 0 };
const removers = Object.keys(seen).map((name) =>
camera[name].addEventListener(() => seen[name]++),
);
try {
camera.percentageChanged = 0.01;
camera.setView({
destination: cartesian3.fromDegrees(60, -30, 2e6),
orientation: { heading: 0, pitch: -math.PI_OVER_TWO, roll: 0 },
});
await until(() => seen.moveEnd > 0, 'moveEnd');
ensure(seen.moveStart > 0, 'moveStart did not fire');
ensure(seen.changed > 0, 'changed did not fire');
} finally {
for (const remove of removers) remove();
camera.percentageChanged = previous;
}
},
],
[
'events: removed listeners are not called',
async () => {
await nadirView();
let viaHandle = 0;
let viaRemove = 0;
const remove = camera.moveStart.addEventListener(() => viaHandle++);
const listener = () => viaRemove++;
engine.frames.postRender.addEventListener(listener);
remove();
ensure(
engine.frames.postRender.removeEventListener(listener) === true,
'removeEventListener did not report removal',
);
await nadirView(3e6);
await settle(3);
ensure(
viaHandle === 0 && viaRemove === 0,
'a removed listener was called',
);
},
],
[
'frames: preUpdate, preRender and postRender fire in order with timestamps',
async () => {
const order = [];
const removers = ['preUpdate', 'preRender', 'postRender'].map((name) =>
engine.frames[name].addEventListener((time) =>
order.push([name, time]),
),
);
try {
await until(
() => order.some(([name]) => name === 'postRender'),
'postRender',
);
} finally {
for (const remove of removers) remove();
}
const firstPost = order.findIndex(([name]) => name === 'postRender');
const frame = order.slice(0, firstPost + 1);
const index = (name) => frame.map(([entry]) => entry).lastIndexOf(name);
ensure(index('preRender') >= 0, 'preRender did not precede postRender');
ensure(index('preUpdate') >= 0, 'preUpdate did not precede postRender');
ensure(
index('preUpdate') < index('preRender'),
'preUpdate ran after preRender',
);
for (const [name, time] of order)
ensure(
Number.isFinite(time),
`${name} timestamp ${time} is not a number`,
);
},
],
[
'render: continuous mode toggles',
async () => {
const previous = engine.render.isContinuous();
try {
engine.render.setContinuous(true);
ensure(
engine.render.isContinuous() === true,
'continuous not enabled',
);
engine.render.setContinuous(false);
ensure(
engine.render.isContinuous() === false,
'continuous not disabled',
);
} finally {
engine.render.setContinuous(previous);
}
},
],
[
'camera.flyTo: duration 0 lands and completes before flyTo returns',
async () => {
await nadirView();
const destination = cartesian3.fromDegrees(-3.7, 40.4, 50000);
const outcome = [];
camera.flyTo({
destination,
orientation: { heading: 0.5, pitch: -0.8, roll: 0 },
duration: 0,
complete: () => outcome.push('complete'),
cancel: () => outcome.push('cancel'),
});
ensure(
outcome.join() === 'complete',
`flyTo returned with [${outcome}] instead of [complete]`,
);
ensure(!camera.flightActive(), 'a duration-0 flight is still active');
const pose = camera.pose();
near(
cartesian3.distance(pose.position, destination),
0,
0.01,
'position error (m)',
);
near(angleBetween(pose.heading, 0.5), 0, 1e-6, 'heading error');
near(pose.pitch, -0.8, 1e-6, 'pitch');
},
],
[
'camera.flyTo: cancelFlight calls cancel and never complete',
async () => {
await nadirView();
const outcome = [];
camera.flyTo({
destination: cartesian3.fromDegrees(100, 0, 5e6),
duration: 5,
easing: 'linear',
complete: () => outcome.push('complete'),
cancel: () => outcome.push('cancel'),
});
await settle(2);
camera.cancelFlight();
await until(() => outcome.length > 0, 'flight cancellation');
await settle(3);
ensure(outcome.join() === 'cancel', `flight ended with ${outcome}`);
},
],
[
'camera.flyTo: a newer flight cancels the previous one',
async () => {
await nadirView();
const outcome = [];
camera.flyTo({
destination: cartesian3.fromDegrees(100, 0, 5e6),
duration: 5,
complete: () => outcome.push('first complete'),
cancel: () => outcome.push('first cancel'),
});
await settle(1);
camera.flyTo({
destination: cartesian3.fromDegrees(20, 10, 2e6),
duration: 0,
complete: () => outcome.push('second complete'),
});
await until(() => outcome.includes('second complete'), 'second flight');
ensure(
outcome.join() === 'first cancel,second complete',
`flights ended with ${outcome}`,
);
},
],
[
'camera.flyToSphere: ends at the range, looking at the centre',
async () => {
await nadirView();
const center = cartesian3.fromDegrees(2.35, 48.85, 100);
let done = false;
camera.flyToSphere(
{ center, radius: 500 },
{
heading: 0.3,
pitch: -0.5,
range: 5000,
duration: 0,
complete: () => (done = true),
},
);
await until(() => done, 'sphere flight completion');
const pose = camera.pose();
near(cartesian3.distance(pose.position, center), 5000, 5, 'range (m)');
const toCenter = unit(
cartesian3.subtract(center, pose.position, cartesian3.create()),
);
near(
cartesian3.dot(toCenter, pose.direction),
1,
1e-6,
'direction·toCentre',
);
},
],
[
'camera.lookAt: holds the range toward the target until release',
async () => {
await nadirView();
const target = cartesian3.fromDegrees(-0.12, 51.5, 0);
camera.lookAt(target, { heading: 0.4, pitch: -0.7, range: 2000 });
await settle();
const pose = camera.pose();
near(cartesian3.distance(pose.position, target), 2000, 1, 'range (m)');
const toTarget = unit(
cartesian3.subtract(target, pose.position, cartesian3.create()),
);
near(
cartesian3.dot(toTarget, pose.direction),
1,
1e-6,
'direction·toTarget',
);
camera.release();
await settle();
near(
cartesian3.distance(camera.pose().position, pose.position),
0,
0.01,
'release moved the camera (m)',
);
},
],
[
'projector.worldToWindow: a point ahead projects to the canvas centre',
async () => {
await nadirView();
const pose = camera.pose();
const window = engine.projector.worldToWindow(
along(pose.position, pose.direction, 1000),
);
ensure(window, 'a point ahead did not project');
const expected = centre();
near(window.x, expected.x, 1, 'x (px)');
near(window.y, expected.y, 1, 'y (px)');
},
],
[
'projector.worldToWindow: a point behind the camera is undefined',
async () => {
await nadirView();
const pose = camera.pose();
const behind = along(pose.position, pose.direction, -1000);
ensure(
engine.projector.worldToWindow(behind) === undefined,
'a point behind the camera projected',
);
},
],
[
'projector.worldToWindow: up on screen is camera up, and result is filled',
async () => {
await nadirView();
const pose = camera.pose();
const ahead = along(pose.position, pose.direction, 1000);
const result = cartesian2.create();
const upper = engine.projector.worldToWindow(
along(ahead, pose.up, 100),
result,
);
ensure(
upper === result,
'worldToWindow did not return its result argument',
);
const lefter = engine.projector.worldToWindow(
along(ahead, pose.right, -100),
);
const expected = centre();
ensure(
upper.y < expected.y,
`camera up projected below the centre (${upper.y})`,
);
ensure(
lefter.x < expected.x,
`camera left projected right of the centre (${lefter.x})`,
);
},
],
[
'camera.pickRay: the centre ray starts at the camera along its direction',
async () => {
await nadirView();
const pose = camera.pose();
const pickRay = camera.pickRay(centre());
ensure(isCartesian3(pickRay?.origin), 'pickRay has no origin');
near(
cartesian3.distance(pickRay.origin, pose.position),
0,
1,
'origin error (m)',
);
near(
cartesian3.dot(unit(pickRay.direction), pose.direction),
1,
1e-6,
'direction·pose',
);
},
],
[
'camera.pickEllipsoid: the nadir hits the surface and the sky misses',
async () => {
await nadirView();
const hit = camera.pickEllipsoid(centre());
ensure(isCartesian3(hit), 'the nadir missed the ellipsoid');
const point = cartographic.fromCartesian(hit, WGS84);
near(point.height, 0, 1, 'surface height (m)');
// Off the surface, Cesium's local up is the scaled-surface normal,
// which misses the geodetic nadir by about 0.0015° at 1000 km.
near(math.toDegrees(point.longitude), 20, 0.01, 'longitude (deg)');
near(math.toDegrees(point.latitude), 10, 0.01, 'latitude (deg)');
camera.setView({
destination: cartesian3.fromDegrees(20, 10, 1e6),
orientation: { heading: 0, pitch: 0.6, roll: 0 },
});
await settle();
ensure(
camera.pickEllipsoid(centre()) === undefined,
'the sky hit the ellipsoid',
);
},
],
[
'projector.worldToWindow: round-trips camera.pickEllipsoid',
async () => {
await nadirView();
const { width, height } = engine.host.size();
const screen = cartesian2.create(width / 4, height / 3);
const hit = camera.pickEllipsoid(screen);
ensure(isCartesian3(hit), 'the screen point missed the ellipsoid');
const back = engine.projector.worldToWindow(hit);
ensure(back, 'the picked point did not project');
near(back.x, screen.x, 1, 'x (px)');
near(back.y, screen.y, 1, 'y (px)');
},
],
[
'camera.viewRectangle: contains the nadir point',
async () => {
await nadirView();
const rectangle = camera.viewRectangle();
ensure(rectangle, 'no view rectangle looking straight down');
const lon = math.toRadians(20);
const lat = math.toRadians(10);
ensure(
rectangle.west < lon && lon < rectangle.east,
`longitude outside ${rectangle.west}..${rectangle.east}`,
);
ensure(
rectangle.south < lat && lat < rectangle.north,
`latitude outside ${rectangle.south}..${rectangle.north}`,
);
},
],
[
'picker: pick, drillPick and pickPosition return contract shapes',
async () => {
await nadirView();
const screen = cartesian2.create(1, 1);
const picked = engine.picker.pick(screen);
ensure(
picked === undefined || 'id' in picked,
'pick returned no id field',
);
const drilled = engine.picker.drillPick(screen, 3);
ensure(Array.isArray(drilled), 'drillPick did not return an array');
ensure(drilled.length <= 3, 'drillPick ignored its limit');
ensure(
typeof engine.picker.pickPositionSupported === 'boolean',
'pickPositionSupported is not boolean',
);
const position = engine.picker.pickPosition(centre());
ensure(
position === undefined || isCartesian3(position),
'pickPosition is not a Cartesian3',
);
},
],
[
'surface: flags, tilesLoaded, sampleHeight, terrainHeight and clampToHeight shapes',
async () => {
for (const flag of ['terrainHeightSupported', 'clampToHeightSupported'])
ensure(
typeof engine.surface[flag] === 'boolean',
`${flag} is not boolean`,
);
const place = cartographic.fromDegrees(20, 10, 0);
if (engine.surface.terrainHeightSupported) {
const terrain = engine.surface.terrainHeight(place);
ensure(
terrain === undefined || Number.isFinite(terrain),
`terrainHeight returned ${terrain}`,
);
}
if (engine.surface.clampToHeightSupported) {
const clamped = engine.surface.clampToHeight(
cartesian3.fromDegrees(20, 10, 5000),
);
ensure(
clamped === undefined || isCartesian3(clamped),
'clampToHeight is not a Cartesian3',
);
}
ensure(
typeof engine.surface.supported === 'boolean',
'supported is not boolean',
);
ensure(
typeof engine.surface.tilesLoaded() === 'boolean',
'tilesLoaded is not boolean',
);
if (!engine.surface.supported) return;
const value = engine.surface.sampleHeight(
cartographic.fromDegrees(20, 10, 0),
);
ensure(
value === undefined || Number.isFinite(value),
`sampleHeight returned ${value}`,
);
},
],
[
'input: every type subscribes and unsubscribes; camera inputs toggle',
async () => {
for (const type of INPUT_TYPES) {
for (const modifier of [undefined, ...MODIFIERS]) {
const off = engine.input.on(type, () => {}, { modifier });
ensure(
typeof off === 'function',
`input.on('${type}', ${modifier}) returned no remover`,
);
off();
off();
}
}
engine.input.setCameraInputs(false);
engine.input.setCameraInputs(true);
},
],
[
'credits.addStatic: returns an idempotent remover',
async () => {
const remove = engine.credits.addStatic('Contract check', {
onScreen: false,
});
ensure(typeof remove === 'function', 'addStatic returned no remover');
remove();
remove();
},
],
[
'maps.setPhotorealTiles(null): photoreal is inactive',
async () => {
engine.maps.setPhotorealTiles(null);
ensure(
engine.maps.photorealActive() === false,
'photoreal still active',
);
},
],
[
'events: adding a listener twice registers it once',
async () => {
let once = 0;
let twice = 0;
const reference = () => once++;
const listener = () => twice++;
const removers = [
engine.frames.postRender.addEventListener(reference),
engine.frames.postRender.addEventListener(listener),
engine.frames.postRender.addEventListener(listener),
];
try {
await until(() => once >= 2, 'postRender');
} finally {
for (const remove of removers) remove();
}
ensure(
twice === once,
`a listener added twice fired ${twice} times in ${once} frames`,
);
removers[1]();
removers[2]();
await settle(2);
ensure(twice === once, 'a removed listener still fired');
},
],
[
'events: removal during dispatch skips the listener; re-adding keeps it',
async () => {
const event = engine.frames.postRender;
const seen = [];
const victim = () => seen.push('victim');
const survivor = () => seen.push('survivor');
let dispatches = 0;
const remover = () => {
dispatches++;
if (dispatches !== 1) return;
event.removeEventListener(victim);
event.removeEventListener(survivor);
event.addEventListener(survivor);
};
event.addEventListener(remover);
event.addEventListener(victim);
event.addEventListener(survivor);
try {
await until(() => dispatches >= 3, 'three postRender dispatches');
} finally {
for (const listener of [remover, victim, survivor])
event.removeEventListener(listener);
}
ensure(
!seen.includes('victim'),
'a listener removed during dispatch ran',
);
ensure(
seen.includes('survivor'),
'a listener removed and re-added during dispatch was lost',
);
},
],
[
'camera.pose: angle ranges follow Cesium',
async () => {
const destination = cartesian3.fromDegrees(30, 20, 20000);
camera.setView({
destination,
orientation: { heading: -0.5, pitch: -0.4, roll: -0.2 },
});
await settle();
let pose = camera.pose();
inRange(pose.heading, 0, math.TWO_PI, 'heading');
inRange(pose.roll, 0, math.TWO_PI, 'roll');
near(pose.heading, math.TWO_PI - 0.5, 1e-6, 'heading of −0.5');
near(pose.roll, math.TWO_PI - 0.2, 1e-6, 'roll of −0.2');
ensure(
pose.pitch >= -math.PI_OVER_TWO && pose.pitch <= math.PI_OVER_TWO,
`pitch ${pose.pitch} outside [−π/2, π/2]`,
);
camera.setView({
destination,
orientation: { heading: 0.7, pitch: -math.PI_OVER_TWO, roll: 0.3 },
});
await settle();
pose = camera.pose();
near(pose.roll, 0, 0, 'roll looking straight down');
inRange(pose.heading, 0, math.TWO_PI, 'heading looking straight down');
},
],
[
'camera.setView: heading π/2 at pitch 0 looks east',
async () => {
const destination = cartesian3.fromDegrees(-120, 35, 3000);
camera.setView({
destination,
orientation: { heading: math.PI_OVER_TWO, pitch: 0, roll: 0 },
});
await settle();
const pose = camera.pose();
const axes = localAxes(pose.position);
near(
cartesian3.dot(pose.direction, axes.east),
1,
1e-6,
'direction·east',
);
near(cartesian3.dot(pose.up, axes.up), 1, 1e-6, 'up·localUp');
},
],
[
'camera.setView: pitch −π/2 looks down the local up',
async () => {
const destination = cartesian3.fromDegrees(-120, 35, 3000);
camera.setView({
destination,
orientation: { heading: 0, pitch: -math.PI_OVER_TWO, roll: 0 },
});
await settle();
const pose = camera.pose();
const axes = localAxes(pose.position);
near(cartesian3.dot(pose.direction, axes.up), -1, 1e-6, 'direction·up');
near(
cartesian3.dot(pose.up, axes.north),
1,
1e-6,
'up·north at heading 0',
);
},
],
[
'camera.setView: positive roll tilts up toward the camera right',
async () => {
const destination = cartesian3.fromDegrees(10, 45, 3000);
camera.setView({
destination,
orientation: { heading: 0.4, pitch: -0.2, roll: 0 },
});
await settle();
const level = camera.pose();
camera.setView({
destination,
orientation: { heading: 0.4, pitch: -0.2, roll: 0.3 },
});
await settle();
const rolled = camera.pose();
near(
cartesian3.dot(rolled.up, level.right),
Math.sin(0.3),
1e-6,
'up·levelRight',
);
near(
cartesian3.dot(rolled.direction, level.direction),
1,
1e-9,
'roll changed the direction',
);
},
],
[
'camera.flightActive: true during a flight, false after it ends',
async () => {
await nadirView();
ensure(!camera.flightActive(), 'a flight is active before flyTo');
camera.flyTo({
destination: cartesian3.fromDegrees(100, 0, 5e6),
duration: 5,
});
ensure(camera.flightActive(), 'no flight is active after flyTo');
camera.cancelFlight();
ensure(
!camera.flightActive(),
'the flight is active after cancelFlight',
);
},
],
[
'camera.flyToSphere: Cesium default heading, pitch and range',
async () => {
await nadirView();
const center = cartesian3.fromDegrees(2.35, 48.85, 100);
const radius = 1000;
let done = false;
camera.flyToSphere(
{ center, radius },
{ duration: 0, complete: () => (done = true) },
);
ensure(
done,
'a duration-0 sphere flight did not complete synchronously',
);
const pose = camera.pose();
const { width, height } = engine.host.size();
const tanPhi = Math.tan(pose.fovy / 2);
const tanTheta = (width / height) * tanPhi;
const range = Math.max(100, radius / tanTheta, radius / tanPhi);
near(
cartesian3.distance(pose.position, center),
range,
range * 1e-6,
'range (m)',
);
const axes = localAxes(center);
const toCamera = unit(
cartesian3.subtract(pose.position, center, cartesian3.create()),
);
near(
cartesian3.dot(toCamera, axes.up),
Math.sin(Math.PI / 4),
1e-6,
'pitch −π/4',
);
near(
cartesian3.dot(toCamera, axes.east),
0,
1e-6,
'heading 0 (east offset)',
);
ensure(
cartesian3.dot(toCamera, axes.north) < 0,
'camera is not south of the centre',
);
camera.flyToSphere({ center, radius: 0 }, { duration: 0 });
near(
cartesian3.distance(camera.pose().position, center),
100,
1e-3,
'minimum range (m)',
);
const identity = camera.transform();
for (let index = 0; index < 16; index++)
near(
identity[index],
matrix4.IDENTITY[index],
0,
`transform[${index}]`,
);
},
],
[
'camera.lookAtTransform: heading/pitch/range and Cartesian offsets, transform and release',
async () => {
await nadirView();
const target = cartesian3.fromDegrees(-0.12, 51.5, 0);
const { frame, up } = localAxes(target);
camera.lookAtTransform(frame, {
heading: 0.4,
pitch: -0.7,
range: 2000,
});
await settle();
let pose = camera.pose();
near(
cartesian3.distance(pose.position, target),
2000,
1e-3,
'range (m)',
);
const aim = () =>
cartesian3.dot(
unit(
cartesian3.subtract(
target,
camera.pose().position,
cartesian3.create(),
),
),
camera.pose().direction,
);
near(aim(), 1, 1e-9, 'direction·toTarget');
const held = camera.transform();
for (let index = 0; index < 16; index++)
near(held[index], frame[index], 1e-6, `transform[${index}]`);
camera.lookAtTransform(frame, cartesian3.create(0, -1000, 1000));
await settle();
pose = camera.pose();
near(
cartesian3.distance(pose.position, target),
Math.SQRT2 * 1000,
1e-3,
'Cartesian offset range (m)',
);
near(aim(), 1, 1e-9, 'Cartesian offset direction·toTarget');
ensure(
cartesian3.dot(pose.up, up) > 0,
'up does not follow the frame +Z',
);
camera.release();
await settle();
near(
cartesian3.distance(camera.pose().position, pose.position),
0,
0.01,
'release moved the camera (m)',
);
const released = camera.transform();
for (let index = 0; index < 16; index++)
near(
released[index],
matrix4.IDENTITY[index],
0,
`released transform[${index}]`,
);
},
],
[
'camera.zoomIn and zoomOut move along the view direction',
async () => {
camera.setView({
destination: cartesian3.fromDegrees(20, 10, 50000),
orientation: { heading: 0.3, pitch: -0.9, roll: 0 },
});
await settle();
const start = camera.pose();
camera.zoomIn(2000);
await settle();
const zoomed = camera.pose().position;
const moved = cartesian3.subtract(
zoomed,
start.position,
cartesian3.create(),
);
near(
cartesian3.dot(moved, start.direction),
2000,
1e-3,
'zoomIn distance (m)',
);
near(
cartesian3.magnitude(moved),
2000,
1e-3,
'zoomIn stays on the view axis',
);
camera.zoomOut(500);
await settle();
near(
cartesian3.distance(camera.pose().position, start.position),
1500,
1e-3,
'zoomOut distance (m)',
);
},
],
[
'camera.viewRectangle: wraps west > east across the antimeridian',
async () => {
camera.setView({
destination: cartesian3.fromDegrees(180, 0, 1e6),
orientation: { heading: 0, pitch: -math.PI_OVER_TWO, roll: 0 },
});
await settle();
const rectangle = camera.viewRectangle();
ensure(rectangle, 'no view rectangle over the antimeridian');
ensure(
rectangle.west > rectangle.east,
`west ${rectangle.west} is not east of east ${rectangle.east}`,
);
ensure(
rectangle.west > 0 && rectangle.east < 0,
'the rectangle does not cross ±180°',
);
ensure(
rectangle.south < 0 && rectangle.north > 0,
'the rectangle misses the equator',
);
},
],
[
'camera.viewRectangle: spans all longitudes over a pole',
async () => {
camera.setView({
destination: cartesian3.fromDegrees(0, 89, 1e6),
orientation: { heading: 0, pitch: -math.PI_OVER_TWO, roll: 0 },
});
await settle();
const rectangle = camera.viewRectangle();
ensure(rectangle, 'no view rectangle over the pole');
near(rectangle.west, -Math.PI, 1e-9, 'west');
near(rectangle.east, Math.PI, 1e-9, 'east');
near(rectangle.north, math.PI_OVER_TWO, 1e-9, 'north');
ensure(
rectangle.south > 0,
`south ${rectangle.south} crosses the equator`,
);
},
],
[
'projector.viewProjection: agrees with worldToWindow',
async () => {
camera.setView({
destination: cartesian3.fromDegrees(20, 10, 30000),
orientation: { heading: 0.6, pitch: -0.5, roll: 0.1 },
});
await settle();
const { width, height } = engine.host.size();
const result = new Array(16).fill(0);
const matrix = engine.projector.viewProjection(result);
ensure(
matrix === result,
'viewProjection did not fill its result argument',
);
ensure(
matrix.length === 16 && matrix.every(Number.isFinite),
'not 16 finite numbers',
);
let compared = 0;
for (const [x, y] of [
[width / 2, height / 2],
[width / 5, height / 4],
[width * 0.9, height * 0.8],
]) {
const point = camera.pickEllipsoid(cartesian2.create(x, y));
if (!point) continue;
const window = engine.projector.worldToWindow(point);
ensure(window, 'a picked point did not project');
const clip = [0, 1, 2, 3].map(
(row) =>
matrix[row] * point.x +
matrix[4 + row] * point.y +
matrix[8 + row] * point.z +
matrix[12 + row],
);
ensure(clip[3] > 0, 'a visible point has clip.w <= 0');
near(((clip[0] / clip[3] + 1) / 2) * width, window.x, 0.5, 'x (px)');
near(((1 - clip[1] / clip[3]) / 2) * height, window.y, 0.5, 'y (px)');
compared++;
}
ensure(compared >= 2, 'too few screen points hit the globe');
},
],
[
'projector.horizonVisible: the nadir is visible and the far side hidden',
async () => {
await nadirView();
ensure(
engine.projector.horizonVisible(cartesian3.fromDegrees(20, 10, 0)),
'the nadir is hidden',
);
ensure(
!engine.projector.horizonVisible(
cartesian3.fromDegrees(-160, -10, 0),
),
'the antipode is visible',
);
ensure(
engine.projector.horizonVisible(cartesian3.fromDegrees(-70, 10, 2e7)),
'a high point beside the limb is hidden',
);
},
],
];
return checks.map(([name, run]) => ({ name, run }));
}
/** Runs every check in order; never throws for a failing check. */
export async function runContractSuite(engine, options) {
const results = [];
for (const { name, run } of createContractSuite(engine, options)) {
try {
await run();
results.push({ name, ok: true });
} catch (error) {
results.push({
name,
ok: false,
error: error instanceof Error ? error : new Error(String(error)),
});
}
}
return results;
}