Add declusteredEvent to EntityCluster #12920

Oko-Tester · 2025-09-25T07:31:30Z

Fixes #5760 by adding declusteredEvent that provides both clustered and declustered entities, plus new API methods for accessing clustering state. Maintains backward compatibility.

Description

This PR adds comprehensive clustering state information to EntityCluster by introducing a new declusteredEvent and supporting API methods. The original clusterEvent only provided information about entities that were successfully clustered, but developers also needed access to entities that were processed but not clustered (declustered entities).

Key Changes

New declusteredEvent: Fires with complete clustering information including both clustered and declustered entities
New API methods:
- getLastClusteredEntities() - Returns currently clustered entities
- getLastDeclusteredEntities() - Returns currently declustered entities
- getAllProcessedEntities() - Returns all entities processed during clustering
Enhanced event coverage: Events now fire when clustering is disabled or clusters become empty
Backward compatibility: Original clusterEvent remains unchanged and functional

Issue number and link

Fixes #5760 - Include declustered entities in cluster callback

This addresses multiple user requests from the forum and GitHub comments spanning several years.

Testing plan

Manual Testing

Create CustomDataSource with clustering enabled
Add entities at various distances to create both clustered and declustered entities
Verify declusteredEvent fires with correct clustered and declustered arrays
Disable clustering and verify event fires with all entities as declustered
Test API methods return correct entity lists
Verify original clusterEvent still works as before

Author checklist

I have submitted a Contributor License Agreement
I have added my name to CONTRIBUTORS.md
I have updated CHANGES.md with a short summary of my change
I have added or updated unit tests to ensure consistent code coverage
I have updated the inline documentation, and included code examples where relevant
I have performed a self-review of my code

github-actions · 2025-09-25T07:31:58Z

Thank you for the pull request, @Oko-Tester!

✅ We can confirm we have a CLA on file for you.

packages/engine/Source/DataSources/EntityCluster.js

Oko-Tester · 2025-09-26T12:09:36Z

this is ready

packages/engine/Source/DataSources/EntityCluster.js

Fixes CesiumGS#5760 by adding declusteredEvent that provides both clustered and declustered entities, plus new API methods for accessing clustering state. Maintains backward compatibility.

… skipping unused declustering computations

Oko-Tester · 2025-10-04T12:54:16Z

@mzschwartz5 Is there any news regarding the approval?

mzschwartz5 · 2025-10-06T16:25:04Z

Hi @Oko-Tester, I haven't had a chance to review this yet. It might not happen until Thursday as I'm out tomorrow and Wednesday.

mzschwartz5

Hey @Oko-Tester,

Thanks for the PR. I have a number of mostly minor comments about code style and performance, but those might be irrelevant because I'm a little unsure of the overall approach. It's a lot of extra state that we're tracking now, which means more memory consumed, more bookkeeping to sync arrays, more room for potential edge cases.

In the linked issue you said "clusterEvent does not fire when a cluster becomes empty, which makes it impossible to detect de-clustered entities." My intuition is that there's a better way to deal with this than to track more state and manually fire the decluster event accordingly. I haven't actually looked at the code closely to tell, but that's my instinct.

packages/engine/Source/DataSources/EntityCluster.js

mzschwartz5 · 2025-10-17T01:39:18Z

packages/engine/Specs/DataSources/EntityClusterSpec.js

I'm not an expert on unit testing philosphy, so maybe this is a bad suggestion, but could we maybe have unit test(s) that check that clustering generally works for all three of: points, billboards, and labels (collections)?

I'm just a little wary given the discussion about using the item.show property as if these classes all have a shared abstract interface (which they don't). I don't expect that to be an issue, but if someone were to ever change that property name on one of the classes, at least having a failing unit test here would prevent the issue.

Oko-Tester · 2025-10-17T10:25:01Z

Hey @mzschwartz5,
Thanks for your feedback. I'll rethink my current implementation and maybe find a better way. But I won't be able to deal with this MR for a few days.

As for your comment on unit tests, I am not an expert in this field either, but it seems sensible to me to use them to avoid potential future problems.

Oko-Tester · 2025-10-28T20:51:50Z

Okay, I rethought my current implementation and realized that I had adapted the component too much for my specific needs.
It would be better to simply add a single event that returns the last declustered entities — nothing more. The rest can easily be handled manually by the user.

I’ve reset the EntityCluster component locally and will commit the new changes shortly after testing them. I also need to update the tests to match the new implementation.

I’d really appreciate your feedback on this new approach once the changes are pushed.

mzschwartz5 · 2025-10-28T21:26:45Z

@Oko-Tester When you're ready, just re-request review from me and/or leave a comment saying you're ready for another pass. Depending on when it's ready, I may need a few days before I can take another look.

