feat(globe): instanced movers on both engines

engine.movers.createSet({ id, kind: sprite|point|model, capacity, order,
depthTest, sprite|point|model, pickable }) → a MoverSet: set(index,
fields) stores an instance (position, screen rotation, orientation, rgba,
scale, atlas cell, show, pickId) in flat arrays, commit() uploads the
changed range once and requests one render, positionsView() reads the
positions, destroy() removes it; movers.list() for QA. The options, the
store and the registry are engine-neutral (src/globe/movers.js); the fake
engine keeps them for layer tests.

- Cesium: one primitive per set in an engine-owned PrimitiveCollection
  added with the first set, in `order`: sprites a BillboardCollection
  (one image per atlas cell, NearFarScalar, disableDepthTestDistance),
  points a PointPrimitiveCollection, models a Model per instance.
- Navara: a public MeshDesc per set. Sprites and points are one
  InstancedMesh of a quad, faced to the screen and sized in CSS pixels in
  the vertex shader from uniforms (the pick pass draws the same
  footprint), atlas uv, rotation, colour and scale per instance, drawn in
  the transparent pass unlit; offsets from an origin that follows the
  camera past max(1 km, 10 % of its height). Models: the glTF once, one
  InstancedMesh per mesh, minimumPixelSize/maximumScale on the CPU per
  drawn frame, colorBlend in the shader. Pickable sets register a
  PickableInstancedMeshWrapper; pickIds.js maps batch ids back to
  instances (used by Task 4).
- The contract suite draws three 24 px sprites on both engines: centred
  within 2 px of worldToWindow, hidden by show:false, recoloured, gone on
  destroy, and no frames added once the commit has drawn.
- qa-engine-bench --scenario=movers: 10 000 synthetic aircraft
  (src/bench/syntheticFlights.js, moved from the Navara spike with its
  test), every instance moved and committed every frame. p95 Navara
  (look=minimal) / Cesium: global 5.2/7.0 ms, city 5.6/9.9, orbit 6.0/7.4
  (0.74, 0.57, 0.81; gate 1.1). Cesium is measured without its 60 fps cap.

Main chunk 2,860,302 bytes (+9,706, +0.34 %: the Cesium movers).
This commit is contained in:
German Khokhlov committed 2026-10-16 17:15:24 +04:00
1 parent 4623c8b616
commit 0109097440
24 files changed
+2735 -3

No files matched your search

