feat(globe): picks on input payloads

input.on('click'|'doubleClick'|'move', fn, { pick, drill }) delivers
{ …event, picked, drilled }: PickResult { id, owner, instance, primitive
(Cesium) } names the mover set (and instance) or line hit. One pick (and
one drill, as deep as the deepest listener) per event, shared by its
listeners; moves with picks are coalesced to one delivery per frame with
the latest position (src/globe/pickDelivery.js). Option checks in the
contract (normalizeInputOptions).

- Cesium: scene.pick / drillPick, and the picker names the owner: movers
  map billboards, points and models to their set and instance, lines
  their primitives to the line.
- Navara: a click with pick takes Navara's GPU pick of the same gesture
  (featureClick; its pick helper answers on the same pointerup, usually
  before the engine's click, so a fresh answer waits for it; otherwise
  the click waits up to 250 ms, then the CPU pick). Navara 0.2.1 answers
  clicks in quick succession with the first click's pick: a GPU answer
  whose instance is not drawn near the click is stale and the CPU pick
  answers. Hover, drill and the synchronous picker.pick/drillPick are CPU
  picks (src/globe/cpuPicks.js) of pickable mover sets and pickable lines
  (within half the width + 3 px), behind the globe excluded, nearest
  first; lines are picked on the CPU after an empty GPU answer.
  picker.clickStats() (Navara only) counts the answers and latencies.
- The fake engine picks its own movers and lines on the CPU unless
  scripted.
- The contract suite clicks with real pointer events (puppeteer) on both
  engines: a sprite is picked with its owner and instance, the map picks
  nothing, two sprites in one place drill both, a line is picked, a
  hover picks the sprite under it. Navara, 20 clicks: payload p50 2.8 ms,
  p95 4.1 ms after the click (puppeteer dispatch included), 20/20 GPU
  answers. The Cesium harness keeps the first-run card closed.
This commit is contained in:
German Khokhlov committed 2026-10-16 18:25:12 +04:00
1 parent 86aa0bc9ba
commit b0cb8ce881
26 files changed
+1267 -68

No files matched your search

