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

+14 -6
View File
@@ -41,23 +41,31 @@ export function createCesiumEngine(viewer, options = {}) {
const canvas = viewer.canvas ?? viewer.scene.canvas;
const render = createCesiumRender(viewer, options);
const credits = createCesiumCredits(viewer);
// Picks name the mover set or line they hit (movers and lines exist
// below; the picker asks them when it picks).
let lines = null;
let movers = null;
const picker = createCesiumPicker(viewer, {
identify: (picked) =>
movers?.identify(picked) ?? lines?.identify(picked) ?? null,
});
const parts = {
camera: createCesiumCamera(viewer),
picker: createCesiumPicker(viewer),
picker,
projector: createCesiumProjector(viewer),
frames: createCesiumFrames(viewer),
clock: createCesiumClock(viewer, options),
lines: createCesiumLines(viewer, {
lines: (lines = createCesiumLines(viewer, {
requestRender: (reason) => render.render.request(reason),
...(options.lineFactories ? { factories: options.lineFactories } : {}),
}),
movers: createCesiumMovers(viewer, {
})),
movers: (movers = createCesiumMovers(viewer, {
requestRender: (reason) => render.render.request(reason),
...(options.moverFactories ? { factories: options.moverFactories } : {}),
}),
})),
render,
surface: createCesiumSurface(viewer),
input: createCesiumInput(viewer, options),
input: createCesiumInput(viewer, { ...options, picker: picker.picker }),
credits,
maps: createCesiumMaps(viewer, {
...options,
+20 -11
View File
@@ -2,7 +2,8 @@
// one action per (type, modifier); the engine fans it out to its listeners.
import * as Cesium from 'cesium';
import { INPUT_TYPES, MODIFIERS } from '../contract.js';
import { normalizeInputOptions } from '../contract.js';
import { createPickDelivery } from '../pickDelivery.js';
import { toGeo2 } from './convert.js';
const TYPES = {
@@ -28,26 +29,34 @@ const toEvent = (event) => {
/**
* @param {Cesium.Viewer} viewer
* @param {{ createEventHandler?: (canvas: HTMLCanvasElement) => Cesium.ScreenSpaceEventHandler }} [options]
* @param {{ createEventHandler?: (canvas: HTMLCanvasElement) => Cesium.ScreenSpaceEventHandler,
* picker?: { pick: Function, drillPick: Function },
* scheduleFrame?: (run: () => void) => void }} [options] `picker` answers
* listeners with { pick, drill } (the engine's picker); moves with picks
* wait for `scheduleFrame` (requestAnimationFrame).
* @returns {{ input: object, destroy: () => void }}
*/
export function createCesiumInput(
viewer,
{
createEventHandler = (canvas) => new Cesium.ScreenSpaceEventHandler(canvas),
picker = null,
scheduleFrame = (run) => requestAnimationFrame(run),
} = {},
) {
const { scene } = viewer;
let handler = null;
let destroyed = false;
const groups = new Map();
const delivery = createPickDelivery({
pick: (position) => picker?.pick(position),
drill: (position, limit) => picker?.drillPick(position, limit) ?? [],
schedule: (run) => scheduleFrame(() => !destroyed && run()),
});
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 () => {};
handler ??= createEventHandler(scene.canvas);
const key = `${type}:${modifier}`;
@@ -57,15 +66,15 @@ export function createCesiumInput(
groups.set(key, listeners);
handler.setInputAction(
(event) => {
const converted = toEvent(event);
for (const entry of [...listeners])
if (listeners.has(entry)) entry.listener(converted);
delivery.deliver(type, toEvent(event), [...listeners], {
isLive: (entry) => listeners.has(entry),
});
},
TYPES[type],
KEYS[modifier],
);
}
const entry = { listener };
const entry = { listener, pick, drill };
listeners.add(entry);
return () => {
if (!listeners.delete(entry) || listeners.size) return;
+58
View File
@@ -136,3 +136,61 @@ test('on() after destroy() creates no handler', () => {
destroy();
assert.equal(handlers.length, 0);
});
test('click listeners with pick and drill get the picker answers once per click', () => {
const viewer = createFakeViewer();
const handlers = createFakeEventHandlers();
const calls = [];
const picker = {
pick: (screen) => (
calls.push(['pick', screen]),
{ id: 'p', owner: 'flights', instance: 2 }
),
drillPick: (screen, limit) => (
calls.push(['drill', limit]),
[{ id: 'p' }, { id: 'q' }, { id: 'r' }].slice(0, limit)
),
};
const frames = [];
const { input } = createCesiumInput(viewer, {
createEventHandler: handlers.create,
picker,
scheduleFrame: (run) => frames.push(run),
});
const seen = [];
input.on('click', (event) => seen.push(['plain', event]));
input.on('click', (event) => seen.push(['picked', event]), {
pick: true,
drill: 2,
});
input.on('move', (event) => seen.push(['hover', event]), { pick: true });
const [handler] = handlers.handlers;
handler.fire(Type.LEFT_CLICK, { position: new Cesium.Cartesian2(4, 5) });
assert.deepEqual(
calls.map(([name, value]) => [
name,
typeof value === 'object' ? { ...value } : value,
]),
[
['pick', { x: 4, y: 5 }],
['drill', 2],
],
);
assert.equal(seen[0][1].picked, undefined);
assert.deepEqual(seen[1][1].picked, {
id: 'p',
owner: 'flights',
instance: 2,
});
assert.deepEqual(seen[1][1].drilled, [{ id: 'p' }, { id: 'q' }]);
for (const x of [1, 2])
handler.fire(Type.MOUSE_MOVE, {
startPosition: new Cesium.Cartesian2(0, 0),
endPosition: new Cesium.Cartesian2(x, 0),
});
assert.equal(frames.length, 1, 'moves coalesce into one frame');
frames[0]();
const hovers = seen.filter(([name]) => name === 'hover');
assert.equal(hovers.length, 1);
assert.deepEqual({ ...calls.at(-1)[1] }, { x: 2, y: 0 });
});
+6
View File
@@ -171,6 +171,7 @@ export function createCesiumLines(
show: shown,
asynchronous: false,
});
primitive.gevLine = options.id;
root.add(primitive);
requestRender('lines');
},
@@ -203,6 +204,11 @@ export function createCesiumLines(
});
return {
lines: registry.lines,
/** The line a Cesium pick result belongs to, or null. */
identify(picked) {
const owner = picked?.primitive?.gevLine;
return owner !== undefined && registry.live.has(owner) ? { owner } : null;
},
destroy() {
registry.destroyAll();
if (root) {
+18
View File
@@ -125,3 +125,21 @@ test('dash kinds pick their materials', () => {
assert.equal(made[2].appearance.material.type, 'Color');
assert.equal(made[2].depthFailAppearance, undefined);
});
test('a pick of a line primitive names the line', () => {
const viewer = createFakeViewer();
const { factories, made } = fakePrimitives();
const { lines, identify } = createCesiumLines(viewer, { factories });
lines
.createLine({
id: 'orbit-25544',
widthPx: 2,
color: [1, 1, 1, 1],
pickId: 'o',
})
.setPositions(points);
assert.deepEqual(identify({ primitive: made[0], id: 'o' }), {
owner: 'orbit-25544',
});
assert.equal(identify({ primitive: {}, id: 'o' }), null);
});
+16 -6
View File
@@ -85,7 +85,7 @@ function readColor(store, index) {
return scratchColor;
}
function spritePart(scene, options, store, factories, requestRender) {
function spritePart(scene, options, store, factories, requestRender, owners) {
const collection = factories.billboards(scene);
const { sprite, depthTest, id } = options;
const style = {
@@ -108,6 +108,7 @@ function spritePart(scene, options, store, factories, requestRender) {
if (!billboard) {
billboard = collection.add({ ...style });
billboards[index] = billboard;
owners.set(billboard, { owner: id, instance: index });
shownCell[index] = -1;
}
billboard.position = readPosition(store, index);
@@ -146,7 +147,7 @@ function spritePart(scene, options, store, factories, requestRender) {
};
}
function pointPart(options, store, factories, requestRender) {
function pointPart(options, store, factories, requestRender, owners) {
const collection = factories.points();
const { point, depthTest } = options;
const style = {
@@ -169,6 +170,7 @@ function pointPart(options, store, factories, requestRender) {
if (!item) {
item = collection.add({ ...style });
points[index] = item;
owners.set(item, { owner: options.id, instance: index });
}
item.position = readPosition(store, index);
item.pixelSize = point.sizePx * store.scales[index];
@@ -182,7 +184,7 @@ function pointPart(options, store, factories, requestRender) {
};
}
function modelPart(options, store, factories, requestRender) {
function modelPart(options, store, factories, requestRender, owners) {
const collection = factories.models();
const { model } = options;
const blendMode =
@@ -235,6 +237,7 @@ function modelPart(options, store, factories, requestRender) {
return;
}
models[index] = item;
owners.set(item, { owner: options.id, instance: index });
place(item, index);
collection.add(item);
requestRender('movers');
@@ -273,6 +276,8 @@ export function createCesiumMovers(
const { scene } = viewer;
let root = null;
const ordered = [];
// Billboard, point or model → its set and instance, for picks.
const owners = new WeakMap();
const rootCollection = () => {
if (!root) {
root = new Cesium.PrimitiveCollection({ destroyPrimitives: true });
@@ -283,10 +288,10 @@ export function createCesiumMovers(
const registry = createMoverRegistry((options, store) => {
const part =
options.kind === 'sprite'
? spritePart(scene, options, store, make, requestRender)
? spritePart(scene, options, store, make, requestRender, owners)
: options.kind === 'point'
? pointPart(options, store, make, requestRender)
: modelPart(options, store, make, requestRender);
? pointPart(options, store, make, requestRender, owners)
: modelPart(options, store, make, requestRender, owners);
const { primitive } = part;
primitive.gevMoverSet = options.id;
// Later (higher) order draws later: after every set of lower or equal order.
@@ -308,6 +313,11 @@ export function createCesiumMovers(
});
return {
movers: registry.movers,
/** The set and instance a Cesium pick result belongs to, or null. */
identify(picked) {
const known = picked?.primitive ? owners.get(picked.primitive) : null;
return known && registry.sets.has(known.owner) ? { ...known } : null;
},
destroy() {
registry.destroyAll();
if (root) {
+24
View File
@@ -221,3 +221,27 @@ test('models load per instance and follow position and orientation', async () =>
set.destroy();
assert.equal(models.destroyed, true);
});
test('a pick of a billboard or point names its set and instance', async () => {
const viewer = createFakeViewer();
const { factories, made } = fakeFactories();
const { movers, identify } = createCesiumMovers(viewer, { factories });
const set = movers.createSet({
id: 'sats',
kind: 'point',
capacity: 3,
point: { sizePx: 4 },
});
set.set(0, { position: at(1) });
set.set(1, { position: at(2), pickId: 25544 });
set.setCount(2);
set.commit();
const [, second] = made.find((c) => c.kind === 'points').items;
assert.deepEqual(identify({ primitive: second, id: 25544 }), {
owner: 'sats',
instance: 1,
});
assert.equal(identify({ primitive: {}, id: 'x' }), null);
set.destroy();
assert.equal(identify({ primitive: second, id: 25544 }), null);
});
+21 -11
View File
@@ -4,21 +4,31 @@
import { toCesium2, toGeo3 } from './convert.js';
const normalise = (picked) =>
picked == null
? undefined
: {
id: picked.id,
primitive: picked.primitive,
content: picked.content,
object: picked,
};
/**
* @param {Cesium.Viewer} viewer
* @param {{ identify?: (picked: object) => ({ owner: string, instance?: number } | null) }} [options]
* `identify` names the mover set or line (and instance) a pick belongs to.
* @returns {{ picker: object, destroy: () => void }}
*/
export function createCesiumPicker(viewer) {
export function createCesiumPicker(viewer, { identify = () => null } = {}) {
const normalise = (picked) => {
if (picked == null) return undefined;
const known = identify(picked);
return {
id: picked.id,
primitive: picked.primitive,
content: picked.content,
object: picked,
...(known
? {
owner: known.owner,
...(known.instance !== undefined
? { instance: known.instance }
: {}),
}
: {}),
};
};
const { scene } = viewer;
const picker = {
pick(screen, width, height) {
+21
View File
@@ -113,3 +113,24 @@ test('pickGlobe asks the globe along the camera pick ray and returns geo', () =>
scene.globe = undefined;
assert.equal(picker.pickGlobe(geo.cartesian2.create(1, 1)), undefined);
});
test('picks of movers and lines name their owner and instance', () => {
const viewer = createFakeViewer();
const billboard = { id: 'ae01ce' };
viewer.scene.pick = () => ({ primitive: billboard, id: 'ae01ce' });
viewer.scene.drillPick = () => [
{ primitive: billboard, id: 'ae01ce' },
{ primitive: {}, id: 'other' },
];
const { picker } = createCesiumPicker(viewer, {
identify: (raw) =>
raw.primitive === billboard ? { owner: 'flights', instance: 7 } : null,
});
const picked = picker.pick({ x: 1, y: 2 });
assert.equal(picked.id, 'ae01ce');
assert.equal(picked.owner, 'flights');
assert.equal(picked.instance, 7);
const drilled = picker.drillPick({ x: 1, y: 2 }, 5);
assert.equal(drilled[0].owner, 'flights');
assert.equal(drilled[1].owner, undefined);
});