+5
View File
@@ -11,6 +11,7 @@ import { createCesiumCredits } from './credits.js';
import { createCesiumFrames } from './frames.js';
import { createCesiumInput } from './input.js';
import { createCesiumMaps } from './maps.js';
import { createCesiumMovers } from './movers.js';
import { createCesiumPicker } from './picker.js';
import { createCesiumProjector } from './projector.js';
import { createCesiumRender } from './render.js';
@@ -45,6 +46,10 @@ export function createCesiumEngine(viewer, options = {}) {
projector: createCesiumProjector(viewer),
frames: createCesiumFrames(viewer),
clock: createCesiumClock(viewer, options),
movers: createCesiumMovers(viewer, {
requestRender: (reason) => render.render.request(reason),
...(options.moverFactories ? { factories: options.moverFactories } : {}),
}),
render,
surface: createCesiumSurface(viewer),
input: createCesiumInput(viewer, options),
+319
View File
@@ -0,0 +1,319 @@
// engine.movers on Cesium: one primitive per set inside one engine-owned
// PrimitiveCollection (added to the scene with the first set, in `order`):
// sprites are a BillboardCollection (screen-aligned, rotation in screen
// space, an image per atlas cell), points a PointPrimitiveCollection,
// models one Model per instance in a PrimitiveCollection. commit() writes
// the changed instances and requests a render; nothing else renders.
import * as Cesium from 'cesium';
import { createMoverRegistry } from '../movers.js';
const scratchPosition = new Cesium.Cartesian3();
const scratchColor = new Cesium.Color();
const scratchQuaternion = new Cesium.Quaternion();
const scratchRotation = new Cesium.Matrix3();
/** The atlas cells as canvases, by key (a DOM canvas or image source). */
async function cropAtlasCells(atlas, keys) {
let image = atlas.canvas;
if (!image) {
image = new Image();
image.crossOrigin = 'anonymous';
image.src = atlas.url;
await image.decode();
}
const width = image.width;
const height = image.height;
const cells = new Map();
for (const key of keys) {
const [u0, v0, u1, v1] = atlas.cells[key];
const canvas = document.createElement('canvas');
canvas.width = Math.max(1, Math.round((u1 - u0) * width));
canvas.height = Math.max(1, Math.round((v1 - v0) * height));
canvas
.getContext('2d')
.drawImage(
image,
u0 * width,
v0 * height,
canvas.width,
canvas.height,
0,
0,
canvas.width,
canvas.height,
);
cells.set(key, canvas);
}
return cells;
}
const DEFAULT_FACTORIES = {
billboards: (scene) => new Cesium.BillboardCollection({ scene }),
points: () => new Cesium.PointPrimitiveCollection(),
models: () => new Cesium.PrimitiveCollection({ destroyPrimitives: true }),
loadModel: (options) => Cesium.Model.fromGltfAsync(options),
cropCells: cropAtlasCells,
};
const depthTestDistance = (depthTest) =>
depthTest === 'always'
? Number.POSITIVE_INFINITY
: depthTest === 'normal'
? 0
: depthTest.disableWithinM;
const nearFar = (value) =>
value ? new Cesium.NearFarScalar(...value) : undefined;
function readPosition(store, index) {
const { positions } = store;
return Cesium.Cartesian3.fromElements(
positions[index * 3],
positions[index * 3 + 1],
positions[index * 3 + 2],
scratchPosition,
);
}
function readColor(store, index) {
const { colors } = store;
scratchColor.red = colors[index * 4];
scratchColor.green = colors[index * 4 + 1];
scratchColor.blue = colors[index * 4 + 2];
scratchColor.alpha = colors[index * 4 + 3];
return scratchColor;
}
function spritePart(scene, options, store, factories, requestRender) {
const collection = factories.billboards(scene);
const { sprite, depthTest, id } = options;
const style = {
width: sprite.sizePx,
height: sprite.sizePx,
scaleByDistance: nearFar(sprite.scaleByDistance),
disableDepthTestDistance: depthTestDistance(depthTest),
};
const billboards = [];
const shownCell = [];
let cells = null;
let destroyed = false;
const apply = (from, to) => {
for (let index = from; index < to; index++) {
let billboard = billboards[index];
if (index >= store.count) {
if (billboard) billboard.show = false;
continue;
}
if (!billboard) {
billboard = collection.add({ ...style });
billboards[index] = billboard;
shownCell[index] = -1;
}
billboard.position = readPosition(store, index);
billboard.rotation = store.rotations[index];
billboard.scale = store.scales[index];
billboard.color = readColor(store, index);
billboard.show = store.shows[index] === 1;
billboard.id = store.pickIds[index];
const cell = store.cells[index];
if (shownCell[index] !== cell) {
const key = store.cellKeys[cell];
billboard.setImage(`${id}:${key}`, cells.get(key));
shownCell[index] = cell;
}
}
};
// Instances wait for the atlas; then everything drawn so far is applied.
factories
.cropCells(sprite.atlas, store.cellKeys)
.then((ready) => {
if (destroyed) return;
cells = ready;
apply(0, Math.max(store.count, billboards.length));
requestRender('movers');
})
.catch((error) => console.warn(`[movers] ${id}: atlas failed`, error));
return {
primitive: collection,
commit(range) {
if (cells && range) apply(range.from, range.to);
requestRender('movers');
},
destroy() {
destroyed = true;
},
};
}
function pointPart(options, store, factories, requestRender) {
const collection = factories.points();
const { point, depthTest } = options;
const style = {
outlineWidth: point.outlinePx,
outlineColor: Cesium.Color.BLACK,
scaleByDistance: nearFar(point.scaleByDistance),
disableDepthTestDistance: depthTestDistance(depthTest),
};
const points = [];
return {
primitive: collection,
commit(range) {
if (range)
for (let index = range.from; index < range.to; index++) {
let item = points[index];
if (index >= store.count) {
if (item) item.show = false;
continue;
}
if (!item) {
item = collection.add({ ...style });
points[index] = item;
}
item.position = readPosition(store, index);
item.pixelSize = point.sizePx * store.scales[index];
item.color = readColor(store, index);
item.show = store.shows[index] === 1;
item.id = store.pickIds[index];
}
requestRender('movers');
},
destroy() {},
};
}
function modelPart(options, store, factories, requestRender) {
const collection = factories.models();
const { model } = options;
const blendMode =
model.colorBlend?.mode === 'replace'
? Cesium.ColorBlendMode.REPLACE
: Cesium.ColorBlendMode.MIX;
const models = [];
const loading = [];
let destroyed = false;
const place = (item, index) => {
const { orientations } = store;
scratchQuaternion.x = orientations[index * 4];
scratchQuaternion.y = orientations[index * 4 + 1];
scratchQuaternion.z = orientations[index * 4 + 2];
scratchQuaternion.w = orientations[index * 4 + 3];
item.modelMatrix = Cesium.Matrix4.fromRotationTranslation(
Cesium.Matrix3.fromQuaternion(scratchQuaternion, scratchRotation),
readPosition(store, index),
new Cesium.Matrix4(),
);
item.scale = store.scales[index];
item.show = index < store.count && store.shows[index] === 1;
item.id = store.pickIds[index];
if (model.colorBlend)
item.color = Cesium.Color.clone(readColor(store, index));
};
const ensure = (index) => {
if (models[index] || loading[index]) return;
loading[index] = true;
factories
.loadModel({
url: model.url,
minimumPixelSize: model.minimumPixelSize,
maximumScale: Number.isFinite(model.maximumScale)
? model.maximumScale
: undefined,
colorBlendMode: blendMode,
colorBlendAmount: model.colorBlend?.amount ?? 0.5,
...(model.unlit
? {
customShader: new Cesium.CustomShader({
lightingModel: Cesium.LightingModel.UNLIT,
}),
}
: {}),
})
.then((item) => {
if (destroyed) {
item.destroy?.();
return;
}
models[index] = item;
place(item, index);
collection.add(item);
requestRender('movers');
})
.catch((error) =>
console.warn(`[movers] ${options.id}: model failed`, error),
);
};
return {
primitive: collection,
commit(range) {
if (range)
for (let index = range.from; index < range.to; index++) {
if (index < store.count) ensure(index);
if (models[index]) place(models[index], index);
}
requestRender('movers');
},
destroy() {
destroyed = true;
},
};
}
/**
* @param {Cesium.Viewer} viewer
* @param {{ requestRender?: (reason: string) => void, factories?: object }} [options]
* `factories` (collections, model loading, atlas cropping) is a test seam.
* @returns {{ movers: import('../contract.js').GlobeMovers, destroy: () => void }}
*/
export function createCesiumMovers(
viewer,
{ requestRender = () => viewer.scene.requestRender(), factories = {} } = {},
) {
const make = { ...DEFAULT_FACTORIES, ...factories };
const { scene } = viewer;
let root = null;
const ordered = [];
const rootCollection = () => {
if (!root) {
root = new Cesium.PrimitiveCollection({ destroyPrimitives: true });
scene.primitives.add(root);
}
return root;
};
const registry = createMoverRegistry((options, store) => {
const part =
options.kind === 'sprite'
? spritePart(scene, options, store, make, requestRender)
: options.kind === 'point'
? pointPart(options, store, make, requestRender)
: modelPart(options, store, make, requestRender);
const { primitive } = part;
primitive.gevMoverSet = options.id;
// Later (higher) order draws later: after every set of lower or equal order.
const at = ordered.filter((entry) => entry.order <= options.order).length;
ordered.splice(at, 0, { order: options.order, primitive });
rootCollection().add(primitive, at);
return {
commit: () => part.commit(store.dirty()),
destroy() {
part.destroy();
ordered.splice(
ordered.findIndex((entry) => entry.primitive === primitive),
1,
);
root.remove(primitive);
requestRender('movers');
},
};
});
return {
movers: registry.movers,
destroy() {
registry.destroyAll();
if (root) {
scene.primitives.remove(root);
root = null;
}
},
};
}
+223
View File
@@ -0,0 +1,223 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import { createCesiumMovers } from './movers.js';
import { createFakeViewer } from './testing/fakeViewer.mjs';
// Collections that keep what the engine gives them (Cesium's own need a
// WebGL scene to add billboards).
function fakeFactories() {
const made = [];
const collection = (kind) => {
const items = [];
const value = {
kind,
items,
show: true,
add(options) {
// Cesium's billboards and points copy positions and colours.
let position;
let color;
const item = {
...options,
get position() {
return position;
},
set position(value) {
position = Cesium.Cartesian3.clone(value);
},
get color() {
return color;
},
set color(value) {
color = Cesium.Color.clone(value);
},
images: [],
setImage(id, image) {
this.images.push(id);
this.image = image;
},
};
items.push(item);
return item;
},
remove(item) {
items.splice(items.indexOf(item), 1);
return true;
},
get length() {
return items.length;
},
isDestroyed: () => false,
destroy() {
value.destroyed = true;
},
};
made.push(value);
return value;
};
return {
made,
factories: {
billboards: () => collection('billboards'),
points: () => collection('points'),
models: () => collection('models'),
loadModel: async (options) => ({ ...options, loaded: true }),
cropCells: async (atlas, keys) =>
new Map(keys.map((key) => [key, { cell: key }])),
},
};
}
const atlas = {
canvas: { width: 64, height: 32 },
cells: { jet: [0, 0, 0.5, 1], heli: [0.5, 0, 1, 1] },
};
const at = (x) => ({ x, y: 0, z: 6_400_000 });
const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
test('creating the movers changes nothing; the first set adds one root collection', () => {
const viewer = createFakeViewer();
const { factories } = fakeFactories();
const { movers, destroy } = createCesiumMovers(viewer, { factories });
assert.equal(viewer.scene.primitives.length, 0);
movers.createSet({
id: 'a',
kind: 'point',
capacity: 2,
point: { sizePx: 4 },
});
assert.equal(viewer.scene.primitives.length, 1);
destroy();
assert.equal(viewer.scene.primitives.length, 0);
});
test('sprites become billboards with the set style once the atlas cells are ready', async () => {
const viewer = createFakeViewer();
const { factories, made } = fakeFactories();
const requests = [];
const { movers } = createCesiumMovers(viewer, {
factories,
requestRender: (reason) => requests.push(reason),
});
const set = movers.createSet({
id: 'flights',
kind: 'sprite',
capacity: 3,
depthTest: 'always',
sprite: { atlas, sizePx: 20, scaleByDistance: [1e3, 1, 1e6, 0.5] },
});
set.set(0, { position: at(1), rotation: 0.25, cell: 'heli', pickId: 'x1' });
set.set(1, { position: at(2), color: [1, 0, 0, 0.5], scale: 2, show: false });
set.setCount(2);
set.commit();
const billboards = made.find(
(collection) => collection.kind === 'billboards',
);
assert.equal(billboards.items.length, 0, 'waits for the atlas');
await settle();
assert.equal(billboards.items.length, 2);
const [first, second] = billboards.items;
assert.ok(first.position instanceof Cesium.Cartesian3);
assert.equal(first.position.x, 1);
assert.equal(first.width, 20);
assert.equal(first.height, 20);
assert.equal(first.rotation, 0.25);
assert.equal(first.id, 'x1');
assert.equal(first.disableDepthTestDistance, Number.POSITIVE_INFINITY);
assert.ok(first.scaleByDistance instanceof Cesium.NearFarScalar);
assert.deepEqual(first.images, ['flights:heli']);
assert.equal(first.show, true);
assert.equal(second.show, false);
assert.equal(second.scale, 2);
assert.ok(Cesium.Color.equals(second.color, new Cesium.Color(1, 0, 0, 0.5)));
assert.ok(requests.length >= 1);
// Lowering the count hides the instances past it.
set.setCount(1);
set.commit();
assert.equal(second.show, false);
set.set(0, { cell: 'heli' });
set.commit();
assert.deepEqual(
first.images,
['flights:heli'],
'the same cell is not re-sent',
);
});
test('points take the size, outline and depth test of the set', () => {
const viewer = createFakeViewer();
const { factories, made } = fakeFactories();
const { movers } = createCesiumMovers(viewer, { factories });
const set = movers.createSet({
id: 'sats',
kind: 'point',
capacity: 2,
depthTest: { disableWithinM: 5000 },
point: { sizePx: 4, outlinePx: 1 },
});
set.set(0, { position: at(3), scale: 1.5, color: [0, 1, 0, 1] });
set.setCount(1);
set.commit();
const [point] = made.find((c) => c.kind === 'points').items;
assert.equal(point.pixelSize, 6);
assert.equal(point.outlineWidth, 1);
assert.equal(point.disableDepthTestDistance, 5000);
assert.ok(Cesium.Color.equals(point.color, new Cesium.Color(0, 1, 0, 1)));
});
test('sets are ordered in the root by their order', () => {
const viewer = createFakeViewer();
const { factories } = fakeFactories();
const { movers } = createCesiumMovers(viewer, { factories });
const make = (id, order) =>
movers.createSet({
id,
kind: 'point',
capacity: 1,
order,
point: { sizePx: 2 },
});
make('top', 5);
make('bottom', -1);
make('middle', 0);
const root = viewer.scene.primitives.get(0);
assert.deepEqual(
[0, 1, 2].map((index) => root.get(index).gevMoverSet),
['bottom', 'middle', 'top'],
);
});
test('models load per instance and follow position and orientation', async () => {
const viewer = createFakeViewer();
const { factories, made } = fakeFactories();
const { movers } = createCesiumMovers(viewer, { factories });
const set = movers.createSet({
id: 'models',
kind: 'model',
capacity: 2,
model: {
url: '/models/airplane.glb',
minimumPixelSize: 24,
colorBlend: { mode: 'mix', amount: 0.4 },
},
});
set.set(0, {
position: at(4),
orientation: { x: 0, y: 0, z: 0, w: 1 },
color: [1, 0.5, 0, 1],
});
set.setCount(1);
set.commit();
await settle();
const models = made.find((c) => c.kind === 'models');
assert.equal(models.items.length, 1);
const [model] = models.items;
assert.equal(model.url, '/models/airplane.glb');
assert.equal(model.minimumPixelSize, 24);
assert.equal(model.colorBlendMode, Cesium.ColorBlendMode.MIX);
assert.equal(model.colorBlendAmount, 0.4);
assert.equal(model.modelMatrix[12], 4);
set.destroy();
assert.equal(models.destroyed, true);
});