Label/Billboard/Point clustering

[bagnell]

Adds label, billboard, and point clustering. There is a new object on each data source called clustering. This has properties enabled, pixelRange and minimumClusterSize. There is also clusterEvent that is raised for every new cluster. The parameters to the callback are the array of entities being clustered and an entity that will be drawn for the cluster. The label and billboard properties for the second entity parameter are the only things considered when drawing the cluster.

TODO:

• Fix existing tests
• Add new tests
• Update doc
• Update CHANGES.md
• Update LICENSE.md for kdbush
• Submit issues for deprecated function parameters

[bagnell]

If you run the Sandcastle and switch to 2D/CV, all of the labels and billboards are in the wrong position. That isn't a problem with the new code. The same problem exists in master with the KML Sandcastle example. I think the problem is in the clamp-to-ground code.

[pjcozzi]

Note that this is being merged into cluster-master as we don't anticipate this making 1.25 despite thinking otherwise offline.

[colek42]

We don't mind the clusters being out of sync. Most of the movement in our time dynamic data is sub pixel at the zoom levels we will be using it at. We would appreciate a recluster() function that we can call to ensure that the clusters are updated once in a while. Clustering is one of the biggest feature requests that we get. Thanks for working on it.

[mramato]

Have we thought about allowing cluster selection to see what's in the cluster? Not saying it needs to be part of this PR, but no default handling for a cluster seems incomplete. We've talked about multiselection in the past and having multiple tabs in the InfoBox to do it. (or we could show the clusters description, which if set, currently does nothing).

[mramato]

Can we make these checkboxes, the toggle button is confusing because you don't know what state it's in.

[bagnell]

@mramato We discussed the issues with how clustering works offline. I submitted changes to fix time-dynamic data like we discussed as well and fixed the issue when removing points. This is ready for another review.

[mramato]

Using the cluster demo:

1. Switch to 2D (you'll get some weird billboard flashing)
2. Disable clustering
3. Everything is broken

Similar problems in Columbus View

[mramato]

To experiment with custom styling, I tried making a point where the size depends on the size of the cluster (instead of a billboard). Is there a reason this doesn't work?

removeListener = dataSource.clustering.clusterEvent.addEventListener(function(cluster, entity) {
    entity.label = undefined;
    entity.point = {
        pixelSize : cluster.length
    };
});

[bagnell]

Using the cluster demo:

1. Switch to 2D (you'll get some weird billboard flashing)
2. Disable clustering
3. Everything is broken

This was mentioned above. The labels are clamped to the ground and its broken. Open the KML example that uses the same KML file and you'll see the same behavior.

[bagnell]

To experiment with custom styling, I tried making a point where the size depends on the size of the cluster (instead of a billboard). Is there a reason this doesn't work?

The code that adds the cluster is here: https://github.com/AnalyticalGraphicsInc/cesium/pull/4240/files#diff-3ca360d29d7d55bfdc7322d4e18721e7R157

Its pretty limited because I wanted to keep it close to the cluster position and limit the size so it doesn't overlap other clusters. I'm open to any suggestions here.

[mramato]

This was mentioned above. The labels are clamped to the ground and its broken. Open the KML example that uses the same KML file and you'll see the same behavior.

That breakage is worst than I thought then. We should fix this ASAP. I'll mark those issues as next release.

[bagnell]

@mramato I updated the custom styling like we discussed offline. This is ready for another look.

[mramato]

The doc needs to be updated, but then I think this is good to go.

[bagnell]

@mramato The doc is updated. This is ready.

[mramato]

Thanks @bagnell!