Move shared follow offsets and Draw onto the globe contract

Share links read the current follow handle and displayed position through
engine.camera and restore their ENU offset with follow's swingTo option.
Cesium retains its first-frame wait, displayed-position cache, 60-degree
frame limit and range interpolation. Navara and the fake engine apply the
same swing. Cancellation, camera handoff and destruction release it; an
externally tracked Cesium entity keeps its existing handle.

Draw uses one surface with engine input, geodesic lines and point movers.
An exclusive pointer claim suppresses ambient subscriptions and deferred
picks across ownership changes. Cesium owns suspension and exact restoration
of its stock select and track actions. Camera gestures remain enabled.
Detaching releases the sketch and preview and retains shape and colour.
The separate Navara surface and Cesium data-source preview are removed.

Cesium remains the reference for clicked heights, line width and dash,
vertex size and outline, keyboard handling and completed annotations.
One deliberate visual fix is that the occluded rubber band uses the selected
colour instead of retaining the initial amber: it now identifies the same
sketch as its visible segment. Navara adopts Cesium's geodesic preview edges.
Finished annotation drapes are unchanged.

External Cesium import files fall from 7 to 5, viewer lines from 1005 to
953, and engine-name lines from 39 to 37. No coupling metric grows.

The full unit suite, import directions, package boundaries, formatting
and coupling checks pass.

Checked in the browser, keyless: the contract suite passes on Navara and on
Cesium apart from the camera-events check that also fails intermittently
before; qa-navara-draw passes; qa-draw-tool passes apart from its hidden-line
pixel check, which fails the same way before this change. Its destroy check
now expects no preview data source, since the preview has none.
This commit is contained in:
German Khokhlov committed 2026-11-07 14:31:59 +04:00
1 parent 910d693b94
commit dacfd33f10
31 files changed
+1071 -785

No files matched your search

