From c57eb745062b72b6995600c480e705e2827eca23 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 14 Nov 2026 00:29:26 -0800 Subject: [PATCH] fix(radio): a cluster kept from the last pass names the same station first Points too close together on screen are grouped by geo/screenCluster.js as the default renderer's entity clustering grouped them. Its range queries ran on a uniform grid sorted by index, while the reference queries a KDBush tree, so a cluster kept as the eye came lower could list its stations in another order, and a click on it played a different station. The index is now KDBush, built as the reference builds it, and kdbush is a declared dependency (it already came with the globe). The package boundaries list kdbush as external wherever screenCluster is owned, and own src/viewSky.js beside src/viewWeather.js. --- THIRD_PARTY_NOTICES.md | 8 ++++ package-lock.json | 1 + package.json | 1 + scripts/package-boundaries.json | 69 +++++++++++++++++++-------------- src/geo/screenCluster.js | 52 +++++++------------------ src/geo/screenCluster.test.mjs | 48 ++++++++++++++++++++++- 6 files changed, 109 insertions(+), 70 deletions(-) diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 4ed2ea418..8f4f5f224 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -60,3 +60,11 @@ Street Level viewer and the Data Library's GeoParquet reader; the complete resol - Author: Copyright (c) 2020 Arjun Barrett - Source: - License: MIT + +## kdbush + +- Package: `kdbush` 4.0.2 (the screen index that groups points drawn too + close together into clusters) +- Author: Copyright (c) 2018, Vladimir Agafonkin +- Source: +- License: ISC diff --git a/package-lock.json b/package-lock.json index a59e07a1e..0166a9c31 100644 --- a/package-lock.json +++ b/package-lock.json @@ -18,6 +18,7 @@ "fzstd": "0.1.1", "hls.js": "^1.7.3", "hyparquet": "1.31.2", + "kdbush": "^4.0.2", "mapillary-js": "^4.1.2", "mgrs": "^2.1.0", "pbf": "^5.1.2", diff --git a/package.json b/package.json index 3ee38cfeb..7ec919044 100644 --- a/package.json +++ b/package.json @@ -72,6 +72,7 @@ "fzstd": "0.1.1", "hls.js": "^1.7.3", "hyparquet": "1.31.2", + "kdbush": "^4.0.2", "mapillary-js": "^4.1.2", "mgrs": "^2.1.0", "pbf": "^5.1.2", diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 7ee370ad9..d44c7b4cf 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -69,7 +69,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium"] + "external": ["cesium", "kdbush"] }, "application": { "exports": ["./application"], @@ -1159,7 +1159,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium"] + "external": ["cesium", "kdbush"] }, "scene-controls": { "exports": ["./ui/scenes"], @@ -1548,7 +1548,8 @@ "pinia", "vue-i18n", "pbf", - "@mapbox/vector-tile" + "@mapbox/vector-tile", + "kdbush" ] }, "ui-styles": { @@ -1738,7 +1739,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium", "vue", "pinia", "vue-i18n"] + "external": ["cesium", "vue", "pinia", "vue-i18n", "kdbush"] }, "live-observations": { "exports": ["./sources/live"], @@ -1892,7 +1893,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium"] + "external": ["cesium", "kdbush"] }, "military-flights": { "exports": ["./layers/military"], @@ -2024,7 +2025,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium"] + "external": ["cesium", "kdbush"] }, "aircraft-mechanics": { "exports": ["./aircraft"], @@ -2173,7 +2174,7 @@ "src/layers/vessels/photos.js", "src/data/openVesselPhoto.js" ], - "external": ["cesium"] + "external": ["cesium", "kdbush"] }, "render-cesium-plugin": { "exports": ["./render/cesium/plugin"], @@ -2297,7 +2298,7 @@ "src/layers/wind/model.js", "src/sky/assets.js" ], - "external": ["cesium", "pbf", "@mapbox/vector-tile"] + "external": ["cesium", "pbf", "@mapbox/vector-tile", "kdbush"] }, "render-cesium-unbound": { "exports": ["./render/cesium/unbound"], @@ -2392,7 +2393,7 @@ "src/render/vectorBase/paint.js", "src/render/vectorBase/expressions.js" ], - "external": ["cesium", "pbf", "@mapbox/vector-tile"] + "external": ["cesium", "pbf", "@mapbox/vector-tile", "kdbush"] }, "earthquakes": { "exports": ["./layers/earthquakes"], @@ -2539,7 +2540,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium"] + "external": ["cesium", "kdbush"] }, "satellites-layer": { "exports": ["./layers/satellites"], @@ -2645,7 +2646,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium", "satellite.js"] + "external": ["cesium", "satellite.js", "kdbush"] }, "launches-layer": { "exports": ["./layers/launches"], @@ -2747,7 +2748,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium"] + "external": ["cesium", "kdbush"] }, "installations-layer": { "exports": ["./layers/installations"], @@ -2857,7 +2858,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium", "@mapbox/vector-tile", "pbf"] + "external": ["cesium", "@mapbox/vector-tile", "pbf", "kdbush"] }, "awareness-layer": { "exports": ["./layers/awareness"], @@ -2938,7 +2939,7 @@ "src/ui/layerNames.js", "src/render/cesium/zoomOutGuard.js" ], - "external": ["cesium"] + "external": ["cesium", "kdbush"] }, "traffic-layer": { "exports": ["./layers/traffic"], @@ -3062,7 +3063,7 @@ "src/render/vectorBase/paint.js", "src/render/vectorBase/expressions.js" ], - "external": ["cesium", "pbf", "@mapbox/vector-tile"] + "external": ["cesium", "pbf", "@mapbox/vector-tile", "kdbush"] }, "bikeshare-layer": { "exports": ["./layers/bikeshare"], @@ -3251,7 +3252,7 @@ "src/render/vectorBase/paint.js", "src/render/vectorBase/expressions.js" ], - "external": ["hls.js", "cesium", "pbf", "@mapbox/vector-tile"] + "external": ["hls.js", "cesium", "pbf", "@mapbox/vector-tile", "kdbush"] }, "street-level-layer": { "exports": [ @@ -3378,7 +3379,13 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium", "pbf", "@mapbox/vector-tile", "mapillary-js"] + "external": [ + "cesium", + "pbf", + "@mapbox/vector-tile", + "mapillary-js", + "kdbush" + ] }, "alpr-cameras": { "exports": ["./layers/alpr"], @@ -3463,7 +3470,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium", "@mapbox/vector-tile", "pbf"] + "external": ["cesium", "@mapbox/vector-tile", "pbf", "kdbush"] }, "radio-layer": { "exports": ["./layers/radio"], @@ -3573,7 +3580,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium"] + "external": ["cesium", "kdbush"] }, "submarine-cables": { "exports": ["./layers/submarine-cables"], @@ -3648,7 +3655,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium"] + "external": ["cesium", "kdbush"] }, "bundled-cables": { "exports": ["./sources/bundled-cables"], @@ -3787,7 +3794,7 @@ "src/render/vectorBase/paint.js", "src/render/vectorBase/expressions.js" ], - "external": ["cesium", "pbf", "@mapbox/vector-tile"] + "external": ["cesium", "pbf", "@mapbox/vector-tile", "kdbush"] }, "voice-connection": { "exports": [ @@ -5259,6 +5266,7 @@ "src/ui/stores/dataLibrary.js", "src/data/openVesselPhoto.js", "src/layers/vessels/photos.js", + "src/viewSky.js", "src/viewWeather.js", "src/render/weather.js" ], @@ -5276,7 +5284,8 @@ "fzstd", "vue", "pinia", - "vue-i18n" + "vue-i18n", + "kdbush" ] }, "application-catalog": { @@ -6088,7 +6097,8 @@ "@jtarrio/webrtlsdr", "vue", "pinia", - "vue-i18n" + "vue-i18n", + "kdbush" ] }, "application-operations": { @@ -6225,7 +6235,8 @@ "satellite.js", "@mapbox/vector-tile", "pbf", - "mgrs" + "mgrs", + "kdbush" ] }, "entity-records": { @@ -6330,7 +6341,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium"] + "external": ["cesium", "kdbush"] }, "ui-share-restoration": { "exports": ["./ui/share-restoration"], @@ -7038,7 +7049,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium", "egm96-universal", "pbf"] + "external": ["cesium", "egm96-universal", "pbf", "kdbush"] }, "transit-layer": { "exports": ["./layers/transit"], @@ -7162,7 +7173,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium", "pbf"] + "external": ["cesium", "pbf", "kdbush"] }, "transit-source-factory": { "exports": ["./layers/transit/source"], @@ -7473,7 +7484,7 @@ "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], - "external": ["cesium"] + "external": ["cesium", "kdbush"] }, "ghostmaps-source": { "exports": ["./layers/ghostmaps/source"], @@ -7881,7 +7892,7 @@ "src/render/vectorBase/encode.js", "src/render/weather.js" ], - "external": ["pbf", "@mapbox/vector-tile"] + "external": ["pbf", "@mapbox/vector-tile", "kdbush"] }, "wildlife-sightings": { "exports": ["./layers/wildlife-sightings"], diff --git a/src/geo/screenCluster.js b/src/geo/screenCluster.js index c21ca1705..5f85dbd5b 100644 --- a/src/geo/screenCluster.js +++ b/src/geo/screenCluster.js @@ -17,6 +17,8 @@ * right and down. */ +import KDBush from 'kdbush'; + /** * @typedef {object} ScreenClusterPoint * @property {string} id @@ -71,7 +73,7 @@ export function clusterScreenPoints({ ys[i] = viewHeight - points[i].screen.y; } const clustered = new Uint8Array(n); - const index = createGridIndex(xs, ys, Math.max(1, pixelRange * 2)); + const index = createIndex(xs, ys); const clusters = []; const kept = []; @@ -164,43 +166,15 @@ function pointBox(x, y, size, pixelRange) { } /** - * A uniform grid over packed coordinates, answering which points lie in a - * box (bounds included), in ascending index order. + * The points' index: a KDBush tree built as the reference renderer's entity + * clustering builds it (64 per node, 64-bit coordinates), so a range query + * lists the same points in the same order and a cluster kept from the last + * pass names the same station first. */ -function createGridIndex(xs, ys, cell) { - const buckets = new Map(); - const key = (cx, cy) => `${cx}:${cy}`; - for (let i = 0; i < xs.length; i++) { - const k = key(Math.floor(xs[i] / cell), Math.floor(ys[i] / cell)); - let bucket = buckets.get(k); - if (!bucket) buckets.set(k, (bucket = [])); - bucket.push(i); - } - return { - range(minX, minY, maxX, maxY) { - const found = []; - if (!(maxX >= minX && maxY >= minY)) return found; - const x0 = Math.floor(minX / cell); - const x1 = Math.floor(maxX / cell); - const y0 = Math.floor(minY / cell); - const y1 = Math.floor(maxY / cell); - if ((x1 - x0 + 1) * (y1 - y0 + 1) > buckets.size) { - for (let i = 0; i < xs.length; i++) - if (xs[i] >= minX && xs[i] <= maxX && ys[i] >= minY && ys[i] <= maxY) - found.push(i); - return found; - } - for (let cx = x0; cx <= x1; cx++) - for (let cy = y0; cy <= y1; cy++) - for (const i of buckets.get(key(cx, cy)) ?? []) - if ( - xs[i] >= minX && - xs[i] <= maxX && - ys[i] >= minY && - ys[i] <= maxY - ) - found.push(i); - return found.sort((a, b) => a - b); - }, - }; +function createIndex(xs, ys) { + if (!xs.length) return { range: () => [] }; + const index = new KDBush(xs.length, 64, Float64Array); + for (let i = 0; i < xs.length; i++) index.add(xs[i], ys[i]); + index.finish(); + return index; } diff --git a/src/geo/screenCluster.test.mjs b/src/geo/screenCluster.test.mjs index 2c535311a..b6157749f 100644 --- a/src/geo/screenCluster.test.mjs +++ b/src/geo/screenCluster.test.mjs @@ -1,5 +1,6 @@ import assert from 'node:assert/strict'; import test from 'node:test'; +import KDBush from 'kdbush'; import { clusterScreenPoints } from './screenCluster.js'; /** A point at screen `x, y` whose world position is `x, y, 0` too. */ @@ -129,8 +130,51 @@ test('many points cluster as a scan of every point would', () => { ids.forEach((id) => done.add(id)); } } + // The same seeds take the same points; the order after the seed is the + // index's, checked below. + const seedThenSorted = (ids) => [ids[0], ...ids.slice(1).sort()]; assert.deepEqual( - result.clusters.map((c) => c.ids), - expected, + result.clusters.map((c) => seedThenSorted(c.ids)), + expected.map(seedThenSorted), ); }); + +test('a cluster lists its points in the reference renderer’s KDBush order, so a kept one names the same point first', () => { + // The reference indexes the points with KDBush (64 per node, 64-bit) and + // lists a cluster's points in the order a range query returns them. + let seed = 11; + const random = () => (seed = (seed * 16807) % 2147483647) / 2147483647; + const points = Array.from({ length: 400 }, (_, i) => + at(`p${i}`, random() * 400, random() * 400), + ); + const index = new KDBush(points.length, 64, Float64Array); + for (const p of points) index.add(p.screen.x, 1000 - p.screen.y); + index.finish(); + const first = run(points); + const [kept] = first.state.clusters; + // Closer, at once: the first kept cluster takes every unclustered point in + // its box, in the index's order. + // (Its box is measured from the top, the index from the bottom.) + const coord = { x: 200, y: 800 }; + const again = run(points, { + eyeHeight: 999_999, + previous: first.state, + project: () => coord, + }); + const width = Math.max(kept.width * 1e-6, kept.minimumWidth); + const height = Math.max(kept.height * 1e-6, kept.minimumHeight); + const expected = index + .range( + coord.x - width * 0.5, + coord.y - height * 0.5, + coord.x + width, + coord.y + height, + ) + .map((i) => points[i].id); + assert.ok(expected.length >= 3, 'the kept cluster holds'); + assert.deepEqual(again.clusters[0].ids, expected); + const ascending = [...expected].sort( + (a, b) => Number(a.slice(1)) - Number(b.slice(1)), + ); + assert.notDeepEqual(expected, ascending, 'the order is not the input order'); +});