mzschwartz5 · 2025-11-04T18:05:38Z

packages/engine/Source/DataSources/EntityCluster.js

+    if (newClusters.length > 0 && defined(clusteredLabelCollection)) {
+      for (let c = 0; c < clusteredLabelCollection.length; ++c) {
+        const clusterLabel = clusteredLabelCollection.get(c);
+        if (defined(clusterLabel) && defined(clusterLabel.id)) {
+          currentlyClusteredIds.push(...clusterLabel.id);
+        }
+      }
+    }


Why do we need to check newClusters.length > 0?

Will it ever be the case that clusterLabel or clusterLabel.id is not defined? When?

Why do we need to use the spread operator (...) when pushing an ID? To make a copy of it (if so, why isn't a reference sufficient?)

Why check newClusters.length > 0?
This check is redundant. If there are no clusters, clusteredLabelCollection.length would be 0 anyway, so the loop wouldn't execute. I'll remove this check.

Will clusterLabel or clusterLabel.id ever be undefined?
In normal operation, no. clusterLabel.id is always set in addCluster(). I think keeping these defensive checks for safety would be good.

Why use the spread operator (...)?
Because clusterLabel.id is an array of entity IDs (set in addCluster()), not a single ID. The spread operator flattens it. Without it, you'd have an array of arrays instead of a flat array of IDs.

Random drive-by comment:

In normal operation, no. clusterLabel.id is always set in addCluster(). I think keeping these defensive checks for safety would be good.

When something should never be undefined, then this should be a contract that people can rely on. When one of these things is ever undefined, then this is a bug, and it will show up as a crash, with a clear stack trace. With these checks, it will not show up with a stack trace. But it will still be a bug. And this bug will only show up as an issue like "Sometimes some labels are not properly shown in some clusters at some zoom level" or so. And one can easily spend 5 or 10 hours of painful debugging to find the reason for an issue like that.

I know, there are different philosophies. But there's an important difference between being "defensive"/"resilient", and what I refer to as "fail silent".
"Defensive" would mean that there is a defined check, and when the thing is undefined, then it does not crash, but it still logs an error to the console, saying "This is undefined, but it never should be". Ideally, this should not be necessary within a library. It should only be necessary for things that are provided from outside, via the public API. But... that ship has sailed.
"Fail silent" means that something is wrong, and there's not way to figure out what is wrong. That's not good.

Good point, I didn’t consider that. I think it was mentioned earlier in this PR, but you’re right, better to fail visibly than silently.

Okay so sounds like we can address points 1 and 2 easily.

For point 3 (the spread operator) - are we copying the all currently clustered IDs (i.e. every ID of every entity that is clustered) on every declutter callback? That seems like it could be bad for performance. It also doubles the memory we consume in tracking which entities are clustered (since we always have a copy of the previouslyClustered...)

Side note: does this only fire a declustered event for clusteredLabelCollection? But not for clusteredBillboardCollection or clusteredPointCollection?

mzschwartz5 · 2025-11-04T18:07:32Z

packages/engine/Source/DataSources/EntityCluster.js

  this._removeEventListener = undefined;

  this._clusterEvent = new Event();
+  this._declusterEvent = new Event();


I feel like this is a bit misleading. clusterEvent fires whenever a new cluster is added, right? But declusterEvent only fires when all clusters are removed. (If I've understood this PR correctly)

It seems like declusterEvent should also fire whenever a cluster is removed. (I don't know if that's feasible to implement, though)

You are correct about the asymmetry. The behavior is as follows:
clusterEvent: Triggered every time addCluster is called, which happens in the following cases:

When new clusters are created
When existing clusters are reused (when the camera zooms in and they still meet the minimumClusterSize threshold)

declusterEvent: Only fires when transitioning from "has clusters" to "no clusters at all". It does NOT fire when individual clusters are removed.
However, users can still detect which clusters have been removed by tracking the entity IDs themselves. Since clusterEvent is triggered every frame with the current cluster composition, you can compare frame by frame to determine which entities were declustered.

A wild guess is that this question may have to do with the name.

When you have methods like
addSomething/removeSomething or
createSomething/destroySomething
then you'd also expect a certain "symmetry".
_{(And when you have addSomething, removeSomething, and deleteSomething, you'll wonder: Wait what...?)}

In this case, one could expect this event to be raises when ... the opposite of that happened what causes a clusterEvent. Yes, there is the documentation that says that this event "... will be raised when all entities have been declustered.", but still.

@mzschwartz5 It's up to you, but I think that options could be to

rename this event (to something like declusteredAllEvent or allDeclusteredEvent or ... whatever is appropriate here)

and (!!!optional!!!) consider adding a declusterEvent that indeed is the opposite of what clusterEvent is doing

Yes, you’re right about the naming confusion. I think we should rename the event to lastDeclusterEvent (or allDeclusteredEvent, whatever you prefer) so it’s clear that it only fires when the last cluster is removed. But there’s no real need for a new event that tracks every declustering — users can already detect removed clusters by comparing the cluster composition from the clusterEvent. So I don’t think an additional event for every declustering is necessary.

I'm not deeply involved here - it was just a comment while looking at my GitHub notifications. So I don't know in how far it makes sense to define an event for individual removed clusters. But... (again: a bit shallow)...:

users can already detect removed clusters by comparing the cluster composition from the clusterEvent. So I don’t think an additional event for every declustering is necessary.

Users can do a lot of stuff. Users can track this and that and store this and that and compute some difference here and there. The question is whether there's a convincing use case for being informed about individual clusters. If there is, then uers should not be forced to write 200 lines of (possibly buggy) code to derive the information they need, when they could just listen for a single, predefined event.

Maybe there is no such use case. And in doubt, this new event could be added later, when the demand arises. And following the mantra: "When in doubt, leave it out!", it's probably OK to omit it for now (and certainly in the context of this PR)

I generally agree with @javagl, I and I think it would be sufficient for this PR to simply rename this event. I liked the proposed "allDeclusteredEvent"

mzschwartz5 · 2025-11-04T18:08:04Z

packages/engine/Source/DataSources/EntityCluster.js

 * });
 */
+/**
+ * A event listener function used when all entities have been declustered.


Small typo- "A event" --> "An event"

javagl reviewed Sep 25, 2025

View reviewed changes

packages/engine/Source/DataSources/EntityCluster.js Outdated Show resolved Hide resolved

Oko-Tester force-pushed the fix-issue-5760-declustered-entities branch from 746701c to 2d42fdc Compare September 26, 2025 12:07

Oko-Tester marked this pull request as ready for review September 26, 2025 12:07

mzschwartz5 reviewed Sep 26, 2025

View reviewed changes

packages/engine/Source/DataSources/EntityCluster.js Outdated Show resolved Hide resolved

mzschwartz5 reviewed Sep 26, 2025

View reviewed changes

packages/engine/Source/DataSources/EntityCluster.js Outdated Show resolved Hide resolved

javagl and others added 6 commits September 29, 2025 10:42

Cache rectangle in ClippingPolygon

04fcc53

Add declusteredEvent to EntityCluster

2c9215f

Fixes CesiumGS#5760 by adding declusteredEvent that provides both clustered and declustered entities, plus new API methods for accessing clustering state. Maintains backward compatibility.

perf: optimize entity clustering by avoiding spread on large sets and…

5d851e7

… skipping unused declustering computations

docs: updated CHANGES.md

126337f

test: extend EntityClusterSpec to cover declusteredEvent

5f40635

refactor: reduce nesting and extract duplicate collection logic

587e235

Oko-Tester force-pushed the fix-issue-5760-declustered-entities branch from 9bd82e9 to 587e235 Compare September 29, 2025 08:43

Merge branch 'main' into fix-issue-5760-declustered-entities

5224ff1

ggetz assigned mzschwartz5 Sep 29, 2025

Oko-Tester added 2 commits October 1, 2025 11:39

Merge branch 'main' into fix-issue-5760-declustered-entities

a11b0b8

Merge branch 'main' into fix-issue-5760-declustered-entities

f0b1458

mzschwartz5 requested changes Oct 17, 2025

View reviewed changes

Add declusterEvent to EntityCluster

5ec4ced

mzschwartz5 reviewed Nov 4, 2025

View reviewed changes

Add declusteredEvent to EntityCluster #12920

Are you sure you want to change the base?

Add declusteredEvent to EntityCluster #12920

Conversation

Oko-Tester commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Key Changes

Issue number and link

Testing plan

Manual Testing

Author checklist

Uh oh!

github-actions bot commented Sep 25, 2025

Uh oh!

Uh oh!

Oko-Tester commented Sep 26, 2025

Uh oh!

Uh oh!

Uh oh!

Oko-Tester commented Oct 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mzschwartz5 commented Oct 6, 2025

Uh oh!

mzschwartz5 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Oko-Tester commented Oct 17, 2025

Uh oh!

Oko-Tester commented Oct 28, 2025

Uh oh!

mzschwartz5 commented Oct 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

javagl Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mzschwartz5 Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Oko-Tester Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Oko-Tester commented Sep 25, 2025 •

edited

Loading

Oko-Tester commented Oct 4, 2025 •

edited

Loading

mzschwartz5 left a comment •

edited

Loading

javagl Nov 6, 2025 •

edited

Loading

mzschwartz5 Nov 6, 2025 •

edited

Loading

Oko-Tester Nov 6, 2025 •

edited

Loading