Fix the review findings across the engines, layers, data and QA

Navara now matches Cesium where the review found it diverging: a flight
holds the camera inputs, camera.changed counts turns as Cesium does,
render requests made during a frame survive it, follow pinches zoom,
ground widths follow the pixel ratio and Cyber sonar reaches glyph caches
and models. On Cesium, a staged imagery swap keeps loading tiles, setView
replaces a running flight, and a cleared weather detail goes away.

The contract gains MoverSet.failed, maps.terrainRevision,
render.maxTextureSize and surface.sampleTerrainMostDetailed on every
engine, so layers retry failed models, key road heights by terrain,
size weather textures to the GPU and place Bhote Koshi cards on detailed
terrain.

Engine switches keep the live view, follows, focus, layer options and
cards: a pick hands over the exact pose, applies no address options and
pans no carried-over card; a history visit still applies its entry.

Layers put GhostMaps pins, cable landings, OSM Places and directions on
the measured surface without per-frame sampling, draw the Cockpit contact
dot, hide disabled CCTV on attach, and keep ALPR running outside secure
contexts. KML imports draw raised polygon fills, rotated and coloured
ground overlays and north-referenced icon headings, and report files
with nothing to draw.

QA scripts read the contract instead of Cesium internals (test:track is
109/109 again), wait for the camera to rest before clicking, and give
cold switches and parked engines realistic time. Docs follow the code.
This commit is contained in:
German Khokhlov committed 2026-11-09 21:34:42 +04:00
1 parent 69fbf5b38d
commit 0ef29781e5
276 files changed
+7217 -1517

No files matched your search

