diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md
index 829767f68..67cfb876b 100644
--- a/docs/RENDERER-CONTRACT.md
+++ b/docs/RENDERER-CONTRACT.md
@@ -163,6 +163,21 @@ keyed canvas, and an atlas slot as the image it holds (an icon waits for an
unregistered slot; anything else refuses it). The check `draw.icons.images`
draws each kind on still and receding icons.
+Icon sets with `cluster` (`ClusterSpec`) cluster the same way on every
+renderer: `clusterScreenPoints` (`src/geo/screenCluster.js`) over the shown
+icons in front of the eye and above the horizon, in the set's order, boxed at
+their drawn size, the last pass's clusters kept. A cluster draws one icon at
+the mean of its members' positions in place of its members (`icon(count)`,
+else a default badge with the count, at the seed's size). A pick on it
+answers one hit a member, seed first, each with the member's own `set`, `id`
+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.
+
The Cesium port also draws `pattern` line styles (the image repeated
`repeat` times along the line, in the translucent pass; draped too), lines in the
`inertial` frame (turned each frame by the set's motion clock, a depth-fail
diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js
index c564441a4..c85ee15d0 100644
--- a/src/render/cesium/draw.js
+++ b/src/render/cesium/draw.js
@@ -34,6 +34,7 @@
import * as Cesium from 'cesium';
import { temeToPseudoFixed } from '../../geo/celestial.js';
import { alongLength } from '../../geo/polyline.js';
+import { clusterScreenPoints } from '../../geo/screenCluster.js';
import { provideUnboundDraw } from '../rendererOf.js';
import { blobUrl, listenerList, toCartesian, uncaught } from './common.js';
import { createGpuIcons, GPU_ICON_CAPABILITIES } from './gpuIcons.js';
@@ -549,6 +550,8 @@ export function createCesiumDraw({
requestRender();
},
setOptions(options) {
+ // Refused, changing nothing, where icons on the GPU cannot take it.
+ if (record.gpu) gpu.check([], { ...spec, ...options });
const culled = spec.horizonCull;
const clampTo = spec.clampTo;
const blend = spec.blend;
@@ -605,6 +608,19 @@ export function createCesiumDraw({
requestRender();
},
};
+ // A clustered set clusters again in the next frame drawn after a change.
+ for (const name of ['set', 'upsert', 'remove', 'clear', 'setOptions']) {
+ const call = handle[name];
+ handle[name] = (...args) => {
+ record.clusterKey = null;
+ return call(...args);
+ };
+ }
+ const dispose = handle.dispose;
+ handle.dispose = () => {
+ dropClusters(record);
+ dispose();
+ };
// `columns`: column updates of an icon set, on the GPU.
if (kind === 'icons' && capabilities.has('columns'))
handle.setColumns = (columns) => {
@@ -833,7 +849,10 @@ export function createCesiumDraw({
const horizon = horizonNow();
if (!horizon) return;
for (const placed of record.placed) {
- const show = placed.shown && horizon.isPointVisible(placed.position);
+ const show =
+ placed.shown &&
+ !placed.clustered &&
+ horizon.isPointVisible(placed.position);
if (placed.primitive.show !== show) placed.primitive.show = show;
}
}
@@ -859,6 +878,168 @@ export function createCesiumDraw({
}
}
+ // --- Clusters (`cluster`) --------------------------------------------------
+
+ /** The default cluster badge: the count on a disc. */
+ const clusterBadge = (count) => ({
+ svg: ``,
+ });
+
+ /** Whether an icon set clusters now. */
+ const clusters = (record) =>
+ record.kind === 'icons' &&
+ Boolean(record.spec.cluster) &&
+ capabilities.has('cluster') &&
+ !record.gpu;
+
+ /** Let go of a set's cluster icons, and show its members again. */
+ function dropClusters(record) {
+ const host = record.clusterHost;
+ if (host && !host.isDestroyed() && live()) scene.primitives.remove(host);
+ record.clusterHost = null;
+ record.clusterState = null;
+ record.clusterKey = null;
+ for (const placed of record.placed) placed.clustered = false;
+ }
+
+ const clusterScratch = new Cesium.Cartesian2();
+ /**
+ * Each frame, before it draws: every clustered icon set clusters its
+ * 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() {
+ let pose;
+ const poseNow = () => {
+ const eye = scene.camera?.positionWC;
+ const dir = scene.camera?.directionWC;
+ return `${eye?.x},${eye?.y},${eye?.z},${dir?.x},${dir?.y},${dir?.z},${scene.canvas?.clientWidth},${scene.canvas?.clientHeight}`;
+ };
+ for (const record of sets.values()) {
+ if (!clusters(record)) {
+ if (record.clusterHost || record.clusterState) {
+ dropClusters(record);
+ for (const placed of record.placed)
+ placed.primitive.show = shownNow(record, placed);
+ }
+ continue;
+ }
+ if (!record.billboardHost || record.billboardHost.isDestroyed()) continue;
+ // A rebuilt collection starts afresh.
+ if (record.billboardHost !== record.clusteredHost) {
+ record.clusterState = null;
+ record.clusterKey = null;
+ record.clusteredHost = record.billboardHost;
+ }
+ pose ??= poseNow();
+ if (record.clusterKey === pose) {
+ if (record.clusterHost)
+ record.clusterHost.show = record.spec.show !== false;
+ continue;
+ }
+ record.clusterKey = pose;
+ reclusterIcons(record);
+ }
+ }
+
+ function reclusterIcons(record) {
+ const spec = record.spec.cluster;
+ const horizon = horizonNow();
+ const points = [];
+ const entries = new Map();
+ for (const [id, entry] of record.billboards) {
+ const item = record.items.get(id);
+ const placed = entry.placed;
+ if (!item || !placed.shown) continue;
+ if (horizon && !horizon.isPointVisible(placed.position)) continue;
+ const screen = Cesium.SceneTransforms.worldToWindowCoordinates(
+ scene,
+ placed.position,
+ clusterScratch,
+ );
+ if (!screen) continue;
+ points.push({
+ id,
+ position: placed.position,
+ screen: { x: screen.x, y: screen.y },
+ pixelSize: Math.max(item.size[0], item.size[1]) * (item.scale ?? 1),
+ });
+ entries.set(id, entry);
+ }
+ const result = clusterScreenPoints({
+ points,
+ pixelRange: spec.pixelRange,
+ minimumClusterSize: spec.minimumSize,
+ viewHeight: scene.canvas?.clientHeight ?? 0,
+ eyeHeight: scene.camera.positionCartographic?.height ?? 0,
+ previous: record.clusterState,
+ project: (position) => {
+ const p = Cesium.SceneTransforms.worldToWindowCoordinates(
+ scene,
+ toCartesian(position),
+ new Cesium.Cartesian2(),
+ );
+ return p ? { x: p.x, y: p.y } : null;
+ },
+ isOccluded: (position) =>
+ horizon ? !horizon.isPointVisible(toCartesian(position)) : false,
+ });
+ record.clusterState = result.state;
+ const inCluster = new Set(result.clusters.flatMap((c) => c.ids));
+ for (const placed of record.placed) placed.clustered = false;
+ for (const id of inCluster) {
+ const entry = entries.get(id);
+ if (entry) entry.placed.clustered = true;
+ }
+ for (const placed of record.placed) {
+ const show = shownNow(record, placed);
+ if (placed.primitive.show !== show) placed.primitive.show = show;
+ }
+ let host = record.clusterHost;
+ if (!host || host.isDestroyed()) {
+ host = new Cesium.BillboardCollection({
+ scene,
+ blendOption: pointBlendOf(record.spec.blend),
+ });
+ record.clusterHost = host;
+ scene.primitives.add(host);
+ }
+ host.removeAll();
+ host.show = record.spec.show !== false;
+ for (const cluster of result.clusters) {
+ const seed = record.items.get(cluster.ids[0]);
+ const position = toCartesian(cluster.position);
+ const given = spec.icon?.(cluster.ids.length);
+ const image =
+ given === undefined
+ ? clusterBadge(cluster.ids.length)
+ : typeof given?.atlas === 'string'
+ ? atlases.get(given.atlas)?.[given.slot]
+ : given;
+ if (image === undefined) continue;
+ const scale = seed.scale ?? 1;
+ const billboard = host.add({
+ position,
+ width: seed.size[0] * scale,
+ height: seed.size[1] * scale,
+ disableDepthTestDistance: seed.disableDepthTest ?? 0,
+ id: {
+ set: record.spec.id,
+ id: cluster.ids[0],
+ get meta() {
+ return record.items.get(cluster.ids[0])?.meta;
+ },
+ cluster: {
+ ids: cluster.ids.slice(),
+ position: { x: position.x, y: position.y, z: position.z },
+ },
+ },
+ });
+ if (isKeyed(image)) billboard.setImage(image.key, image.canvas);
+ else billboard.image = toImage(image);
+ }
+ }
+
/** The horizon from the eye as it is now; null where there is none (2D). */
function horizonNow() {
const eye = scene.camera?.positionWC;
@@ -882,7 +1063,8 @@ export function createCesiumDraw({
* frame's cull (a frame listener that moves its items).
*/
function shownNow(record, placed) {
- if (!placed.shown || !record.spec.horizonCull) return placed.shown;
+ if (!placed.shown || placed.clustered) return false;
+ if (!record.spec.horizonCull) return placed.shown;
return horizonNow()?.isPointVisible(placed.position) ?? true;
}
@@ -4795,6 +4977,7 @@ export function createCesiumDraw({
beforeRender() {
pulsing = runPulses();
cullHorizon();
+ clusterIcons();
runFlows();
for (const record of sets.values())
if (record.inertialLines || record.inertialPieces?.length)
diff --git a/src/render/cesium/draw.test.mjs b/src/render/cesium/draw.test.mjs
index 7572a2fd7..c0eac6389 100644
--- a/src/render/cesium/draw.test.mjs
+++ b/src/render/cesium/draw.test.mjs
@@ -7941,3 +7941,89 @@ test('the transit layer draws its vehicles as two icon sets, moving a marker bet
assert.equal(hostOf(stillId), undefined);
assert.equal(hostOf(movingId), undefined);
});
+
+test('a clustered icon set draws one icon a cluster in place of its members, made again as the camera moves', () => {
+ const scene = fakeScene();
+ scene.camera.directionWC = new Cesium.Cartesian3(-1, 0, 0);
+ scene.camera.positionCartographic = { height: 1000 };
+ scene.canvas = { clientWidth: 400, clientHeight: 300 };
+ // Window positions: a degree of longitude is `spread` pixels.
+ let spread = 1;
+ const transforms = Cesium.SceneTransforms;
+ const project = transforms.worldToWindowCoordinates;
+ 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 = createCesiumDraw({
+ scene,
+ report: (error) => {
+ throw error;
+ },
+ capabilities: new Set(['cluster']),
+ });
+ const counts = [];
+ const set = part.port.icons({
+ id: 'clustered',
+ cluster: {
+ pixelRange: 10,
+ minimumSize: 2,
+ icon: (count) => (counts.push(count), undefined),
+ },
+ });
+ const icon = (id, lon) => ({
+ id,
+ pos: { lon, lat: 0 },
+ image: { svg: '' },
+ size: [8, 8],
+ meta: { id },
+ });
+ set.set([icon('a', 0), icon('b', 2), icon('c', 4)]);
+ part.beforeRender();
+ const members = scene.added[0];
+ const clusters = scene.added.at(-1);
+ assert.notEqual(
+ clusters,
+ members,
+ 'cluster icons are a collection of their own',
+ );
+ assert.deepEqual(
+ [0, 1, 2].map((i) => members.get(i).show),
+ [false, false, false],
+ 'members are not drawn',
+ );
+ assert.equal(clusters.length, 1);
+ assert.deepEqual(counts, [3]);
+ const { id } = clusters.get(0);
+ assert.deepEqual([id.set, id.id, id.meta], ['clustered', 'a', { id: 'a' }]);
+ 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-6);
+ // Not made again while nothing moved.
+ part.beforeRender();
+ assert.deepEqual(counts, [3]);
+ // The camera moved: apart, each is its own.
+ spread = 100;
+ scene.camera.positionWC = new Cesium.Cartesian3(2e7, 1, 0);
+ part.beforeRender();
+ assert.equal(clusters.length, 0);
+ assert.deepEqual(
+ [0, 1, 2].map((i) => members.get(i).show),
+ [true, true, true],
+ );
+ set.dispose();
+ assert.ok(!scene.added.includes(clusters), 'let go with the set');
+ } finally {
+ transforms.worldToWindowCoordinates = project;
+ }
+});
diff --git a/src/render/cesium/gpuIcons.js b/src/render/cesium/gpuIcons.js
index 524c80adb..2f3d1239c 100644
--- a/src/render/cesium/gpuIcons.js
+++ b/src/render/cesium/gpuIcons.js
@@ -13,7 +13,8 @@
* an item first needs it (or it first takes columns), and stays one. They
* refuse loudly what billboards draw and they do not: clamped heights,
* `fadeByDistance`, `displayRange`, pixel offsets, anchors other than the
- * centre, axis and screen rotations, and opaque and additive blends. Their
+ * centre, axis and screen rotations, opaque and additive blends, and
+ * clustering. Their
* images (URLs, SVG, blobs, keyed canvases and atlas slots of those)
* are rasterised square into the icon atlas every GPU icon set shares, and
* refused when it has no room left for them: an SVG at its own size (its
@@ -205,6 +206,8 @@ export function createGpuIcons({
throw new Error(
`the Cesium renderer's GPU icons have no ${spec.blend} blend`,
);
+ 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) {
diff --git a/src/render/cesium/gpuIcons.test.mjs b/src/render/cesium/gpuIcons.test.mjs
index a55626644..c319ece88 100644
--- a/src/render/cesium/gpuIcons.test.mjs
+++ b/src/render/cesium/gpuIcons.test.mjs
@@ -349,6 +349,21 @@ test('GPU icon sets refuse what they cannot draw, changing nothing', () => {
assert.equal(billboards.size(), 1);
});
+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('columns update rows by index: positions, courses, shown, scales, tints and meta', () => {
const { part, draw } = drawOver();
const set = draw.icons({ id: 'gpu:columns' });
diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js
index 113269565..bdd80ea4d 100644
--- a/src/render/cesium/harness.js
+++ b/src/render/cesium/harness.js
@@ -44,6 +44,7 @@ export const CESIUM_CHECKS = new Set([
'draw.drillPick',
'draw.field.rasterShell',
'draw.field.windStreamlines',
+ 'draw.icons.cluster',
'draw.icons.distance',
'draw.icons.images',
'draw.icons.update',
diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js
index 51d9e6be0..8e5e4ef0a 100644
--- a/src/render/cesium/ports.js
+++ b/src/render/cesium/ports.js
@@ -81,6 +81,8 @@ export function cesiumCapabilities(scene, only) {
? ['keepEarthFramed']
: []),
...GPU_ICON_CAPABILITIES,
+ // Icon sets on billboards cluster on screen (`draw.js`).
+ 'cluster',
'styles',
'bloom',
'sharpen',
diff --git a/src/render/cesium/ports.test.mjs b/src/render/cesium/ports.test.mjs
index 55ce0cfc7..f559fd1f9 100644
--- a/src/render/cesium/ports.test.mjs
+++ b/src/render/cesium/ports.test.mjs
@@ -17,6 +17,7 @@ test('capabilities follow what the scene supports', () => {
'columns',
'motionSegments',
'courseGlide',
+ 'cluster',
'styles',
'bloom',
'sharpen',
diff --git a/src/render/cesium/query.js b/src/render/cesium/query.js
index 4005e01d5..f38029e72 100644
--- a/src/render/cesium/query.js
+++ b/src/render/cesium/query.js
@@ -76,6 +76,30 @@ export function createCesiumQuery({
const hitOf = ({ id }) => drawHitOf({ id });
+ /**
+ * The hits a picked object stands for: its item's, or for a cluster's
+ * icon, one a member in the cluster's order (seed first), each at the
+ * cluster's position (`ClusterSpec`); unpickable members left out.
+ */
+ function hitsOf(owner) {
+ const cluster = owner.id.cluster;
+ if (!cluster) return pickable(owner) ? [hitOf(owner)] : [];
+ const { record } = owner;
+ const hits = [];
+ for (const id of cluster.ids) {
+ const item = record.items.get(id);
+ if (!item || !pickable({ record, item })) continue;
+ hits.push({
+ set: record.spec.id,
+ id,
+ ...(item.meta === undefined ? {} : { meta: item.meta }),
+ surface: false,
+ position: { ...cluster.position },
+ });
+ }
+ return hits;
+ }
+
/** A query that throws answers nothing. */
const quietly = (fn) => {
try {
@@ -147,11 +171,18 @@ export function createCesiumQuery({
if (untilForeign) break;
continue;
}
- const key = `${owner.id.set}\u0000${owner.id.id}`;
- if (!pickable(owner) || seen.has(key)) continue;
- seen.add(key);
- hits.push(hitOf(owner));
- if (limit !== undefined && hits.length >= limit) break;
+ let full = false;
+ for (const hit of hitsOf(owner)) {
+ const key = `${hit.set}\u0000${hit.id}`;
+ if (seen.has(key)) continue;
+ seen.add(key);
+ hits.push(hit);
+ if (limit !== undefined && hits.length >= limit) {
+ full = true;
+ break;
+ }
+ }
+ if (full) break;
}
return hits;
}
@@ -313,7 +344,8 @@ export function createCesiumQuery({
const picked = scene.pick(screen(x, y), width, height);
rememberPick(scene, x, y, width, height, picked);
const owner = ownerOf(picked);
- if (owner && pickable(owner)) return hitOf(owner);
+ const [hit] = owner ? hitsOf(owner) : [];
+ if (hit) return hit;
// Something unpickable is on top: the first pickable item under it,
// unless something else hides it.
if (owner) {
diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js
index bbf71fcde..2f0ab7ac8 100644
--- a/src/render/conformance/checks/ports.js
+++ b/src/render/conformance/checks/ports.js
@@ -1714,6 +1714,111 @@ 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' },
+ ),
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',
diff --git a/src/render/contract/draw.d.ts b/src/render/contract/draw.d.ts
index ba0b62a1a..1f990d6ca 100644
--- a/src/render/contract/draw.d.ts
+++ b/src/render/contract/draw.d.ts
@@ -30,8 +30,24 @@ export type HeightMode = 'absolute' | 'clampGround' | 'relativeGround';
/** What `clampGround` / `relativeGround` clamp to. */
export type ClampTarget = 'terrain' | 'tiles' | 'both';
+/**
+ * `cluster`: screen-space clustering of a set's icons. Which icons cluster
+ * is `clusterScreenPoints` (`src/geo/screenCluster.js`) over the set's shown
+ * icons in front of the eye and above the horizon, in the set's order, each
+ * boxed at its drawn size (its larger side, times its `scale`), with
+ * `pixelRange` and `minimumSize`, and the last pass's clusters kept as it
+ * keeps them: so the renderer forms exactly these clusters. A cluster draws one
+ * icon at the cluster's position (the mean of its members') in place of its
+ * members, which are not drawn: its image is `icon(count)` when given, else
+ * a default badge showing the count, drawn at its seed's size. A pick on a
+ * cluster answers one `Hit` per member, in the cluster's order (seed
+ * first), each with that member's own `set`, `id` and `meta` and the
+ * cluster's `position`: so `pick` gives the seed and `drillPick` every
+ * member. Clusters are recomputed in the frames drawn after the camera
+ * moves or the set changes, never on a timer.
+ */
export interface ClusterSpec {
- /** Screen distance under which icons merge. */
+ /** Screen distance under which icons merge, CSS pixels. */
pixelRange: number;
/** Fewest icons that form a cluster. */
minimumSize: number;
@@ -48,7 +64,7 @@ export interface SetSpec {
id: string;
/** Hide items beyond the ellipsoid's horizon, for sets drawn without depth test. */
horizonCull?: boolean;
- /** `cluster`: screen-space clustering (icons only). */
+ /** `cluster`: screen-space clustering (icons only; see `ClusterSpec`). */
cluster?: ClusterSpec | null;
blend?: 'opaque' | 'translucent' | 'additive';
/**
diff --git a/src/render/stub/index.js b/src/render/stub/index.js
index 323221da8..d250c367e 100644
--- a/src/render/stub/index.js
+++ b/src/render/stub/index.js
@@ -11,6 +11,7 @@
*/
import { horizonFrom } from '../../geo/horizon.js';
import { alongLength } from '../../geo/polyline.js';
+import { clusterScreenPoints } from '../../geo/screenCluster.js';
import { createInputRouter } from '../input/router.js';
import { cssColor } from '../color.js';
import { CAPABILITIES, CONTRACT_VERSION } from '../contract/index.js';
@@ -288,6 +289,7 @@ export function createStubRenderer(options = {}) {
step('preRender');
runPhase('preRender', t);
step('render');
+ for (const set of sets.values()) clusterPass(set);
rendered += 1;
// A frame each timed layer was asked to show is now drawn.
for (const [layer, flush] of [...frameFlushes])
@@ -510,9 +512,88 @@ export function createStubRenderer(options = {}) {
record.items = next;
requestRender('draw');
};
+ // A clustered set clusters again in the next frame drawn after a change.
+ record.version = 0;
+ for (const name of [
+ 'set',
+ 'upsert',
+ 'remove',
+ 'clear',
+ 'setOptions',
+ 'setColumns',
+ ]) {
+ const call = handle[name];
+ if (!call) continue;
+ handle[name] = (...args) => {
+ record.version += 1;
+ return call(...args);
+ };
+ }
return handle;
}
+ /**
+ * `cluster`: a clustered icon set's clusters as the last drawn frame made
+ * them (`ClusterSpec`), made again where the camera moved or the set
+ * changed since; null for a set that does not cluster.
+ */
+ function clusterPass(set) {
+ if (
+ set.kind !== 'icons' ||
+ !set.spec.cluster ||
+ !capabilities.has('cluster')
+ ) {
+ set.clusters = null;
+ return;
+ }
+ const e = eye();
+ const key = [
+ set.version,
+ e.position.x,
+ e.position.y,
+ e.position.z,
+ e.direction.x,
+ e.direction.y,
+ e.direction.z,
+ viewport.width,
+ viewport.height,
+ ].join(',');
+ if (set.clusterKey === key) return;
+ set.clusterKey = key;
+ const points = [];
+ for (const item of set.items.values()) {
+ if (item.show === false) continue;
+ const position = itemPosition(set, item);
+ if (!position || isOccluded(position)) continue;
+ const screen = project(position);
+ if (!screen) continue;
+ const [w = 0, h = 0] = item.size ?? [];
+ points.push({
+ id: item.id,
+ position,
+ screen,
+ pixelSize: Math.max(w, h) * (item.scale ?? 1),
+ });
+ }
+ const result = clusterScreenPoints({
+ points,
+ pixelRange: set.spec.cluster.pixelRange,
+ minimumClusterSize: set.spec.cluster.minimumSize,
+ viewHeight: viewport.height,
+ eyeHeight: toCartographicRadians(e.position).height,
+ previous: set.clusters?.state ?? null,
+ project,
+ isOccluded,
+ });
+ // Each cluster's icon is asked for, as a renderer drawing it would.
+ for (const cluster of result.clusters)
+ set.spec.cluster.icon?.(cluster.ids.length);
+ set.clusters = {
+ ...result,
+ members: new Set(result.clusters.flatMap((c) => c.ids)),
+ };
+ }
+
function simpleHandle(kind, spec) {
const record = {
kind,
@@ -858,8 +939,40 @@ export function createStubRenderer(options = {}) {
set.kind !== 'models'
)
continue;
+ const clustered = set.kind === 'icons' ? set.clusters : null;
+ // A cluster is picked as its members, seed first, at its position.
+ for (const cluster of clustered?.clusters ?? []) {
+ const seed = set.items.get(cluster.ids[0]);
+ const s = project(cluster.position);
+ if (!seed || !s) continue;
+ const [w = 0, h = 0] = seed.size ?? [];
+ const k = seed.scale ?? 1;
+ if (
+ Math.abs(s.x - x) > (w * k) / 2 + halfW ||
+ Math.abs(s.y - y) > (h * k) / 2 + halfH
+ )
+ continue;
+ const depth = magnitude(sub(cluster.position, eye().position));
+ for (const id of cluster.ids) {
+ const item = set.items.get(id);
+ if (!item) continue;
+ hits.push({
+ set: setId,
+ id,
+ meta: item.meta,
+ surface: false,
+ position: { ...cluster.position },
+ depth,
+ blocked: blockedItem(item),
+ over: (seed.disableDepthTest ?? 0) > depth,
+ order: set.spec.drawOrder ?? 0,
+ seq: set.seq,
+ });
+ }
+ }
for (const item of set.items.values()) {
if (item.show === false) continue;
+ if (clustered?.members.has(item.id)) continue;
const p = itemPosition(set, item);
if (!p || isOccluded(p)) continue;
const distance = magnitude(sub(p, eye().position));