Stop Navara's memory growth on engine switches, hide polygon zones reliably, and drop the Cesium camera rig

- Navara 0.2.1 never frees pick batch ids, and the mover banks rebuilt
  their instanced meshes on each attach, leaking about 260 KiB of
  WebAssembly memory per switch. A per-view pool hands released ids back
  out; the long soak now asserts native growth of at most 32 KiB per switch.
- Navara 0.2.1 sometimes drops the first show:false update on a new
  vector layer, so a zone turned off right after a switch back stayed
  drawn. Polygon displays hide by deleting their layers and rebuild them
  when shown.
- Camera verbs drive both engines through the globe contract; the Cesium
  viewer rig and the tests of states it can no longer reach are gone.
- Flights and military tracking share src/layers/aircraft/tracking.js.
- The geo import scenario reads movers only where the engine has them.
- Add the Navara section to docs/CURRENT-STATE.md and a changelog fragment.
This commit is contained in:
German Khokhlov committed 2026-11-05 21:18:23 +04:00
1 parent 7abf74518f
commit a6c64713ee
46 files changed
+2367 -2894

No files matched your search

+42 -2
View File
@@ -38,6 +38,41 @@ const cesiumDestination = (destination) =>
const cesiumEasing = (easing) => (easing ? easings()[easing] : undefined);
let scratchBasis;
/**
* Write a world direction and up (right = direction × up, up made
* perpendicular) as the camera's basis, in its current reference frame.
* Cesium's setView turns direction/up into heading/pitch/roll, which is
* singular looking straight down: within about 2.6° of nadir it drops the
* roll and reads the heading off `up`. The exact basis is what Cesium's own
* rotate/look/move leave. A degenerate pair (up along direction) keeps
* Cesium's result.
*/
function setBasis(cesium, direction, up) {
scratchBasis ??= {
direction: new Cesium.Cartesian3(),
up: new Cesium.Cartesian3(),
right: new Cesium.Cartesian3(),
};
const right = Cesium.Cartesian3.cross(direction, up, scratchBasis.right);
const rightLength = Cesium.Cartesian3.magnitude(right);
const directionLength = Cesium.Cartesian3.magnitude(direction);
if (!(rightLength > 1e-12 * directionLength) || !Number.isFinite(rightLength))
return;
Cesium.Cartesian3.divideByScalar(right, rightLength, right);
const forward = Cesium.Cartesian3.divideByScalar(
direction,
directionLength,
scratchBasis.direction,
);
const upright = Cesium.Cartesian3.cross(right, forward, scratchBasis.up);
const inverse = cesium.inverseTransform;
Cesium.Matrix4.multiplyByPointAsVector(inverse, forward, cesium.direction);
Cesium.Matrix4.multiplyByPointAsVector(inverse, upright, cesium.up);
Cesium.Matrix4.multiplyByPointAsVector(inverse, right, cesium.right);
}
// A HeadingPitchRange or a Cartesian offset, as Cesium's lookAt takes them.
const cesiumOffset = (offset) =>
'heading' in offset
@@ -167,10 +202,13 @@ export function createCesiumCamera(viewer) {
setView(view) {
if (!view?.destination)
throw new TypeError('setView needs a destination');
const orientation = cesiumOrientation(view.orientation);
cesium.setView({
destination: cesiumDestination(view.destination),
orientation: cesiumOrientation(view.orientation),
orientation,
});
if (orientation?.direction)
setBasis(cesium, orientation.direction, orientation.up);
},
flyTo(options) {
if (!options?.destination)
@@ -209,7 +247,9 @@ export function createCesiumCamera(viewer) {
),
);
},
flightActive: () => flight != null,
// Also a flight started straight on viewer.camera (layers' flyTo and
// flyToBoundingSphere): Cesium runs every camera flight as a scene tween.
flightActive: () => flight != null || viewer.scene.tweens?.length > 0,
lookAt(target, offset) {
cesium.lookAt(toCesium3(target), cesiumOffset(offset));
},
+90
View File
@@ -5,6 +5,7 @@ import * as geo from '../../geo/index.js';
import { isEngineEvent } from '../contract.js';
import { createCesiumCamera } from './camera.js';
import { createFakeViewer } from './testing/fakeViewer.mjs';
import { createCameraViewer } from './testing/cameraViewer.mjs';
const notCesium = (value, label) => {
assert.ok(value != null, `${label} is missing`);
@@ -115,6 +116,95 @@ test('flyTo maps easing, duration and callbacks and tracks the flight', () => {
assert.equal(viewer.callsOf('camera.cancelFlight').length, 1);
});
test('flightActive also reports a flight started straight on the Cesium camera', () => {
const { viewer, camera, cesium } = setup();
assert.equal(camera.flightActive(), false);
// Cesium runs every camera flight as a scene tween, so a layer's own
// viewer.camera.flyTo counts as much as the engine's.
const layerFlight = {};
viewer.scene.tweens.push(layerFlight);
assert.equal(camera.flightActive(), true);
viewer.scene.tweens.splice(viewer.scene.tweens.indexOf(layerFlight), 1);
assert.equal(camera.flightActive(), false);
camera.flyTo({ destination: geo.cartesian3.fromDegrees(0, 0, 1e6) });
assert.equal(camera.flightActive(), true);
cesium.completeFlight();
assert.equal(camera.flightActive(), false);
});
test('setView with direction and up keeps the exact basis next to nadir', () => {
const { camera, engine } = createCameraViewer();
const unit = (x, y, z) =>
Cesium.Cartesian3.normalize(
new Cesium.Cartesian3(x, y, z),
new Cesium.Cartesian3(),
);
for (const locked of [false, true]) {
// Nearly straight down at 15° N with a 30° roll: inside the band where
// Cesium's heading/pitch/roll conversion drops the roll.
const destination = Cesium.Cartesian3.fromDegrees(0, 15, 18_000_000);
const enu = Cesium.Transforms.eastNorthUpToFixedFrame(destination);
const toWorld = (local) =>
Cesium.Matrix4.multiplyByPointAsVector(
enu,
local,
new Cesium.Cartesian3(),
);
const direction = toWorld(unit(0.01, 0, -1));
const level = toWorld(unit(1, 0, 0.01));
const right = Cesium.Cartesian3.cross(
direction,
level,
new Cesium.Cartesian3(),
);
const roll = Cesium.Quaternion.fromAxisAngle(
direction,
Cesium.Math.toRadians(30),
);
const up = Cesium.Matrix3.multiplyByVector(
Cesium.Matrix3.fromQuaternion(roll),
Cesium.Cartesian3.normalize(
Cesium.Cartesian3.cross(right, direction, new Cesium.Cartesian3()),
new Cesium.Cartesian3(),
),
new Cesium.Cartesian3(),
);
if (locked)
camera.lookAtTransform(
Cesium.Transforms.eastNorthUpToFixedFrame(
Cesium.Cartesian3.fromDegrees(20, 10),
),
);
engine.camera.setView({
destination: geo.cartesian3.clone(destination),
orientation: {
direction: geo.cartesian3.clone(direction),
up: geo.cartesian3.clone(up),
},
});
const close = (actual, expected, tolerance, label) =>
assert.ok(
Cesium.Cartesian3.distance(actual, expected) < tolerance,
`${label}: ${Cesium.Cartesian3.distance(actual, expected)}`,
);
close(camera.positionWC, destination, 1e-6, 'position');
close(camera.directionWC, direction, 1e-12, 'direction');
close(camera.upWC, up, 1e-12, 'up');
close(
camera.rightWC,
Cesium.Cartesian3.cross(direction, up, new Cesium.Cartesian3()),
1e-12,
'right',
);
assert.equal(
Cesium.Matrix4.equals(camera.transform, Cesium.Matrix4.IDENTITY),
!locked,
'the reference frame is kept',
);
camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
}
});
test('flyTo with duration 0 completes before it returns and leaves no flight', () => {
const { camera } = setup();
let done = false;
+5 -6
View File
@@ -8,12 +8,11 @@
// drives Cesium's own lighting as before.
//
// The latch is attached when the engine is created (the app creates it with
// the scene, before cameraVerbs and the layers add their own onTick
// listeners), so it runs first in each tick; an onTick listener added before
// the engine existed would read the previous frame's time. destroy removes
// it. A viewer without a clock (tests, a bare scene) latches on the scene's
// preUpdate instead, attached on first use so creating the engine adds no
// scene listener.
// the scene), so it runs before any onTick listener added later; one added
// before the engine existed would read the previous frame's time. destroy
// removes it. A viewer without a clock (tests, a bare scene) latches on the
// scene's preUpdate instead, attached on first use so creating the engine
// adds no scene listener.
import { appClock as pageClock } from '../../time/clock.js';
+1 -2
View File
@@ -31,8 +31,7 @@ test('the clock reads the app clock and latches on the viewer clock from creatio
const viewer = createFakeViewer();
const wall = manualAppClock();
const { clock } = createCesiumClock(viewer, { appClock: wall.appClock });
// Attached at creation, so it runs before onTick listeners added later
// (cameraVerbs installs its own after the engine exists).
// Attached at creation, so it runs before onTick listeners added later.
assert.equal(viewer.clock.onTick.numberOfListeners, 1);
const order = [];
viewer.clock.onTick.addEventListener(() => order.push(clock.frameTime()));
+10 -1
View File
@@ -5,7 +5,9 @@
// one exact tracked frame on preUpdate (applyTrackedCameraFrame) and the
// zoom limits that keep the camera outside the minimum range.
// following() also reports a trackedEntity the app set itself, and
// followChanged is viewer.trackedEntityChanged.
// followChanged is viewer.trackedEntityChanged. A handle on an Entity carries
// its `name` (the Entity's name, else its id): what the camera verbs say they
// are following.
import * as Cesium from 'cesium';
import * as geo from '../../geo/index.js';
@@ -18,6 +20,7 @@ import {
import { toCesium3 } from './convert.js';
const MAX_FRAME_ATTEMPTS = 120;
const entityName = (entity) => (entity ? entity.name || entity.id : undefined);
const ZOOM_INERTIA_STATES = new WeakMap();
function acquireStableTrackedZoom(controller, owner, minRange) {
@@ -188,6 +191,9 @@ export function createCesiumFollow(viewer, { commanded }) {
if (!handle) {
handle = {
native: entity,
get name() {
return entityName(entity);
},
target: () =>
displayPosition(entity, viewer.clock.currentTime, undefined),
stop() {
@@ -308,6 +314,9 @@ export function createCesiumFollow(viewer, { commanded }) {
const state = { entity: null, proxy: null, options, handle: null };
state.handle = {
native: options.native,
get name() {
return entityName(state.handle.native);
},
target() {
try {
return state.options.position();
+27
View File
@@ -126,6 +126,33 @@ test('retarget switches the tracked entity without ending the follow', () => {
assert.deepEqual(changes, [handle, handle]);
});
test('a follow on an Entity names it, as the tracked camera is named', () => {
const { viewer, camera } = setup();
// An entity the app tracked itself: its name, else its id.
viewer.trackedEntity = new Cesium.Entity({ id: 'N123AB', name: 'UAL 12' });
assert.equal(camera.following().name, 'UAL 12');
viewer.trackedEntity = new Cesium.Entity({ id: 'N456CD' });
assert.equal(camera.following().name, 'N456CD');
// The engine's own follow of a native entity; a proxy follow has none.
const native = new Cesium.Entity({
id: 'ISS',
position: Cesium.Cartesian3.clone(TARGET),
viewFrom: new Cesium.Cartesian3(0, -900, 400),
});
const handle = camera.follow({
native,
position: () => TARGET,
viewFrom: { x: 0, y: -900, z: 400 },
});
assert.equal(handle.name, 'ISS');
const proxy = camera.follow({
position: () => TARGET,
viewFrom: { x: 0, y: -900, z: 400 },
});
assert.equal(proxy.name, undefined);
proxy.stop();
});
test('destroy ends an engine follow and leaves an app-tracked entity alone', () => {
const first = setup();
first.camera.follow({
+73
View File
@@ -0,0 +1,73 @@
// A Cesium viewer around a real Cesium.Camera on a stub scene (no renderer,
// GPU or providers), with the Cesium engine over it: for tests that check
// what the globe contract does to Cesium's own camera geometry.
import * as Cesium from 'cesium';
import { createCesiumEngine } from '../createCesiumEngine.js';
/**
* @param {{ width?: number, height?: number }} [options] The canvas size.
* @returns {{ viewer: object, scene: object, camera: Cesium.Camera,
* canvas: EventTarget, engine: import('../../contract.js').GlobeEngine,
* frame: () => void }} `frame()` runs one turn of CesiumWidget's loop: the
* viewer clock's tick, then the scene's frame events.
*/
export function createCameraViewer({ width = 1280, height = 800 } = {}) {
const canvas = Object.assign(new EventTarget(), {
clientWidth: width,
clientHeight: height,
width,
height,
});
const ellipsoid = Cesium.Ellipsoid.WGS84;
const scene = {
canvas,
drawingBufferWidth: width,
drawingBufferHeight: height,
frameState: { mode: Cesium.SceneMode.SCENE3D },
mapProjection: new Cesium.GeographicProjection(ellipsoid),
globe: { ellipsoid },
mapMode2D: Cesium.MapMode2D.INFINITE_SCROLL,
mode: Cesium.SceneMode.SCENE3D,
pixelRatio: 1,
// Cesium's running camera flights.
tweens: [],
preUpdate: new Cesium.Event(),
preRender: new Cesium.Event(),
postRender: new Cesium.Event(),
requestRender() {},
};
const camera = new Cesium.Camera(scene);
scene.camera = camera;
let trackedEntity;
const viewer = {
scene,
camera,
canvas,
container: {},
trackedEntityChanged: new Cesium.Event(),
// Assigning raises trackedEntityChanged, as Cesium's Viewer does.
get trackedEntity() {
return trackedEntity;
},
set trackedEntity(value) {
if (value === trackedEntity) return;
trackedEntity = value;
viewer.trackedEntityChanged.raiseEvent(value);
},
clock: {
onTick: new Cesium.Event(),
currentTime: Cesium.JulianDate.fromIso8601('2026-10-16T12:00:00Z'),
},
isDestroyed: () => false,
};
const engine = createCesiumEngine(viewer, { requestRender: () => {} });
const frame = () => {
const time = viewer.clock.currentTime;
viewer.clock.onTick.raiseEvent(viewer.clock);
scene.preUpdate.raiseEvent(scene, time);
scene.preRender.raiseEvent(scene, time);
scene.postRender.raiseEvent(scene, time);
};
return { viewer, scene, camera, canvas, engine, frame };
}
+11 -1
View File
@@ -30,9 +30,11 @@ export function createFakeViewer({ width = 1024, height = 768 } = {}) {
const fovy = 2 * Math.atan(Math.tan(Math.PI / 6) * (height / width));
const camera = {
positionWC: new Cesium.Cartesian3(7e6, 1e5, 2e5),
// Position and direction in the camera's transform (identity: world).
// Position and basis in the camera's transform (identity: world).
position: new Cesium.Cartesian3(7e6, 1e5, 2e5),
direction: new Cesium.Cartesian3(-1, 0, 0),
up: new Cesium.Cartesian3(0, 0, 1),
right: new Cesium.Cartesian3(0, 1, 0),
directionWC: new Cesium.Cartesian3(-1, 0, 0),
upWC: new Cesium.Cartesian3(0, 0, 1),
rightWC: new Cesium.Cartesian3(0, 1, 0),
@@ -48,6 +50,12 @@ export function createFakeViewer({ width = 1024, height = 768 } = {}) {
},
viewMatrix: Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(1, 2, 3)),
transform: Cesium.Matrix4.clone(Cesium.Matrix4.IDENTITY),
get inverseTransform() {
return Cesium.Matrix4.inverseTransformation(
camera.transform,
new Cesium.Matrix4(),
);
},
defaultZoomAmount: 100000,
percentageChanged: 0.5,
changed: new Cesium.Event(),
@@ -132,6 +140,8 @@ export function createFakeViewer({ width = 1024, height = 768 } = {}) {
postRender: new Cesium.Event(),
requestRenderMode: true,
maximumRenderTimeChange: Infinity,
// Cesium's running camera flights (a flight on viewer.camera is one).
tweens: [],
requestRender: record('scene.requestRender'),
pick: record('scene.pick', () => undefined),
drillPick: record('scene.drillPick', () => []),