-2
View File
@@ -164,7 +164,6 @@ export class StyleManager extends ShellScene {
this.placeSearch = placeSearch;
this._navigation = new NavigationController({
viewer,
engine,
tracking: {
flightsLayer,
@@ -196,7 +195,6 @@ export class StyleManager extends ShellScene {
this._cockpitDisplayModeHandler = null;
this._locationNavigation = new LocationNavigation({
viewer,
engine,
placeSearch,
navigation: this._navigation,
+28 -24
View File
@@ -2,10 +2,10 @@ import * as geo from '../geo/index.js';
import { isPickedWorldPosition } from '../data/scenePick.js';
import { t } from '../i18n/index.js';
// The camera is the globe engine's, and so is the follow: the followed
// entity is engine.camera.following().native (on Cesium also an entity the
// app put on viewer.trackedEntity). The viewer, when callers pass one, is
// read only for its clock.
// The camera is the globe engine's, and so is the follow. On Cesium the
// follow is the viewer's tracked entity (an app entity, or the proxy of an
// engine follow): its EntityView keeps whatever offset the camera takes in
// the entity's frame. Elsewhere the follow owns its offset.
// Cesium's EasingFunction.CUBIC_IN_OUT (tween.js Cubic.InOut).
function cubicInOut(amount) {
@@ -13,17 +13,15 @@ function cubicInOut(amount) {
return 0.5 * ((amount -= 2) * amount * amount + 2);
}
function followedEntity(engine) {
const handle = engine?.camera.following?.();
return handle?.native ?? null;
function followedEntity(engine, viewer) {
return engine?.camera.following?.() ? (viewer?.trackedEntity ?? null) : null;
}
// An engine's own follow (no tracked entity: Navara): its handle, which
// knows its target and takes a new offset without ending the follow.
// A follow handle that takes a new offset without ending the follow.
function engineFollow(engine, viewer) {
const handle = engine?.camera.following?.();
return handle &&
!followedEntity(engine) &&
!followedEntity(engine, viewer) &&
typeof handle.target === 'function' &&
typeof handle.retarget === 'function'
? handle
@@ -84,12 +82,12 @@ export function pickViewTarget(engine) {
/**
* Describe the camera as an orbit around the current viewport center.
* @param {import('../globe/contract.js').GlobeEngine | null} engine
* @param {object | null} [viewer] The Cesium viewer whose tracked entity is
* the orbit target.
* @param {object | null} [viewer] The Cesium viewer: its tracked entity and
* the clock that samples it.
*/
export function readCameraTargetFrame(engine, viewer = null) {
if (!engine) return null;
const entity = followedEntity(engine);
const entity = followedEntity(engine, viewer);
const follow = engineFollow(engine, viewer);
const center = entity
? trackedTarget(entity, viewer)
@@ -133,8 +131,7 @@ function setCameraTargetFrame(engine, frame, viewer = null) {
if (!engine || !frame?.target || !Number.isFinite(frame.range)) return false;
const { camera } = engine;
// Inside an engine's own follow: the new frame is the follow's offset (a
// camera command would end the follow; Cesium's tracked entity keeps its
// follow through lookAt below, so both engines keep following).
// camera command would end the follow).
const follow = engineFollow(engine, viewer);
if (follow) {
const heading = normalizedHeading(frame.heading);
@@ -150,19 +147,26 @@ function setCameraTargetFrame(engine, frame, viewer = null) {
return true;
}
try {
const trackedTransform = followedEntity(engine) ? camera.transform() : null;
camera.lookAt(frame.target, {
const offset = {
heading: normalizedHeading(frame.heading),
pitch: frame.pitch,
range: frame.range,
});
if (trackedTransform) {
// Preserve EntityView's reference frame (including satellite frames).
// Its next update carries this new local offset along with the target.
};
if (followedEntity(engine, viewer)) {
// lookAt is a camera command and would end an engine follow; the same
// frame through lookAtTransform does not. Then back to EntityView's
// reference frame (including satellite frames): its next update
// carries this new local offset along with the target.
const trackedTransform = camera.transform();
camera.lookAtTransform(
geo.transforms.eastNorthUpToFixedFrame(frame.target),
offset,
);
camera.lookAtTransform(trackedTransform);
engine.render.request('camera-orientation');
return true;
}
camera.lookAt(frame.target, offset);
const { position: destination, direction, up } = camera.pose();
camera.release();
if (destination && direction && up) {
@@ -238,14 +242,14 @@ export function createCameraOrientationAnimator(
if (!engine) return false;
if (duration <= 0)
return setCameraTargetFrame(engine, { ...frame, ...destination }, viewer);
const entity = followedEntity(engine);
const entity = followedEntity(engine, viewer);
pending = destination;
const start = now();
const headingDelta = geo.math.negativePiToPi(
destination.heading - frame.heading,
);
remove = engine.frames.preUpdate.addEventListener(() => {
if (engine.isDestroyed() || followedEntity(engine) !== entity) {
if (engine.isDestroyed() || followedEntity(engine, viewer) !== entity) {
cancel();
return;
}
@@ -291,7 +295,7 @@ export function createCameraOrientationAnimator(
* runNavigation: Function,
* showToast?: Function,
* animationMs?: number,
* }} options The viewer is only read for its clock and tracked entity.
* }} options The viewer (Cesium) is read for its tracked entity and clock.
*/
export function bindCameraOrientationControls({
viewer = null,
@@ -64,6 +64,7 @@ function createViewer({ cameraPosition, target, pickPosition = null } = {}) {
lookAtTransform(transform) {
calls.push({ type: 'lookAtTransform', transform });
},
cancelFlight() {},
setView(view) {
calls.push({ type: 'setView', view });
},
@@ -0,0 +1,98 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import * as Cesium from 'cesium';
import {
readCameraTargetFrame,
resetCameraNorth,
toggleCameraTilt,
} from './cameraOrientationControls.js';
import { createFakeEngine } from '../globe/testing/fakeEngine.js';
import { createCesiumEngine } from '../globe/cesium/createCesiumEngine.js';
// The aircraft and satellite displays pass native: handle to engine.camera.follow
// (src/layers/aircraft/render/display.js, src/layers/satellites/render/display.js).
const target = Cesium.Cartesian3.fromDegrees(-73.78, 40.64, 3000);
const aircraft = {
gevTrackedId: 'flight:abc',
gevDisplayPosition: () => target,
};
const followAircraft = (engine) =>
engine.camera.follow({
native: aircraft,
position: () => target,
viewFrom: { x: 1400, y: -1400, z: 1000 },
});
// A Cesium viewer with a real camera and the tracked-entity surface the
// Cesium follow drives (no EntityView: the follow's own frame holds).
function cesiumViewer() {
const scene = {
canvas: { clientWidth: 1200, clientHeight: 800, width: 1200, height: 800 },
drawingBufferWidth: 1200,
drawingBufferHeight: 800,
mapProjection: new Cesium.GeographicProjection(Cesium.Ellipsoid.WGS84),
globe: { ellipsoid: Cesium.Ellipsoid.WGS84, pick: () => target },
mapMode2D: Cesium.MapMode2D.INFINITE_SCROLL,
mode: Cesium.SceneMode.SCENE3D,
pixelRatio: 1,
pickPositionSupported: false,
requestRender() {},
preRender: new Cesium.Event(),
preUpdate: new Cesium.Event(),
postRender: new Cesium.Event(),
screenSpaceCameraController: { inertiaZoom: 0.8, minimumZoomDistance: 1 },
};
const camera = new Cesium.Camera(scene);
scene.camera = camera;
let tracked;
const trackedEntityChanged = new Cesium.Event();
const viewer = {
scene,
camera,
canvas: scene.canvas,
clock: { currentTime: Cesium.JulianDate.now(), onTick: new Cesium.Event() },
entities: { add: (options) => new Cesium.Entity(options), remove() {} },
isDestroyed: () => false,
trackedEntityChanged,
get trackedEntity() {
return tracked;
},
set trackedEntity(entity) {
if (entity === tracked) return;
tracked = entity;
trackedEntityChanged.raiseEvent(entity);
},
};
viewer.engine = createCesiumEngine(viewer);
return viewer;
}
for (const [name, act, check] of [
['north-up', resetCameraNorth, (frame) => frame.heading],
['tilt', toggleCameraTilt, (frame) => frame.pitch + Math.PI / 2],
]) {
test(`${name} keeps an engine follow that carries a native handle (Navara aircraft)`, () => {
const engine = createFakeEngine({ kind: 'navara' });
const handle = followAircraft(engine);
engine.fake.frame();
assert.ok(act(engine), `${name} applied`);
engine.fake.frame();
assert.equal(engine.camera.following(), handle, `${name} keeps the follow`);
handle.stop();
engine.destroy();
});
test(`${name} keeps an engine follow on Cesium (aircraft)`, () => {
const viewer = cesiumViewer();
const { engine } = viewer;
const handle = followAircraft(engine);
viewer.scene.preUpdate.raiseEvent();
assert.ok(act(engine, viewer), `${name} applied`);
viewer.scene.preUpdate.raiseEvent();
assert.equal(engine.camera.following(), handle, `${name} keeps the follow`);
const frame = readCameraTargetFrame(engine, viewer);
assert.ok(Math.abs(check(frame)) < 0.02, `${name} reached the camera`);
handle.stop();
engine.destroy();
});
}
+1 -1
View File
@@ -206,7 +206,7 @@ export class CockpitViewController {
this.scratchAnchorCartographic = geo.cartographic.create();
this.scratchCameraCartographic = geo.cartographic.create();
this.scratchTargetCartographic = geo.cartographic.create();
this._listenerRemovers = [];
this._listenerRemovers = [onLocaleChange(() => this.relocalize())];
// Camera mutations belong before scene update/culling. Changing the camera
// from preRender makes 3D Tiles discover a new view after traversal and can
+20
View File
@@ -306,3 +306,23 @@ test('the cockpit eye stays above the engine surface when the aircraft reads bel
env.restore();
}
});
test('locale changes relocalize the cockpit until it is disposed', async () => {
const { getLocale, setLocale } = await import('../i18n/index.js');
const locale = getLocale();
const env = environment();
const owner = new CockpitViewController(env.engine, { services: {} });
let updates = 0;
owner.relocalize = () => updates++;
try {
setLocale(locale === 'de' ? 'en' : 'de');
assert.equal(updates, 1);
owner.dispose();
setLocale(locale);
assert.equal(updates, 1);
} finally {
owner.dispose();
setLocale(locale);
env.restore();
}
});
+33
View File
@@ -486,3 +486,36 @@ test('the search toggle opens the field, and a lookup marks it', async (t) => {
assert.equal(field.classList.contains('searching'), false);
assert.equal(field.classList.contains('expanded'), false);
});
test('the engine picker stays focusable and announces an engine switch', async (t) => {
const { $, pinia } = fixture(t);
const display = useDisplayStore(pinia);
const selected = [];
const select = (kind) => selected.push(kind);
display.presentGlobeEngine({ kind: 'cesium', busy: false, select });
await nextTick();
const picker = $('#globe-engine');
picker.focus();
display.presentGlobeEngine({ kind: 'cesium', busy: true, select });
await nextTick();
assert.equal(picker.disabled, false);
assert.equal(document.activeElement, picker);
assert.equal(picker.getAttribute('aria-busy'), 'true');
assert.equal(picker.getAttribute('aria-disabled'), 'true');
assert.equal(
$('#globe-engine-status').textContent,
'Initializing systems...',
);
picker.value = 'navara';
picker.dispatchEvent(new Event('change', { bubbles: true }));
assert.deepEqual(selected, []);
await nextTick();
assert.equal(picker.value, 'cesium', 'a refused pick is put back');
display.presentGlobeEngine({ kind: 'navara', busy: false, select });
await nextTick();
assert.equal(document.activeElement, picker);
assert.equal(picker.value, 'navara');
assert.ok(picker.classList.contains('gev-field'));
assert.equal($('#globe-engine-status').getAttribute('role'), 'status');
assert.equal($('#globe-engine-status').textContent, 'Navara');
});
+1
View File
@@ -403,6 +403,7 @@ export function createGeoFileImport({
return;
}
await draw(item, attached, loaded);
if (!imports.includes(item)) undraw(item);
} catch {
if (destroyed || scene !== attached) return;
setHint(`${item.name}: ${t('That file could not be read.')}`);
+75
View File
@@ -0,0 +1,75 @@
// A file removed while its drawing on the next engine is still pending
// (icon decode) must not leave that drawing on the globe.
import test from 'node:test';
import assert from 'node:assert/strict';
import { createGeoFileImport } from './geoFileImport.js';
import { emptyRecords } from '../data/geoImportRecords.js';
const el = () => ({
classList: { toggle() {} },
addEventListener() {},
removeEventListener() {},
});
const engine = () => ({
host: { container: el(), canvas: el() },
camera: { moveEnd: { addEventListener: () => () => {} } },
surface: { tilesLoaded: () => true },
render: { request() {} },
});
test('removing a file during its redraw destroys the late drawing', async () => {
const document = {
...el(),
body: el(),
getElementById: (id) => (id === 'geo-import-button' ? el() : null),
};
let actions = null;
const live = new Set();
let gate = null;
const drawFile = async () => {
if (gate) await gate.promise; // the icon decode of the redraw
const drawing = {
report: { drawn: 1, undrawn: 0 },
setShow() {},
refreshGround: async () => {},
footprint: () => [],
destroy: () => live.delete(drawing),
};
live.add(drawing);
return drawing;
};
const tool = createGeoFileImport({
document,
drawFile,
load: async (f) => ({
records: emptyRecords(),
name: f.name,
format: 'kmz',
entityCount: 1,
removed: 0,
revoke() {},
}),
flyToSource() {},
connect: (next) => ((actions = next), () => {}),
});
tool.attachScene({ engine: engine() });
await tool.importFiles([{ name: 'a.kmz', size: 1 }]);
const [{ id }] = tool.list();
assert.equal(live.size, 1);
// Engine switch: the drawing leaves; the next engine draws the file again.
tool.detachScene();
assert.equal(live.size, 0);
let release;
gate = { promise: new Promise((r) => (release = r)) };
tool.attachScene({ engine: engine() });
for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0));
// The user removes the row while the icon still decodes.
assert.equal(actions.removeGeoImport(id), true);
assert.equal(tool.list().length, 0);
release();
for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0));
assert.equal(live.size, 0, 'the removed file left a drawing on the globe');
tool.destroy();
assert.equal(live.size, 0, 'and destroy() cannot release it either');
});
+3 -8
View File
@@ -7,12 +7,10 @@ import { LocationControls } from './location.js';
/**
* Own destination selection, lookup, orbit and world-jump lifetime. The camera
* is the globe `engine`'s, and a world jump stops its follow
* (`engine.camera.following()`); `viewer` is optional and only clears a
* Cesium tracked entity the engine does not report.
* (`engine.camera.following()`).
*/
export class LocationNavigation {
constructor({
viewer = null,
engine = null,
placeSearch,
services,
@@ -23,7 +21,7 @@ export class LocationNavigation {
}) {
Object.assign(
this,
{ viewer, engine, placeSearch, services, navigation, readCockpit },
{ engine, placeSearch, services, navigation, readCockpit },
elements,
operations,
);
@@ -405,7 +403,6 @@ export class LocationNavigation {
controls?.closeSearch();
}
/** Revoke callbacks and settle owned camera work before the viewer is released. */
/**
* Leave the globe (an engine switch): its reset flight, world-jump
* transition and orbit end; the search, its text and the readout stay.
@@ -420,14 +417,12 @@ export class LocationNavigation {
this._stopOrbit();
}
this.orbitController?.attachEngine(null);
this.viewer = null;
this.engine = null;
}
/** Navigate on another globe (an engine switch). */
attachScene({ viewer = null, engine = null } = {}) {
attachScene({ engine = null } = {}) {
if (this._disposed) return;
this.viewer = viewer;
this.engine = engine;
this.orbitController?.attachEngine(engine);
}
+2 -6
View File
@@ -9,12 +9,10 @@ import {
/**
* Own camera authority generations, pending search UI and tracking handoff.
* The camera is the globe `engine`'s. `viewer` is optional and only clears
* Cesium's tracked entity.
* The camera and tracked subject belong to the globe `engine`.
*/
export class NavigationController {
constructor({
viewer = null,
engine = null,
tracking,
settleSearch = () => {},
@@ -29,7 +27,6 @@ export class NavigationController {
cancelOrientation = () => {},
}) {
Object.assign(this, {
viewer,
engine,
tracking,
settleSearch,
@@ -234,7 +231,7 @@ export class NavigationController {
* flight cannot land on the next one. `retainScene` keeps the selection a
* handoff carries across.
*/
setScene({ viewer = null, engine = null } = {}, { retainScene = true } = {}) {
setScene({ engine = null } = {}, { retainScene = true } = {}) {
if (this._disposed) return;
if (this.engine && engine !== this.engine) {
cancelCameraArrival(this.engine);
@@ -243,7 +240,6 @@ export class NavigationController {
clearSearchedLocation: false,
});
}
this.viewer = viewer;
this.engine = engine;
}
/** Subscribe to ownership changes without claiming the camera or exposing mutable state. */
+5 -2
View File
@@ -17,6 +17,7 @@ export function layersNotOnThisEngine(results) {
import { stampInitialShareGesture } from '../navigationPolicy.js';
import { canPresentDeferredStatusNotice } from '../loadingFeedback.js';
import { t, msg, formatDate } from '../i18n/index.js';
import { localizeLayerName } from './layerNames.js';
import { SHARE_VIEW_ENTITY_KINDS } from '../share/follow.js';
import { UiLifetime } from './uiLifetime.js';
@@ -411,9 +412,11 @@ export class ShareRestoration {
if (this._disposed || !Array.isArray(results)) return;
const names = layersNotOnThisEngine(results);
if (!names.length) return;
this.showStatus('NOT ON THIS ENGINE', {
this.showStatus(t('NOT ON THIS ENGINE'), {
state: 'retry',
detail: `Kept in the link: ${names.join(', ')}`,
detail: t('Kept in the link: {layers}', {
layers: names.map(localizeLayerName).join(', '),
}),
// Long enough to read a list of layer names; the engine's own
// persistent notice comes back afterwards (ShellFeedback).
dwellMs: NOT_ON_THIS_ENGINE_DWELL_MS,
+2 -2
View File
@@ -333,8 +333,8 @@ export class ShellScene extends ShellFacade {
militaryAwarenessLayer,
rocketLaunchesLayer,
};
this._navigation.setScene({ viewer, engine });
this._locationNavigation.attachScene({ viewer, engine });
this._navigation.setScene({ engine });
this._locationNavigation.attachScene({ engine });
this.hud.attachEngine(engine, { viewer });
this.shareLinkManager.attachEngine(engine);
this._displayBindings.attachEngine(engine);
+16
View File
@@ -795,6 +795,22 @@ html:not([lang='en']) .pp-slider-row > .pp-slider-mini-label {
outline: 2px solid currentColor;
}
/* While a switch runs the picker keeps focus (aria-disabled, not disabled). */
#globe-engine[aria-busy='true'] {
opacity: var(--gev-field-disabled-opacity, 0.45);
cursor: progress;
}
/* Announces the switch to screen readers only. */
#globe-engine-status {
position: absolute;
width: 1px;
height: 1px;
overflow: hidden;
clip-path: inset(50%);
white-space: nowrap;
}
.map-source-section {
display: grid;
gap: 6px;
+7 -3
View File
@@ -3,6 +3,7 @@ import { storeToRefs } from 'pinia';
import { msg, t } from '../../i18n/index.js';
import { vPanelState } from '../rail/panelState.js';
import UiButton from '../kit/UiButton.vue';
import UiSelect from '../kit/UiSelect.js';
import { vClassToggle } from '../rail/classToggle.js';
import { useDisplayStore } from '../stores/display.js';
import { computed } from 'vue';
@@ -18,6 +19,8 @@ import VoiceControl from './panels/VoiceControl.vue';
// button calls the Display controls' owner, a chip the map source controls.
const display = useDisplayStore();
const { style, mapSource, mapSourceControls, globeEngine } = storeToRefs(display);
// Product names, as the picker's options show them.
const ENGINE_NAMES = { cesium: 'Cesium', navara: 'Navara', 'navara-hd': 'Navara HD' };
// LocationControls publishes the location tray; pills call the controls,
// and the search field keeps their listeners.
const { view: loc, controls: locationControls } = storeToRefs(useLocationStore());
@@ -115,13 +118,14 @@ function selectMapSource(chip) {
<div v-if="globeEngine" id="globe-engine-control">
<label class="map-source-heading" for="globe-engine">
{{ t('Globe Engine') }}
<select id="globe-engine" class="pp-select" translate="no" :value="globeEngine.kind" :disabled="globeEngine.busy"
@change="globeEngine.select($event.target.value)">
<UiSelect id="globe-engine" class="gev-field gev-field--compact" translate="no" :model-value="globeEngine.kind" :aria-disabled="String(globeEngine.busy)" :aria-busy="String(globeEngine.busy)"
@update:model-value="!globeEngine.busy && globeEngine.select($event)">
<option value="cesium">Cesium</option>
<option value="navara">Navara</option>
<option value="navara-hd">Navara HD</option>
</select>
</UiSelect>
</label>
<span id="globe-engine-status" role="status">{{ globeEngine.busy ? t('Initializing systems...') : ENGINE_NAMES[globeEngine.kind] }}</span>
</div>
<section class="map-source-section" aria-labelledby="map-source-label">
<div class="map-source-heading">
+1 -1
View File
@@ -192,7 +192,7 @@ export function createWildlifeSightingCard({
if (fresh) panForId = null;
nextTick(() => {
if (destroyed || !selected.value) return;
position({ allowPan: fresh || metadata?.explicitSelection === true });
position({ allowPan: metadata?.explicitSelection === true });
if (moving) startFrameUpdates();
// Focus the container so keyboard navigation starts inside the card.
if (fresh)
+28
View File
@@ -808,3 +808,31 @@ test('newly mounted chrome repositions the open card without camera events or id
'closing disconnects structural observation',
);
});
test('remounting a selected sighting does not pan the new engine', async (context) => {
const f = fixture(context);
await f.click();
f.card.destroy();
f.obstacle('.hud-top-left', rect(0, 0, 260, 160));
const ui = createUiRuntime();
let pans = 0;
const card = createWildlifeSightingCard({
layer: f.layer,
ui,
engine: f.engine,
documentRef: document,
windowRef: f.windowRef,
now: () => NOW,
project: () => ({ x: 100, y: 100 }),
pan: () => {
pans++;
return true;
},
});
context.after(() => {
card.destroy();
ui.destroy();
});
await settle();
assert.equal(pans, 0);
});