+23 -4
View File
@@ -17,6 +17,7 @@ import { createCameraModel } from './cameraModel.js';
import { createNavaraClock } from './clock.js';
import { createNavaraCredits } from './credits.js';
import { createNavaraInput } from './input.js';
import { createNavaraPicking } from './picking.js';
import { createNavaraMaps } from './maps.js';
import { createNavaraSurface } from './surface.js';
import { createGroundFloor, GROUND_FLOOR } from './groundFloor.js';
@@ -163,9 +164,24 @@ export function createNavaraEngine(
for (const [name, handler] of Object.entries(handlers))
view.on(name, handler);
// Picks over the movers and lines (picking.js); the input answers
// listeners with { pick, drill } from it.
const picking = createNavaraPicking({
view,
projector: {
worldToWindow: (position, result) =>
model.worldToWindow(position, result),
horizonVisible: (position) => model.horizonVisible(position),
},
camera: model.camera,
movers: () => moversPort?.pickables?.() ?? [],
lines: () => linesPort?.pickables?.() ?? [],
resolveBatch: (batchId) => moversPort?.resolvePick?.(batchId) ?? null,
});
const input = createNavaraInput(view, {
// A gesture is the user, not a new camera owner: no camera.commanded.
onCameraInput: () => model.stopFlight(),
picker: picking,
});
const credits = createNavaraCredits(view);
const maps = createNavaraMaps(view, fetch ? { fetch } : {});
@@ -182,10 +198,12 @@ export function createNavaraEngine(
});
const picker = {
// Navara picks its own meshes only on click gestures (featureClick); there
// is no synchronous pick, and 3D tiles carry no ids. No layers yet.
pick: () => undefined,
drillPick: () => [],
// The CPU pick of movers and lines (picking.js); 3D tiles carry no ids.
// Clicks with { pick } get Navara's GPU pick of the gesture instead.
pick: (screen) => picking.pick(screen),
drillPick: (screen, limit) => picking.drillPick(screen, limit),
// Navara-only diagnostics: how clicks with { pick } were answered.
clickStats: () => picking.clickStats(),
pickPosition(screen) {
const rect = canvas.getBoundingClientRect();
const hit = view.pickDepthPosition(
@@ -262,6 +280,7 @@ export function createNavaraEngine(
view.off(name, handler);
model.destroy();
input.destroy();
picking.destroy();
credits.destroy();
maps.destroy();
sharpenPort?.destroy();
+31 -12
View File
@@ -8,7 +8,8 @@
// Navara 0.2.1 lets a flyTo run on under user input, where Cesium cancels it;
// `onCameraInput` reports user camera input so the engine can do the same.
import { INPUT_TYPES, MODIFIERS } from '../contract.js';
import { INPUT_TYPES, normalizeInputOptions } from '../contract.js';
import { createPickDelivery } from '../pickDelivery.js';
const CLICK_PIXEL_TOLERANCE = 5; // Cesium's _clickPixelTolerance
const SCREEN_EVENTS = ['pointerdown', 'pointerup', 'pointermove', 'dblclick'];
@@ -23,10 +24,21 @@ function modifierOf(event) {
/**
* @param {{ canvas: HTMLCanvasElement, camera: { options: object } }} view
* @param {{ onCameraInput?: (type: string) => void }} [options]
* @param {{ onCameraInput?: (type: string) => void,
* picker?: { clickPick: Function, pick: Function, drillPick: Function },
* scheduleFrame?: (run: () => void) => void }} [options] `picker`
* answers listeners with { pick, drill } (picking.js): clicks from the
* GPU pick of the gesture, moves from the CPU pick once a frame.
* @returns {{ input: object, destroy: () => void }}
*/
export function createNavaraInput(view, { onCameraInput = () => {} } = {}) {
export function createNavaraInput(
view,
{
onCameraInput = () => {},
picker = null,
scheduleFrame = (run) => requestAnimationFrame(run),
} = {},
) {
const { canvas } = view;
const listeners = new Map(INPUT_TYPES.map((type) => [type, new Set()]));
let attached = false;
@@ -36,15 +48,25 @@ export function createNavaraInput(view, { onCameraInput = () => {} } = {}) {
let downAt = null;
let last = null;
const delivery = createPickDelivery({
pick: (position, type) =>
type === 'move' ? picker?.pick(position) : picker?.clickPick(position),
drill: (position, limit) => picker?.drillPick(position, limit) ?? [],
schedule: (run) => scheduleFrame(() => !destroyed && run()),
});
const positionOf = (event) => {
const rect = canvas.getBoundingClientRect();
return { x: event.clientX - rect.left, y: event.clientY - rect.top };
};
const emit = (type, event, payload) => {
const modifier = modifierOf(event);
for (const entry of [...listeners.get(type)])
if (entry.modifier === modifier && listeners.get(type).has(entry))
entry.listener(payload);
const group = listeners.get(type);
delivery.deliver(
type,
payload,
[...group].filter((entry) => entry.modifier === modifier),
{ isLive: (entry) => group.has(entry) },
);
};
const onScreenEvent = (event) => {
@@ -90,18 +112,15 @@ export function createNavaraInput(view, { onCameraInput = () => {} } = {}) {
});
const input = {
on(type, listener, { modifier } = {}) {
if (!INPUT_TYPES.includes(type))
throw new TypeError(`Unknown input type: ${type}`);
if (modifier !== undefined && !MODIFIERS.includes(modifier))
throw new TypeError(`Unknown input modifier: ${modifier}`);
on(type, listener, options = {}) {
const { modifier, pick, drill } = normalizeInputOptions(type, options);
if (destroyed) return () => {};
if (!attached) {
attached = true;
for (const name of SCREEN_EVENTS)
canvas.addEventListener(name, onScreenEvent);
}
const entry = { listener, modifier };
const entry = { listener, modifier, pick, drill };
listeners.get(type).add(entry);
return () => {
listeners.get(type).delete(entry);
+35
View File
@@ -165,3 +165,38 @@ test('setCameraInputs merges into the camera options set through the engine', ()
enableTilt: false,
});
});
test('clicks with pick wait for the click pick; moves with pick use the CPU pick once a frame', async () => {
const canvas = fakeCanvas();
const frames = [];
const calls = [];
const view = { canvas, camera: { set options(value) {} } };
const { input } = createNavaraInput(view, {
picker: {
clickPick: async (at) => (calls.push(['click', at]), { id: 'gpu' }),
pick: (at) => (calls.push(['cpu', at]), { id: 'cpu' }),
drillPick: (at, limit) => (
calls.push(['drill', limit]),
[{ id: 'a' }, { id: 'b' }]
),
},
scheduleFrame: (run) => frames.push(run),
});
const seen = [];
input.on('click', (event) => seen.push(['click', event]), {
pick: true,
drill: 1,
});
input.on('move', (event) => seen.push(['move', event]), { pick: true });
canvas.dispatchEvent(pointer('pointerdown', 110, 60));
canvas.dispatchEvent(pointer('pointerup', 110, 60));
await new Promise((resolve) => setTimeout(resolve, 0));
assert.deepEqual(seen[0][1].picked, { id: 'gpu' });
assert.deepEqual(seen[0][1].drilled, [{ id: 'a' }]);
canvas.dispatchEvent(pointer('pointermove', 120, 70));
canvas.dispatchEvent(pointer('pointermove', 121, 71));
assert.equal(frames.length, 1);
frames[0]();
assert.deepEqual(seen.at(-1)[1].picked, { id: 'cpu' });
assert.deepEqual(calls.at(-1), ['cpu', { x: 21, y: 21 }]);
});
+23 -4
View File
@@ -47,16 +47,24 @@ export function createNavaraLines(view) {
registered.add(view);
}
const request = () => view.forceUpdate();
// What CPU picks need of each line: its drawn positions and matrix.
const drawn = new Map();
const registry = createLineRegistry((options) => {
const line = createLineMesh(options);
const state = {
options,
flat: new Float64Array(0),
modelMatrix: options.modelMatrix,
shown: true,
};
drawn.set(options.id, state);
const canvas = view.canvas;
if (canvas) line.update(canvas.clientWidth || 1, canvas.clientHeight || 1);
const handle = view.addMesh({ lit: false, [DESC_NAME]: { line } });
return {
setPositions(flat) {
line.setPositions(
options.arc === 'geodesic' ? densifyGeodesic(flat) : flat,
);
state.flat = options.arc === 'geodesic' ? densifyGeodesic(flat) : flat;
line.setPositions(state.flat);
request();
},
setColor(rgba) {
@@ -64,18 +72,29 @@ export function createNavaraLines(view) {
request();
},
setModelMatrix(matrix) {
state.modelMatrix = matrix;
line.setModelMatrix(matrix);
request();
},
show(visible) {
state.shown = visible;
line.show(visible);
request();
},
destroy() {
drawn.delete(options.id);
handle.delete();
request();
},
};
});
return { lines: registry.lines, destroy: () => registry.destroyAll() };
return {
lines: registry.lines,
/** Shown lines with a pickId: options, drawn positions, matrix. */
pickables: () =>
[...drawn.values()].filter(
(state) => state.shown && state.options.pickId !== undefined,
),
destroy: () => registry.destroyAll(),
};
}
+6
View File
@@ -138,6 +138,12 @@ export function createNavaraMovers(view) {
return {
movers: registry.movers,
resolvePick: (batchId) => pickIndex.resolve(batchId),
/** The live sets' options and stores, for CPU picks. */
pickables: () =>
[...registry.sets.values()].map(({ options, store }) => ({
options,
store,
})),
destroy: () => registry.destroyAll(),
};
}
+118
View File
@@ -0,0 +1,118 @@
// Picks on Navara. A click is answered by Navara's own GPU pick of the same
// gesture (`featureClick`, a frame or two after the click, null over empty
// space): its batch id resolves to the mover set and instance (pickIds.js).
// Lines are not in the GPU pick, so an empty GPU answer still checks them
// on the CPU; no answer within the timeout falls back to the CPU pick.
// Hover (move with pick), drill and the synchronous picker.pick are CPU
// picks (src/globe/cpuPicks.js). No three.
import { createCpuPicker } from '../cpuPicks.js';
export { distanceToSegment } from '../cpuPicks.js';
const CLICK_TIMEOUT_MS = 250;
// A GPU answer this recent belongs to the click being delivered.
const EARLY_ANSWER_MS = 100;
/**
* @param {{
* view: { on: Function, off: Function },
* projector: { worldToWindow: Function, horizonVisible: Function },
* camera: { livePosition: object },
* movers: () => { options: object, store: object }[],
* lines: () => { options: object, flat: Float64Array, modelMatrix: number[] | null }[],
* resolveBatch: (batchId: number) => ({ set: string, instance: number, pickId: any } | null),
* setTimeout?: Function, clearTimeout?: Function, timeoutMs?: number,
* }} ports
*/
export function createNavaraPicking({
view,
projector,
camera,
movers,
lines,
resolveBatch,
setTimeout: later = globalThis.setTimeout,
clearTimeout: cancel = globalThis.clearTimeout,
timeoutMs = CLICK_TIMEOUT_MS,
now = () => performance.now(),
}) {
const drillPick = createCpuPicker({ projector, camera, movers, lines });
// Clicks waiting for Navara's GPU answer, oldest first.
const waiting = [];
// Diagnostics: how clicks were answered and how long it took (ms).
const stats = { gpu: 0, timeout: 0, stale: 0, latencies: [] };
const answered = (entry, how) => {
stats[how]++;
stats.latencies.push(now() - entry.startedAt);
if (stats.latencies.length > 200) stats.latencies.shift();
};
// Navara 0.2.1 answers clicks in quick succession (within a frame or so)
// with the first click's pick: a GPU answer whose instance is not drawn
// near the click is stale, and the CPU pick answers instead.
const answerFrom = (info, at) => {
const hit = info ? resolveBatch(info.batchId) : null;
if (hit && !drillPick.near(hit.set, hit.instance, at)) {
stats.stale++;
return drillPick(at, 1)[0];
}
return hit
? { id: hit.pickId, owner: hit.set, instance: hit.instance }
: drillPick(at, 1, { includeMovers: false })[0];
};
// Navara's pick helper listens to the same pointerup and, registered
// first, usually answers before the engine's click: that answer waits
// here, for the click of the same gesture.
let early = null;
const onFeatureClick = (info) => {
const next = waiting.shift();
if (!next) {
early = { info, at: now() };
return;
}
cancel(next.timer);
answered(next, 'gpu');
next.resolve(answerFrom(info, next.at));
};
view.on('featureClick', onFeatureClick);
return {
pick: (at) => drillPick(at, 1)[0],
drillPick: (at, limit) => drillPick(at, limit ?? Infinity),
/** The answer for a click at `at`: the GPU pick of its gesture. */
clickPick(at) {
const gesture = early;
early = null;
if (gesture && now() - gesture.at <= EARLY_ANSWER_MS) {
const entry = { startedAt: gesture.at };
answered(entry, 'gpu');
return Promise.resolve(answerFrom(gesture.info, at));
}
return new Promise((resolve) => {
const entry = {
at: { x: at.x, y: at.y },
resolve,
timer: null,
startedAt: now(),
};
entry.timer = later(() => {
const index = waiting.indexOf(entry);
if (index >= 0) waiting.splice(index, 1);
answered(entry, 'timeout');
resolve(drillPick(entry.at, 1)[0]);
}, timeoutMs);
waiting.push(entry);
});
},
/** How clicks were answered: GPU picks, timeouts, recent latencies (ms). */
clickStats: () => ({ ...stats, latencies: [...stats.latencies] }),
destroy() {
view.off('featureClick', onFeatureClick);
for (const entry of waiting.splice(0)) {
cancel(entry.timer);
entry.resolve(undefined);
}
},
};
}
+251
View File
@@ -0,0 +1,251 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { createMoverStore, normalizeMoverSetOptions } from '../movers.js';
import { normalizeLineOptions } from '../lines.js';
import { createNavaraPicking, distanceToSegment } from './picking.js';
// A projector that maps x → screen x and y → screen y, z is the depth (the
// distance from the camera at the origin along +z).
const projector = {
worldToWindow: (p) => ({ x: p.x, y: p.y }),
horizonVisible: (p) => p.z > 0,
};
const camera = { livePosition: { x: 0, y: 0, z: 0 } };
function moverSet(id, rows, { pickable = true, sizePx = 20 } = {}) {
const options = normalizeMoverSetOptions({
id,
kind: 'point',
capacity: rows.length,
pickable,
point: { sizePx },
});
const store = createMoverStore(options);
rows.forEach(([x, y, z, pickId], index) =>
store.set(index, { position: { x, y, z }, pickId }),
);
store.setCount(rows.length);
return { options, store };
}
function fakeView() {
const handlers = new Map();
return {
on(name, fn) {
handlers.set(name, fn);
},
off(name) {
handlers.delete(name);
},
emit(name, value) {
handlers.get(name)?.(value);
},
handlers,
};
}
const timers = () => {
const pending = [];
return {
pending,
setTimeout: (fn, ms) => {
const timer = { fn, ms };
pending.push(timer);
return timer;
},
clearTimeout: (timer) => {
const index = pending.indexOf(timer);
if (index >= 0) pending.splice(index, 1);
},
};
};
test('the distance from a point to a segment', () => {
assert.equal(
distanceToSegment({ x: 5, y: 3 }, { x: 0, y: 0 }, { x: 10, y: 0 }),
3,
);
assert.equal(
distanceToSegment({ x: -4, y: 3 }, { x: 0, y: 0 }, { x: 10, y: 0 }),
5,
);
});
test('CPU picks: pickable sets and lines under a point, nearest first', () => {
const sets = [
moverSet('flights', [
[100, 100, 500, 'far'],
[104, 100, 50, 'near'],
[300, 300, 10, 'elsewhere'],
]),
moverSet('hidden', [[100, 100, -5, 'behind-the-globe']]),
moverSet('quiet', [[100, 100, 20, 'not-pickable']], { pickable: false }),
];
const line = {
options: normalizeLineOptions({
id: 'orbit',
widthPx: 4,
color: [1, 1, 1, 1],
pickId: 'orbit-1',
}),
flat: new Float64Array([90, 103, 200, 110, 103, 200]),
modelMatrix: null,
};
const picking = createNavaraPicking({
view: fakeView(),
projector,
camera,
movers: () => sets,
lines: () => [line],
resolveBatch: () => null,
});
const drilled = picking.drillPick({ x: 100, y: 100 }, 8);
assert.deepEqual(
drilled.map(({ id, owner }) => [id, owner]),
[
['near', 'flights'],
['orbit-1', 'orbit'],
['far', 'flights'],
],
);
assert.equal(drilled[0].instance, 1);
assert.deepEqual(picking.pick({ x: 100, y: 100 }).id, 'near');
assert.equal(picking.pick({ x: 600, y: 600 }), undefined);
assert.equal(picking.drillPick({ x: 100, y: 100 }, 1).length, 1);
});
test('a click takes the GPU pick of its gesture, a batch id resolved to the instance', async () => {
const view = fakeView();
const clock = timers();
const picking = createNavaraPicking({
view,
projector,
camera,
movers: () => [],
lines: () => [],
resolveBatch: (batchId) =>
batchId === 42 ? { set: 'flights', instance: 3, pickId: 'ae01ce' } : null,
...clock,
});
const answer = picking.clickPick({ x: 1, y: 1 });
view.emit('featureClick', { batchId: 42 });
assert.deepEqual(await answer, {
id: 'ae01ce',
owner: 'flights',
instance: 3,
});
assert.equal(clock.pending.length, 0, 'the timeout is cleared');
// Empty space: Navara reports null; a CPU line pick could still answer.
const empty = picking.clickPick({ x: 1, y: 1 });
view.emit('featureClick', null);
assert.equal(await empty, undefined);
});
test('without a GPU answer in time the click falls back to the CPU pick', async () => {
const view = fakeView();
const clock = timers();
const sets = [moverSet('flights', [[10, 10, 5, 'cpu']])];
const picking = createNavaraPicking({
view,
projector,
camera,
movers: () => sets,
lines: () => [],
resolveBatch: () => null,
...clock,
});
const answer = picking.clickPick({ x: 10, y: 10 });
assert.equal(clock.pending.length, 1);
clock.pending[0].fn();
assert.deepEqual(await answer, { id: 'cpu', owner: 'flights', instance: 0 });
picking.destroy();
assert.equal(view.handlers.size, 0);
});
test('click stats count GPU answers and timeouts with their latency', async () => {
const view = fakeView();
const clock = timers();
let time = 0;
const picking = createNavaraPicking({
view,
projector,
camera,
movers: () => [],
lines: () => [],
resolveBatch: () => null,
now: () => time,
...clock,
});
const first = picking.clickPick({ x: 0, y: 0 });
time = 30;
view.emit('featureClick', null);
await first;
const second = picking.clickPick({ x: 0, y: 0 });
time = 280;
clock.pending[0].fn();
await second;
assert.deepEqual(picking.clickStats(), {
gpu: 1,
timeout: 1,
stale: 0,
latencies: [30, 250],
});
});
test("Navara's answer may come before the engine's click of the same gesture", async () => {
const view = fakeView();
const clock = timers();
let time = 1000;
const picking = createNavaraPicking({
view,
projector,
camera,
movers: () => [],
lines: () => [],
resolveBatch: (batchId) =>
batchId === 7 ? { set: 'sats', instance: 0, pickId: 25544 } : null,
now: () => time,
...clock,
});
view.emit('featureClick', { batchId: 7 });
time += 2;
assert.deepEqual(await picking.clickPick({ x: 0, y: 0 }), {
id: 25544,
owner: 'sats',
instance: 0,
});
assert.equal(clock.pending.length, 0);
// A stale answer (a click no listener took) is not reused.
view.emit('featureClick', { batchId: 7 });
time += 500;
const late = picking.clickPick({ x: 0, y: 0 });
assert.equal(clock.pending.length, 1);
view.emit('featureClick', null);
assert.equal(await late, undefined);
});
test('a GPU answer naming an instance drawn far from the click is stale', async () => {
const view = fakeView();
const sets = [
moverSet('flights', [
[10, 10, 5, 'drawn-here'],
[400, 400, 5, 'far-away'],
]),
];
const picking = createNavaraPicking({
view,
projector,
camera,
movers: () => sets,
lines: () => [],
resolveBatch: (batchId) =>
batchId === 2
? { set: 'flights', instance: 1, pickId: 'far-away' }
: null,
...timers(),
});
const answer = picking.clickPick({ x: 10, y: 10 });
view.emit('featureClick', { batchId: 2 });
assert.equal((await answer).id, 'drawn-here');
assert.equal(picking.clickStats().stale, 1);
});