Clustering Pushpins with the Virtual Earth Map Control API
One of the new features introduced in the Virtual Earth Map Control API is Pushpin Clustering. When there are hundreds of pushpin shapes on the map in a dense area, the map can become very cluttered. The pushpins can overlap each other and obscure the map view and make the map difficult to use. Previously, to solve this problem, developers using the Virtual Earth map control would have to either divide groups of pushpins into VEShapeLayers and manually control which layers to show and hide at different zoom levels, or just not show Pushpins at zoom levels if there were too many on the screen. With the v6.2 Virtual Earth Map Control API, this situation has gotten a lot easier to manage with the addition of the pushpin clustering feature.
In the v6.2 Virtual Earth Map Control API, we introduced two new methods on the VEShapeLayer to support pushpin clustering. In a previous blog post awhile back, I talked about the VEShapeLayer class which is designed to group a set of VEShapes so they can be managed as a collective group. The two new methods for pushpin clustering are VEShapeLayer.SetClusteringConfiguration and VEShapeLayer.GetClusteredShapes. The v6.2 Virtual Earth Map Control API is reverse compatible with the previous v6.1 and v6 APIs and does not cluster pushpins by default.
The SetClusteringConfiguration method allows you to specify how you want to cluster shapes in a shape layer. The first parameter is either a VEClusteringType enumeration specifying a known clustering algorithm supported by Virtual Earth, or it can be a reference to a custom function which does the clustering. Currently VEClusteringType can either be VEClusteringType.Grid to specify a grid-based clustering algorithm or VEClusteringType.None which turns off clustering. By default clustering is off if you do not call SetClusteringConfiguration on a VEShapeLayer.
So, you can turn on grid clustering with a single call to SetClusteringConfiguration. Assuming you have a VEShapeLayer reference called shapeLayer, here's the syntax:
shapeLayer.SetClusteringConfiguration(VEClusteringType.Grid);
The built-in grid based clustering algorithm divides the screen into equal-sized squares. If there are more than one VEShape pushpins in a square, they are combined into a cluster. So, at the highest altitude, you will see more clusters and at the lowest altitude (highest level of detail) you will see less clusters, but more individual shapes. So, as you zoom in on clusters to highest level of detail, they will eventually break up and show individual shapes. So, with one line of code, this simple algorithm now reduces clutter on the map significantly and divides shapes up into manageable chunks. By default, pushpin clusters will have a special cluster pushpin icon just like VEShape pushpins have their own default pin icon also. Each cluster will also have a default popup balloon with information about the cluster. The default popup shows the number of shapes in the cluster. In a future blog post, I will show you how to override some of these default settings to provide more advanced customization to pushpin clustering.
Figure 1 below shows a set of pushpins that are not clustered. Figure 2 shows the same set of pushpins clustered with Grid clustering:
 |
 |
| Figure 1. Unclustered Pushpins |
Figure 2. Clustered Pushpins |
If you want to turn off pushpin clustering after you have turned it on, you just have to make the following call:
shapeLayer.SetClusteringConfiguration(VEClusteringType.None);
If you want to know what shapes are in each pushpin cluster, you can do so with the GetClusteredShapes method on the VEShapeLayer which also takes in a VEClusteringType parameter. For example:
var shapeClusters = shapeLayer.GetClusteredShapes(VEClusteringType.Grid)
This call returns an array of VEClusterSpecification objects representing the set of shape clusters with the passed in clustering type. Each VEClusterSpecification object in the array represents a cluster. The Shapes property on the object specifies the pushpins in the cluster. The LatLong property is a VELatLong and specifies the Latitude, Longitude location of the center of the cluster where the cluster icon is positioned. This provides all the information you have for a cluster, so no information is lost when pushpins are clustered. Also, this method works even when clustering is off. So, if you want to have a complete custom rendering for a cluster, or just know what shapes would be clustered if you turned clustering on, you can use this method.
Click on the link below to see a sample of pushpin clustering with Virtual Earth.
Virtual Earth Map Control API Clustering Sample
Keith Kinnan
Software Development Lead, Virtual Earth Platform