GPU icon sets cluster their rows where their segments put them

clusterScreenPoints over each GPU set's shown rows at the frame's
motion-clock time (on their ground when clamped), the members' rows hidden
and one icon a cluster drawn at its seed's size in the set's cluster
billboards, picked as each member. Clustered again after the camera moves
or the set changes (setColumns included), and every frame while rows still
move. Conformance checks take several capabilities; draw.motion.cluster
clusters members that come to rest on their segments.
This commit is contained in:
Sameh Khamis committed 2026-11-11 18:09:38 -08:00
1 parent 933969b7da
commit d9ad7da9d5
6 files changed
+385 -144

No files matched your search

+7 -5
View File
@@ -175,12 +175,14 @@ and `meta` and the cluster's position, so `pick` gives the seed and
`drillPick` every member. Clusters are made again in the frames drawn after
the camera moves or the set changes, never on a timer. The Cesium port draws
a set's cluster icons in a billboard collection of their own and hides the
members' billboards; a set on the GPU (`columns`, or moving, receding,
proxy-picked or level-of-detail icons) refuses clustering. The check
`draw.icons.cluster` draws a cluster, picks it, and parts it by moving in.
members' billboards. A set on the GPU (`columns`, or moving, receding,
proxy-picked or level-of-detail icons) clusters its rows where their segments
(and ground) put them at the frame's motion-clock time, hiding the members'
rows; while rows still move it clusters again every frame. The checks
`draw.icons.cluster` and `draw.motion.cluster` (members coming to rest on
their segments) draw a cluster, pick it, and part it by moving in.
Icon sets on the Cesium GPU path draw what its billboards draw but
clustering: pixel offsets, `bottom` and `top` anchors, screen and axis
Icon sets on the Cesium GPU path draw what its billboards draw: pixel offsets, `bottom` and `top` anchors, screen and axis
rotations (turned as Cesium's billboards turn), `fadeByDistance`,
`displayRange`, and `clampGround` / `relativeGround` heights. Each row reads
these from a float texture by instance, so the 16 vertex attributes hold;
+52 -14
View File
@@ -648,8 +648,16 @@ export function createCesiumDraw({
},
};
// A clustered set clusters again in the next frame drawn after a change.
for (const name of ['set', 'upsert', 'remove', 'clear', 'setOptions']) {
for (const name of [
'set',
'upsert',
'remove',
'clear',
'setOptions',
'setColumns',
]) {
const call = handle[name];
if (!call) continue;
handle[name] = (...args) => {
record.clusterKey = null;
return call(...args);
@@ -992,8 +1000,7 @@ export function createCesiumDraw({
const clusters = (record) =>
record.kind === 'icons' &&
Boolean(record.spec.cluster) &&
capabilities.has('cluster') &&
!record.gpu;
capabilities.has('cluster');
/** Let go of a set's cluster icons, and show its members again. */
function dropClusters(record) {
@@ -1003,6 +1010,7 @@ export function createCesiumDraw({
record.clusterState = null;
record.clusterKey = null;
for (const placed of record.placed) placed.clustered = false;
record.gpu?.setClustered(new Set());
}
const clusterScratch = new Cesium.Cartesian2();
@@ -1011,7 +1019,7 @@ export function createCesiumDraw({
* icons again where the camera moved or the set changed since it last
* did (`ClusterSpec`), hiding the members and drawing an icon a cluster.
*/
function clusterIcons() {
function clusterIcons(frameState = scene.frameState) {
let pose;
const poseNow = () => {
const eye = scene.camera?.positionWC;
@@ -1027,30 +1035,59 @@ export function createCesiumDraw({
}
continue;
}
if (!record.billboardHost || record.billboardHost.isDestroyed()) continue;
// A rebuilt collection starts afresh.
if (record.billboardHost !== record.clusteredHost) {
// A rebuilt collection (or the GPU's host in its place) starts afresh.
const host = record.gpu?.host ?? record.billboardHost;
if (!host || host.isDestroyed()) continue;
if (host !== record.clusteredHost) {
record.clusterState = null;
record.clusterKey = null;
record.clusteredHost = record.billboardHost;
record.clusteredHost = host;
}
pose ??= poseNow();
if (record.clusterKey === pose) {
// Rows still moving on their segments cluster again every frame.
const key = record.gpu?.moving(frameState)
? `${pose}@${frameState?.frameNumber ?? Math.random()}`
: pose;
if (record.clusterKey === key) {
if (record.clusterHost)
record.clusterHost.show = record.spec.show !== false;
continue;
}
record.clusterKey = pose;
reclusterIcons(record);
record.clusterKey = key;
reclusterIcons(record, frameState);
}
}
function reclusterIcons(record) {
/** The points a GPU set clusters: its shown rows where they are drawn. */
function gpuClusterPoints(record, frameState, horizon) {
const points = [];
for (const { id, item, position } of record.gpu.drawnRows(frameState)) {
const at = toCartesian(position);
if (horizon && !horizon.isPointVisible(at)) continue;
const screen = Cesium.SceneTransforms.worldToWindowCoordinates(
scene,
at,
clusterScratch,
);
if (!screen) continue;
points.push({
id,
position: at,
screen: { x: screen.x, y: screen.y },
pixelSize: Math.max(item.size[0], item.size[1]) * (item.scale ?? 1),
});
}
return points;
}
function reclusterIcons(record, frameState) {
const spec = record.spec.cluster;
const horizon = horizonNow();
const points = [];
const points = record.gpu
? gpuClusterPoints(record, frameState, horizon)
: [];
const entries = new Map();
for (const [id, entry] of record.billboards) {
for (const [id, entry] of record.gpu ? [] : record.billboards) {
const item = record.items.get(id);
const placed = entry.placed;
if (!item || !placed.shown) continue;
@@ -1089,6 +1126,7 @@ export function createCesiumDraw({
});
record.clusterState = result.state;
const inCluster = new Set(result.clusters.flatMap((c) => c.ids));
record.gpu?.setClustered(inCluster);
for (const placed of record.placed) placed.clustered = false;
for (const id of inCluster) {
const entry = entries.get(id);
+101 -5
View File
@@ -11,8 +11,9 @@
*
* What these sets draw as billboards do not: an icon set becomes one when
* an item first needs it (or it first takes columns), and stays one. They
* draw what billboards draw but clustering, which they refuse loudly; on
* WebGL 1 they also refuse what each row reads from its extras texture
* draw what billboards draw, clustering included (the draw port clusters
* the rows where their segments put them in the frame drawn); on WebGL 1
* they refuse what each row reads from its extras texture
* there is none of: clamped heights, `fadeByDistance`, `displayRange`, pixel
* offsets, anchors other than the centre, and axis and screen rotations.
*
@@ -233,8 +234,6 @@ export function createGpuIcons({
/** Refuse what a GPU icon set cannot draw, before anything changes. */
function check(items, spec = {}) {
if (spec.cluster)
throw new Error("the Cesium renderer's GPU icons have no clustering");
// Atlas slots these items would take anew: they must all fit.
const fresh = new Set();
for (const item of items) {
@@ -325,6 +324,8 @@ export function createGpuIcons({
// Until when (epoch ms on the motion clock) a row may still move or turn.
let movingUntil = -Infinity;
const clockMs = () => Cesium.JulianDate.toDate(clockTime()).getTime();
// Rows drawn as part of a cluster, hidden.
let clustered = new Set();
// What each row's segment was last written from, by id.
const written = new Map();
// The ids of the last columns, while no other write came after them.
@@ -428,7 +429,12 @@ export function createGpuIcons({
);
set.setDepthTestDistance(row, item.disableDepthTest ?? 0);
// An empty range shows it nowhere.
set.setShown(row, item.show !== false && displayable(item.displayRange));
set.setShown(
row,
item.show !== false &&
displayable(item.displayRange) &&
!clustered.has(item.id),
);
writeExtras(row, item);
writeSegment(row, item, added, motion);
writeGround(row, item);
@@ -556,6 +562,49 @@ export function createGpuIcons({
groundQueue.add(item.id);
}
/**
* `p` on a clamped row's ground, as its shader puts it: the ground
* between the heights under its segment's ends, by how far along it is.
*/
function onGround(row, p) {
const [from, to] = set.groundSpan(row);
const [g0, g1] = set.groundHeights(row);
const sx = to.x - from.x;
const sy = to.y - from.y;
const sz = to.z - from.z;
const spanSq = sx * sx + sy * sy + sz * sz;
const along =
spanSq > 0
? Math.min(
1,
Math.max(
0,
((p.x - from.x) * sx +
(p.y - from.y) * sy +
(p.z - from.z) * sz) /
spanSq,
),
)
: 0;
const ground = g0 + (g1 - g0) * along;
const carto = Cesium.Cartographic.fromCartesian(
Cesium.Cartesian3.fromElements(p.x, p.y, p.z, groundAt),
undefined,
groundCarto,
);
if (!carto) return p;
const height =
set.groundMode(row) === ICON_GROUND_CLAMP
? ground
: carto.height + ground;
const c = Cesium.Cartesian3.fromRadians(
carto.longitude,
carto.latitude,
height,
);
return { x: c.x, y: c.y, z: c.z };
}
const groundAt = new Cesium.Cartesian3();
const groundCarto = new Cesium.Cartographic();
/**
@@ -744,6 +793,53 @@ export function createGpuIcons({
for (const id of later) groundQueue.add(id);
return changed;
},
/**
* The rows a cluster pass sees: each whose item is shown, where it
* is drawn at `frameState`'s time (on its segment, on its ground),
* with its item.
*/
drawnRows(frameState) {
const tau = set.seconds(clockTime(frameState));
const out = [];
for (let row = 0; row < set.count; row++) {
const id = set.idAt(row);
const item = record.items.get(id);
if (!item || item.show === false || !displayable(item.displayRange))
continue;
const p = set.position(row, tau, { x: 0, y: 0, z: 0 });
out.push({
id,
item,
position: grounded.has(id) ? onGround(row, p) : p,
});
}
return out;
},
/** Hide the rows of `ids` (in clusters); show the rest again. */
setClustered(ids) {
const before = clustered;
clustered = ids;
for (const id of new Set([...before, ...ids])) {
if (before.has(id) === ids.has(id)) continue;
const row = set.row(id);
const item = record.items.get(id);
if (row < 0 || !item) continue;
set.setShown(
row,
item.show !== false &&
displayable(item.displayRange) &&
!ids.has(id),
);
}
},
/** Whether rows still move at the motion clock's time in `frameState`. */
moving(frameState) {
return (
set.count > 0 &&
Cesium.JulianDate.toDate(clockTime(frameState)).getTime() <
movingUntil
);
},
/** Whether a live-clock row is still moving: frames should keep coming. */
animating() {
if (spec.motionClock?.kind === 'scene' || spec.show === false)
+86 -13
View File
@@ -492,19 +492,92 @@ test('ground samples are budgeted across frames, the drawn surface the fewest',
);
});
test('GPU icon sets refuse clustering, changing nothing', () => {
const { part, draw } = drawOver();
const cluster = { pixelRange: 10, minimumSize: 2 };
const set = draw.icons({ id: 'gpu:cluster' });
set.set([icon('a', { motion: { kind: 'hold' } })]);
assert.throws(() => set.setOptions({ cluster }), /no clustering/);
assert.equal(part.sets.get('gpu:cluster').spec.cluster, undefined);
const clustered = draw.icons({ id: 'gpu:clustered', cluster });
assert.throws(
() => clustered.set([icon('a', { motion: { kind: 'hold' } })]),
/no clustering/,
);
assert.equal(clustered.size(), 0);
test('a GPU icon set clusters its rows where their segments put them in the frame', () => {
const transforms = Cesium.SceneTransforms;
const project = transforms.worldToWindowCoordinates;
// Window positions: a degree of longitude is `spread` pixels.
let spread = 1;
transforms.worldToWindowCoordinates = (_, position, result) => {
const at = Cesium.Cartographic.fromCartesian(position);
result ??= new Cesium.Cartesian2();
result.x = 200 + Cesium.Math.toDegrees(at.longitude) * spread;
result.y = 150 - Cesium.Math.toDegrees(at.latitude) * spread;
return result;
};
try {
const { part, draw, scene } = drawOver({
capabilities: new Set(['motionSegments', 'columns', 'cluster']),
});
scene.camera.directionWC = new Cesium.Cartesian3(-1, 0, 0);
scene.camera.positionCartographic = { height: 1000 };
scene.canvas = { clientWidth: 400, clientHeight: 300 };
const t0 = Cesium.JulianDate.toDate(scene.frameState.time).getTime();
const counts = [];
const set = draw.icons({
id: 'gpu:cluster',
motionClock: { kind: 'scene' },
cluster: {
pixelRange: 10,
minimumSize: 2,
icon: (count) => (counts.push(count), 'badge.png'),
},
});
// Each given far apart, each moving to within a few pixels of the rest.
const mover = (id, lon) => {
const from = ecef(Cesium.Cartesian3.fromDegrees(lon * 40, 30));
const to = ecef(Cesium.Cartesian3.fromDegrees(lon, 0));
return icon(id, {
pos: from,
size: [8, 8],
meta: { id },
motion: { kind: 'lerp', from, to, t0, t1: t0 + 1000 },
});
};
set.set([mover('a', 0), mover('b', 2), mover('c', 4)]);
// At the start, apart: no cluster.
part.beforeRender();
const { set: s } = rows(part, 'gpu:cluster');
assert.deepEqual(counts, []);
assert.ok(['a', 'b', 'c'].every((id) => s.shown(s.row(id))));
// At the end, together.
scene.frameState.time = julian(t0 + 5000);
part.beforeRender();
assert.deepEqual(counts, [3]);
assert.ok(
['a', 'b', 'c'].every((id) => !s.shown(s.row(id))),
'members are not drawn',
);
const clusters = part.sets.get('gpu:cluster').clusterHost;
assert.equal(clusters.length, 1);
const { id, width } = clusters.get(0);
assert.equal(width, 8, 'at its seed’s size');
assert.deepEqual(id.cluster.ids, ['a', 'b', 'c'], 'seed first');
const mean = Cesium.Cartographic.fromCartesian(
new Cesium.Cartesian3(
id.cluster.position.x,
id.cluster.position.y,
id.cluster.position.z,
),
);
assert.ok(Math.abs(Cesium.Math.toDegrees(mean.longitude) - 2) < 1e-3);
// Held still, not made again.
part.beforeRender();
assert.deepEqual(counts, [3]);
// The camera moved: apart, each drawn again.
spread = 100;
scene.camera.positionWC = new Cesium.Cartesian3(2e7, 1, 0);
part.beforeRender();
assert.equal(clusters.length, 0);
assert.ok(['a', 'b', 'c'].every((id) => s.shown(s.row(id))));
// A member hidden by its item stays hidden out of a cluster.
set.upsert([{ ...mover('b', 2), show: false }]);
part.beforeRender();
assert.equal(s.shown(s.row('b')), false);
set.dispose();
assert.ok(!scene.added.includes(clusters), 'let go with the set');
} finally {
transforms.worldToWindowCoordinates = project;
}
});
test('columns update rows by index: positions, courses, shown, scales, tints and meta', () => {
+1
View File
@@ -65,6 +65,7 @@ export const CESIUM_CHECKS = new Set([
'draw.motion',
'draw.motion.arc',
'draw.motion.climb',
'draw.motion.cluster',
'draw.motion.live',
'draw.motion.look',
'draw.motion.shared',
+138 -107
View File
@@ -146,8 +146,10 @@ function check(id, title, run, extra = {}) {
async run(h) {
const r = await fresh(h);
try {
if (extra.capability && !r.capabilities.has(extra.capability))
return { skip: `no ${extra.capability}` };
// One capability or several, each needed.
for (const capability of [extra.capability ?? []].flat())
if (!r.capabilities.has(capability))
return { skip: `no ${capability}` };
return await run(h, r);
} finally {
r.destroy();
@@ -220,6 +222,138 @@ fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
},
});
/** `draw.icons.cluster`, and with `moving` its rows on their segments. */
function clusterCheck(moving) {
return check(
moving ? 'draw.motion.cluster' : 'draw.icons.cluster',
moving
? 'moving icons cluster where their segments put them, picked as their members seed first; apart again, each is its own'
: 'icons close on screen draw as one cluster, picked as its members seed first at its position; apart again, each is its own',
async (h, r) => {
await overAustin(h, r, 2000);
const counts = [];
const t0 = r.frame.time();
if (moving) r.frame.setTime(t0 + 20000);
const set = r.draw.icons({
id: 'conf:cluster',
...(moving ? { motionClock: { kind: 'scene' } } : {}),
cluster: {
pixelRange: 20,
minimumSize: 3,
icon: (count) => {
counts.push(count);
return DOT;
},
},
});
const at = (dx, dy) =>
h.toEcef({
lon: AUSTIN.lon + 0.0008 + dx * 0.0003,
lat: AUSTIN.lat + 0.0006 + dy * 0.0003,
height: 0,
});
const members = [
['a', at(0, 0)],
['b', at(1, 0)],
['c', at(0, 1)],
['d', at(1, 1)],
];
const far = h.toEcef({
lon: AUSTIN.lon - 0.003,
lat: AUSTIN.lat - 0.002,
height: 0,
});
set.set([
...members.map(([id, pos]) => ({
id,
// Moving: given far off, come to rest where the rest are.
pos: moving ? far : pos,
image: DOT,
size: [16, 16],
meta: { m: id },
...(moving
? {
motion: {
kind: 'lerp',
from: far,
to: pos,
t0,
t1: t0 + 10000,
},
}
: {}),
})),
{
id: 'far',
pos: far,
image: DOT,
size: [16, 16],
...(moving ? { motion: { kind: 'hold' } } : {}),
},
]);
await drawn(h, r);
await settled(r);
await drawn(h, r);
ok(counts.includes(4), 'the icon is drawn for its count');
const mean = members.reduce(
(m, [, p]) => ({
x: m.x + p.x / members.length,
y: m.y + p.y / members.length,
z: m.z + p.z / members.length,
}),
{ x: 0, y: 0, z: 0 },
);
const s = r.query.project(mean);
ok(s, 'the cluster projects');
const hit = r.query.pick(s.x, s.y);
deepEqual(
[hit?.set, hit?.id, hit?.meta],
['conf:cluster', 'a', { m: 'a' }],
'pick gives the seed, with its own meta',
);
ok(hit?.position, 'at a position');
nearVec(hit.position, mean, 1, 'the cluster’s position');
const drilled = r.query
.drillPick(s.x, s.y)
.filter((x) => x.set === 'conf:cluster');
deepEqual(
drilled.map((x) => [x.id, x.meta?.m]),
members.map(([id]) => [id, id]),
'drillPick gives every member, seed first',
);
const sf = r.query.project(far);
equal(r.query.pick(sf.x, sf.y)?.id, 'far', 'an icon on its own');
await overAustin(h, r, 300);
r.camera.setView({
destination: {
lon: AUSTIN.lon + 0.00095,
lat: AUSTIN.lat + 0.00075,
height: 300,
},
orientation: { heading: 0, pitch: -Math.PI / 2, roll: 0 },
});
await drawn(h, r);
await settled(r);
await drawn(h, r);
for (const [id, pos] of members) {
const m = r.query.project(pos);
ok(m, `${id} projects`);
deepEqual(
r.query
.drillPick(m.x, m.y)
.filter((x) => x.set === 'conf:cluster')
.map((x) => x.id),
[id],
`${id} on its own once apart`,
);
}
set.dispose();
},
{ capability: moving ? ['cluster', 'motionSegments'] : 'cluster' },
);
}
export function portChecks() {
return [
// --- Shape -------------------------------------------------------------
@@ -1722,111 +1856,8 @@ export function portChecks() {
for (const set of sets) set.dispose();
},
),
check(
'draw.icons.cluster',
'icons close on screen draw as one cluster, picked as its members seed first at its position; apart again, each is its own',
async (h, r) => {
await overAustin(h, r, 2000);
const counts = [];
const set = r.draw.icons({
id: 'conf:cluster',
cluster: {
pixelRange: 20,
minimumSize: 3,
icon: (count) => {
counts.push(count);
return DOT;
},
},
});
const at = (dx, dy) =>
h.toEcef({
lon: AUSTIN.lon + 0.0008 + dx * 0.0003,
lat: AUSTIN.lat + 0.0006 + dy * 0.0003,
height: 0,
});
const members = [
['a', at(0, 0)],
['b', at(1, 0)],
['c', at(0, 1)],
['d', at(1, 1)],
];
const far = h.toEcef({
lon: AUSTIN.lon - 0.003,
lat: AUSTIN.lat - 0.002,
height: 0,
});
set.set([
...members.map(([id, pos]) => ({
id,
pos,
image: DOT,
size: [16, 16],
meta: { m: id },
})),
{ id: 'far', pos: far, image: DOT, size: [16, 16] },
]);
await drawn(h, r);
await settled(r);
await drawn(h, r);
ok(counts.includes(4), 'the icon is drawn for its count');
const mean = members.reduce(
(m, [, p]) => ({
x: m.x + p.x / members.length,
y: m.y + p.y / members.length,
z: m.z + p.z / members.length,
}),
{ x: 0, y: 0, z: 0 },
);
const s = r.query.project(mean);
ok(s, 'the cluster projects');
const hit = r.query.pick(s.x, s.y);
deepEqual(
[hit?.set, hit?.id, hit?.meta],
['conf:cluster', 'a', { m: 'a' }],
'pick gives the seed, with its own meta',
);
ok(hit?.position, 'at a position');
nearVec(hit.position, mean, 1, 'the cluster’s position');
const drilled = r.query
.drillPick(s.x, s.y)
.filter((x) => x.set === 'conf:cluster');
deepEqual(
drilled.map((x) => [x.id, x.meta?.m]),
members.map(([id]) => [id, id]),
'drillPick gives every member, seed first',
);
const sf = r.query.project(far);
equal(r.query.pick(sf.x, sf.y)?.id, 'far', 'an icon on its own');
await overAustin(h, r, 300);
r.camera.setView({
destination: {
lon: AUSTIN.lon + 0.00095,
lat: AUSTIN.lat + 0.00075,
height: 300,
},
orientation: { heading: 0, pitch: -Math.PI / 2, roll: 0 },
});
await drawn(h, r);
await settled(r);
await drawn(h, r);
for (const [id, pos] of members) {
const m = r.query.project(pos);
ok(m, `${id} projects`);
deepEqual(
r.query
.drillPick(m.x, m.y)
.filter((x) => x.set === 'conf:cluster')
.map((x) => x.id),
[id],
`${id} on its own once apart`,
);
}
set.dispose();
},
{ capability: 'cluster' },
),
clusterCheck(false),
clusterCheck(true),
check(
'draw.icons.update',
'an upserted icon keeps drawing, as it now is, from the next frame: picked at its new size with its new meta, even while a new image loads; a removed one is gone',