+46 -5
View File
@@ -10,6 +10,7 @@
// its `name` (the Entity's name, else its id): what the camera verbs say they
// are following.
import { swingFollowOffset } from './followOffset.js';
import * as Cesium from 'cesium';
import * as geo from '../../geo/index.js';
import { createEngineEvent } from '../contract.js';
@@ -200,6 +201,7 @@ export function createCesiumFollow(viewer, { commanded }) {
// Handles for entities the app tracked itself, one per entity.
const wrapped = new WeakMap();
let switching = false;
let stopExternalSwing = null;
const wrap = (entity) => {
let handle = wrapped.get(entity);
@@ -214,16 +216,36 @@ export function createCesiumFollow(viewer, { commanded }) {
stop() {
if (viewer.trackedEntity === entity) viewer.trackedEntity = undefined;
},
retarget: (next) =>
follow({
retarget(next) {
if (viewer.trackedEntity !== entity) return;
const options = normalizeFollowOptions({
native: entity,
position: () =>
displayPosition(entity, viewer.clock.currentTime, undefined),
position: handle.target,
viewFrom: () =>
entity.viewFrom?.getValue?.(viewer.clock.currentTime) ??
entity.viewFrom,
...next,
}),
});
if (!Object.keys(next).every((key) => key === 'swingTo'))
return follow(options);
watchTracking();
stopExternalSwing?.();
if (!options.swingTo) return;
const stop = swingFollowOffset(
viewer,
entity,
options.swingTo,
handle.target,
);
const offCommand = commanded.addEventListener(() =>
stopExternalSwing?.(),
);
stopExternalSwing = () => {
stop();
offCommand();
stopExternalSwing = null;
};
},
};
wrapped.set(entity, handle);
}
@@ -242,6 +264,7 @@ export function createCesiumFollow(viewer, { commanded }) {
let removeTracked = null;
const onTracked = () => {
if (switching) return;
stopExternalSwing?.();
if (own && viewer.trackedEntity !== own.entity) release(own);
followChanged.raiseEvent(following());
};
@@ -257,6 +280,8 @@ export function createCesiumFollow(viewer, { commanded }) {
// Undo what one follow put on the viewer (not trackedEntity itself).
function teardown(state) {
state.stopSwing?.();
state.stopSwing = null;
state.stopFrame?.();
state.stopFrame = null;
state.removeCommanded?.();
@@ -319,6 +344,10 @@ export function createCesiumFollow(viewer, { commanded }) {
applyTrackedCameraFrame(viewer, entity, viewFrom, {
minRange: options.minRange,
}) ?? null;
if (options.swingTo)
state.stopSwing = swingFollowOffset(viewer, entity, options.swingTo, () =>
displayPosition(entity, viewer.clock.currentTime),
);
// A command that takes the camera ends the follow; so does another
// tracked entity (Cesium raises commanded for that too).
state.removeCommanded = commanded.addEventListener(() => {
@@ -332,6 +361,7 @@ export function createCesiumFollow(viewer, { commanded }) {
function follow(input) {
const options = normalizeFollowOptions(input);
stopExternalSwing?.();
watchTracking();
if (own) {
const previous = own;
@@ -360,6 +390,16 @@ export function createCesiumFollow(viewer, { commanded }) {
retarget(next) {
if (own !== state) return;
const updated = normalizeFollowOptions({ ...state.options, ...next });
if (Object.keys(next).every((key) => key === 'swingTo')) {
state.options = updated;
state.stopSwing?.();
state.stopSwing = updated.swingTo
? swingFollowOffset(viewer, state.entity, updated.swingTo, () =>
displayPosition(state.entity, viewer.clock.currentTime),
)
: null;
return;
}
switching = true;
try {
teardown(state);
@@ -379,6 +419,7 @@ export function createCesiumFollow(viewer, { commanded }) {
return {
camera: { follow, following, followChanged },
destroy() {
stopExternalSwing?.();
if (own) {
const state = own;
if (viewer.trackedEntity === state.entity)
+41
View File
@@ -221,3 +221,44 @@ test('destroy ends an engine follow and leaves an app-tracked entity alone', ()
second.destroy();
assert.equal(second.viewer.trackedEntity, appEntity);
});
test('a swing uses the displayed target without sampling the position again', () => {
const { viewer, camera, frame } = setup();
let samples = 0;
const handle = camera.follow({
native: { gevDisplayPosition: () => TARGET },
position: () => {
samples++;
return TARGET;
},
viewFrom: { x: 0, y: -900, z: 400 },
});
frame();
handle.retarget({ swingTo: { x: 0, y: 900, z: 400 } });
const before = samples;
for (let i = 0; i < 8; i++) frame();
assert.equal(samples, before);
assert.ok(Math.abs(viewer.camera.position.y - 900) < 1e-6);
handle.stop();
});
test('an app-tracked entity swings without replacing its follow handle', () => {
const { viewer, camera, frame, destroy } = setup();
const entity = new Cesium.Entity({ position: TARGET });
viewer.trackedEntity = entity;
viewer.camera.lookAtTransform(
Cesium.Transforms.eastNorthUpToFixedFrame(TARGET),
new Cesium.Cartesian3(0, -900, 400),
);
const handle = camera.following();
handle.retarget({ swingTo: { x: 0, y: 900, z: 400 } });
for (let i = 0; i < 8; i++) frame();
assert.equal(camera.following(), handle);
assert.ok(Math.abs(viewer.camera.position.y - 900) < 1e-6);
handle.retarget({ swingTo: { x: 0, y: -900, z: 400 } });
handle.retarget({ swingTo: null });
frame();
frame();
assert.ok(Math.abs(viewer.camera.position.y - 900) < 1e-6);
destroy();
});
+70
View File
@@ -0,0 +1,70 @@
import * as Cesium from 'cesium';
import { MAX_FOLLOW_TURN, turnFollowOffset } from '../follow.js';
const MAX_FRAMES = 120;
/**
* Put the camera at a shared follow offset from `entity` once following it
* has framed the camera. Cesium keeps the offset afterwards, as it keeps one
* the user orbits to. The camera swings round the entity at most 60° a frame:
* the follow's own guard treats a jump to the far side as the camera crossing
* through the entity and puts it back. Returns a disposer.
*/
export function swingFollowOffset(viewer, entity, local, position) {
if (!viewer?.scene?.preUpdate || !entity || !local) return () => {};
let frames = 0;
let remove = null;
const stop = () => {
remove?.();
remove = null;
};
remove = viewer.scene.preUpdate.addEventListener(() => {
if (viewer.isDestroyed?.() || viewer.trackedEntity !== entity) {
stop();
return;
}
frames += 1;
const camera = viewer.camera;
// Let the follow frame the camera first (its first frame), then move it.
const framed =
frames > 1 &&
!Cesium.Matrix4.equals(camera.transform, Cesium.Matrix4.IDENTITY);
const target = framed ? position() : null;
if (!target) {
if (frames >= MAX_FRAMES) stop();
return;
}
// The offset is east/north/up at the entity; the follow's own frame may
// differ, so place the camera in world space and re-express it there.
const world = Cesium.Matrix4.multiplyByPoint(
Cesium.Transforms.eastNorthUpToFixedFrame(target),
new Cesium.Cartesian3(local.x, local.y, local.z),
new Cesium.Cartesian3(),
);
const goal = Cesium.Matrix4.multiplyByPoint(
Cesium.Matrix4.inverseTransformation(
camera.transform,
new Cesium.Matrix4(),
),
world,
new Cesium.Cartesian3(),
);
const from = Cesium.Cartesian3.clone(
camera.position,
new Cesium.Cartesian3(),
);
const angle =
Cesium.Cartesian3.magnitude(from) > 0
? Cesium.Cartesian3.angleBetween(from, goal)
: 0;
const done = !(angle > MAX_FOLLOW_TURN);
const next = done
? goal
: Cesium.Cartesian3.clone(turnFollowOffset(from, goal));
camera.lookAtTransform(camera.transform, next);
viewer.scene.requestRender?.();
if (done) stop();
});
viewer.scene.requestRender?.();
return stop;
}
+19 -2
View File
@@ -1,3 +1,4 @@
import { createExclusivePointer } from '../exclusivePointer.js';
// Screen input on one lazily created ScreenSpaceEventHandler. Cesium keeps
// one action per (type, modifier); the engine fans it out to its listeners.
@@ -53,6 +54,19 @@ export function createCesiumInput(
// setCameraInputs asked for since.
let suspended = 0;
let resumeTo = true;
const pointer = createExclusivePointer(() => {
const stock = viewer.screenSpaceEventHandler;
const saved = [TYPES.click, TYPES.doubleClick].map((type) => {
const action = stock?.getInputAction(type);
stock?.removeInputAction(type);
return [type, action];
});
return () => {
if (stock?.isDestroyed?.()) return;
for (const [type, action] of saved)
if (action) stock?.setInputAction(action, type);
};
});
const delivery = createPickDelivery({
pick: (position) => picker?.pick(position),
drill: (position, limit) => picker?.drillPick(position, limit) ?? [],
@@ -60,6 +74,7 @@ export function createCesiumInput(
});
const input = {
acquirePointer: () => pointer.acquire(),
on(type, listener, options = {}) {
const { modifier, pick, drill } = normalizeInputOptions(type, options);
if (destroyed) return () => {};
@@ -71,15 +86,16 @@ export function createCesiumInput(
groups.set(key, listeners);
handler.setInputAction(
(event) => {
const accepts = pointer.delivery();
delivery.deliver(type, toEvent(event), [...listeners], {
isLive: (entry) => listeners.has(entry),
isLive: (entry) => listeners.has(entry) && accepts(entry),
});
},
TYPES[type],
KEYS[modifier],
);
}
const entry = { listener, pick, drill };
const entry = { listener, pick, drill, pointer: options.pointer };
listeners.add(entry);
return () => {
if (!listeners.delete(entry) || listeners.size) return;
@@ -111,6 +127,7 @@ export function createCesiumInput(
return {
input,
destroy() {
pointer.destroy();
destroyed = true;
groups.clear();
handler?.destroy();
+44
View File
@@ -220,3 +220,47 @@ test('click listeners with pick and drill get the picker answers once per click'
assert.equal(hovers.length, 1);
assert.deepEqual({ ...calls.at(-1)[1] }, { x: 2, y: 0 });
});
test('exclusive pointer suppresses ambient and stock clicks, restores exact actions on destruction', () => {
const { viewer, input, destroy, handlers } = setup();
const actions = new Map();
const click = () => {};
const double = () => {};
actions.set(Type.LEFT_CLICK, click);
actions.set(Type.LEFT_DOUBLE_CLICK, double);
viewer.screenSpaceEventHandler = {
getInputAction: (type) => actions.get(type),
setInputAction: (action, type) => actions.set(type, action),
removeInputAction: (type) => actions.delete(type),
};
let ambient = 0,
owned = 0;
input.on('click', () => ambient++);
const pointer = input.acquirePointer();
assert.equal(input.acquirePointer(), null);
assert.equal(actions.size, 0);
input.on('click', () => owned++, { pointer });
handlers[0].fire(Type.LEFT_CLICK, { position: { x: 1, y: 1 } });
assert.equal(ambient, 0);
assert.equal(owned, 1);
assert.equal(input.cameraInputsEnabled(), true);
pointer.release();
pointer.release();
assert.equal(actions.get(Type.LEFT_CLICK), click);
assert.equal(actions.get(Type.LEFT_DOUBLE_CLICK), double);
handlers[0].fire(Type.LEFT_CLICK, { position: { x: 1, y: 1 } });
assert.equal(ambient, 1);
assert.equal(owned, 1, 'released subscriptions stay inert');
const next = input.acquirePointer();
pointer.release();
assert.equal(
input.acquirePointer(),
null,
'an old claim cannot release a new one',
);
destroy();
next.release();
assert.equal(actions.get(Type.LEFT_CLICK), click);
assert.equal(actions.get(Type.LEFT_DOUBLE_CLICK), double);
assert.equal(input.acquirePointer(), null);
});