Clustering groups points into clusters based on their spatial proximity to one another. Clusters can reveal information that is difficult to visualize when there are hundreds or thousands of points in a map that may overlap or cover each other. Adopt clustering if you want to discover patterns in your data, such as:
- Identify where students live in a city so that the local government can plan appropriate educational and accommodation resources. Clustering allows you to visualize this data without revealing the individual student addresses.
- Visualize the most common type of environmental complaints that are registered across a city so that authorities can plan how to deploy their environmental officers.
- Ensure that police units are evenly spread throughout city so that a rapid response time can be maintained for emergency calls from the public.
In the map below, for example, various power plants of north-west Europe are clustered together so that you can easily see the count of power plants in each region. The size of each cluster is proportional to the number of points in each cluster and is recalculated when the map is zoomed.
Clustering can be defined on a point feature layer authored and published using the ArcGIS Online Map Viewer or ArcGIS Pro. If you add a feature layer from an ArcGIS feature service, web map, or mobile map package to your app, any predefined clustering displays automatically.
If the published point feature layer is not enabled with clustering, or if you want to cluster point graphics, you can use this SDK to define clustering by following the steps detailed in Enable clustering. You can enhance the visual representation of the clusters and display summary statistics of the clustered point attributes (not just the number of points) by using a variety of more complex renderers, labels, and popups, as described in Enhanced statistics and renderers.
Enable clustering
To cluster point-based features or graphics in your app, you need to create a ClusteringFeatureReduction object that takes a renderer. The renderer determines the cluster's color and shape, but the cluster's size is determined by the number of points in the cluster. So, a cluster with more points is bigger than a cluster with fewer points. You can cluster point features or graphics as follows:
- Create a
SimpleRendererusing aSimpleMarkerSymbol. - Create a
ClusteringFeatureReductionusing the simple renderer. - Pass the
ClusteringFeatureReductionto theFeatureLayer::featureReductionor theGraphicsOverlay::featureReduction().
// Create a new simple marker symbol using the default constructor. SimpleMarkerSymbol* simpleMarkerSymbol = new SimpleMarkerSymbol(this); // Set the color for the simple marker symbol. simpleMarkerSymbol->setColor(Qt::cyan); // Create a new simple renderer from the simple marker symbol. SimpleRenderer* simpleRenderer = new SimpleRenderer(simpleMarkerSymbol, this); // Create a new clustering feature reduction from the simple renderer. m_clusteringFeatureReduction = new ClusteringFeatureReduction(simpleRenderer, this); // Set the feature layer's feature reduction. featureLayer->setFeatureReduction(m_clusteringFeatureReduction); The map below contains a single point symbol for the 8000+ power plants in the United States. On the right side, the points are aggregated into clusters using the default clustering values. Every time the mapview's viewpoint changes the clusters may be recalculated and their symbols redrawn.
Label clusters
The number of points in the cluster is stored in a field called "cluster_count" and is updated every time the cluster redraws. You can display this information in the clusters label, as follows:
- Create a
LabelDefinitionthat uses aSimpleLabelExpressionof "[cluster_count]" and a blackTextSymbol. - Set label definition placement.
- Add the label definition to the
ClusteringFeatureReduction.
// Create a new simple label expression using the derived field name "[cluster_count]" from // the clustering. SimpleLabelExpression* simpleLabelExpression = new SimpleLabelExpression("[cluster_count]", this); // Create a new text symbol using the supplied inmput parameters. TextSymbol* textSymbol = new TextSymbol( simpleLabelExpression->expression(), // The simple label expression to display ("[cluster_count]"). Qt::black, // A color. 15, // Size of the text symbol. HorizontalAlignment::Center, // The horizontal alignment enum. VerticalAlignment::Baseline, // The vertical alignment enum. this); // The parent object. // Create a new label definition using the simple label exression and text symbol. LabelDefinition* labelDefinition = new LabelDefinition(simpleLabelExpression, textSymbol, this); // Set the label definition's placement to be the point center center enum. labelDefinition->setPlacement(LabelingPlacement::PointCenterCenter); // Get the label definition list model from the cluster feature reduction. LabelDefinitionListModel* labelDefinitionListModel = m_clusteringFeatureReduction->labelDefinitions(); // Add the label definition to the label definition list model. labelDefinitionListModel->append(labelDefinition); The map below shows clusters labeled with a SimpleLabelExpression.
Configure clusters
The process of clustering groups points into clusters based on an area of influence defined in screen space by the ClusteringFeatureReduction::radius(). This radius has a default value which is 60 device-independent pixels (dpi), but you can set it to a higher value to aggregate points from a larger area or to a lower value to aggregate points from a smaller area. The size of each cluster symbol on the map is proportional to the number of features within the cluster and is recalculated every time the viewpoint changes.
// Set clustering feature reduction's radius. m_clusteringFeatureReduction->setRadius(120); The map below shows points clustered with a clustering radius of 120.
Enhanced statistics and renderers
You can enhance the information displayed to your users by presenting statistical information, such as the average, max, and mode value of the cluster's point attributes. First, you need to aggregate, or summarize, the cluster's point data, and then you can:
- Apply advanced renderers, such as class break and unique value renderers.
- Configure labels that use simple or Arcade expressions.
- Design user friendly popup text.
Aggregate the point data
First, examine the attributes in your feature layer or graphics overlay and decide which attributes you want to summarize. Next, specify how the attribute values are summarized and store the results in an aggregate field, as follows:
- Create a new
AggregateFieldfor each statistical operation you want to perform on an attribute. Give it aname. - Set the
statisticas the attribute (from the feature layer or graphic overlay) you want to analyze.Field Name - State the
AggregateStatisticType, such as count, average, mode, and max, that will be applied to thestatistic.Field Name - Add a collection of your aggregate fields to your
ClusteringFeatureReductionso they can be used by its renderer, label, and popup definitions.
The code below creates and adds 3 AggregateField objects to the ClusteringFeatureReduction. In the first one, for example, the value of the "fuel1" field that appears most often (mode value) is stored in the "most_common_fuel" aggregate field, the average value of the "capacity_mw" field is stored in the "average_capacity_mw" aggregate field and so on.
// Create a new aggregate field for the `most common fuel` using the input parameters. AggregateField* aggregateField_Fuel = new AggregateField( "most_common_fuel", // String name to be created in the aggregate field for the cluster. "fuel1", // A string that is the field name in the cluster source attributes. AggregateStatisticType::Mode, // Aggregate statistic enum to use. this); // Parent object. // Create a new aggregate field for the `avergate capacity mw` using the input parameters. AggregateField* aggregateField_AvgCapacity = new AggregateField( "average_capacity_mw", // String name to be created in the aggregate field for the cluster. "capacity_mw", // A string that is the field name in the cluster source attributes. AggregateStatisticType::Average, // Aggregate statistic enum to use. this); // Parent object. // Create a new aggregate field for the `total capacity mw` using the input parameters. AggregateField* aggregateField_TotCapacity = new AggregateField( "total_capacity_mw", // String name to be created in the aggregate field for the cluster. "capacity_mw", // A string that is the field name in the cluster source attributes. AggregateStatisticType::Sum, // Aggregate statistic enum to use. this); // Parent object. // Get the aggregate field list model from the the clustering feature reduction. AggregateFieldListModel* aggregateFieldListModel = m_clusteringFeatureReduction->aggregateFields(); // Add the aggregate field for the `most common fuel` to the aggregate field list model. aggregateFieldListModel->append(aggregateField_Fuel); // Add the aggregate field for the `avergate capacity mw` to the aggregate field list model. aggregateFieldListModel->append(aggregateField_AvgCapacity); // Add the aggregate field for the `total capacity mw` to the aggregate field list model. aggregateFieldListModel->append(aggregateField_TotCapacity); Apply a class breaks renderer
You can apply a renderer to the cluster to display the value of the aggregate fields. Class breaks renderers are useful if you want to apply different colors to ranges of values. You can apply a class breaks renderer to the cluster as follows:
- For each range of values, create a
ClassBreakand assign aSimpleMarkerSymbolwith a unique color. - Create a
ClassBreaksRendererfor the aggregate field and provide the collection of class breaks. - Pass the class breaks renderer to the constructor of the
ClusteringFeatureReductionand pass that toFeatureLayer::featureReductionorGraphicsOverlay::featureReduction().
// Create a series of class breaks to be used in a class breaks renderer. // Create a new class break using the supplied inmput parameters. ClassBreak* classBreak1 = new ClassBreak( "<5000", // Display label for the class break. " Power plants will less that 5000 megawatts capacity.", // Description for the class break. 0, // Minimum value of the class break. 5000, // Maximum value of the class break. new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, Qt::cyan, 3, this), // Define a new simple marker symbol. this); // Parent object. // Create a new class break using the supplied inmput parameters. ClassBreak* classBreak2 = new ClassBreak( ">5000 to 10000", ">Power plants with 5000 to 10000 megawatts capacity.", 5001, 10000, new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, Qt::magenta, 5, this), this); // Create a new class break using the supplied inmput parameters. ClassBreak* classBreak3 = new ClassBreak( ">10000 to 15000", ">Power plants with 10000 to 15000 megawatts capacity.", 10001, 15000, new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, Qt::green, 7, this), this); // Create a new class break using the supplied inmput parameters. ClassBreak* classBreak4 = new ClassBreak( ">15000 to 50000", ">Power plants with 15000 to 50000 megawatts capacity.", 150001, 500000, new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, Qt::yellow, 9, this), this); // Create a new class break using the supplied inmput parameters. ClassBreak* classBreak5 = new ClassBreak( ">50000", // Display label for the class break. ">Power plants above 50000 megawatts capacity.", 500001, 1000000, new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, Qt::red, 11, this), this); // Create a new class break renderer using the default constructor. ClassBreaksRenderer* classBreaksRenderer = new ClassBreaksRenderer(this); // Set the field name in the attributes for the class break renderer. classBreaksRenderer->setFieldName("total_capacity_mw"); // Get the class break list model from the class breaks renderer. ClassBreakListModel* classBreakListModel = classBreaksRenderer->classBreaks(); // Add all of the class breaks to the class break list model. classBreakListModel->append(classBreak1); classBreakListModel->append(classBreak2); classBreakListModel->append(classBreak3); classBreakListModel->append(classBreak4); classBreakListModel->append(classBreak5); // Set the renderer on the clustering feature reduction. m_clusteringFeatureReduction->setRenderer(classBreaksRenderer); The map below shows the clusters rendered with a class breaks renderer and reflects the range of total values. For example, the red color indicates that the sum of the capacity of all the points in a cluster is greater than 50000 MW.
Configure label expressions
As shown previously, you can label each cluster with the number of points in the cluster. However, now that you have created some aggregate fields, you can use these to label the clusters by configuring a SimpleLabelExpression or an ArcadeLabelExpression.
In the map below, the most aggregate field value of each cluster is displayed in a label by using a SimpleLabelExpression. For more information about how to format simple expression strings, see Simple expressions.
// Create a new simple label expression using the attribute from the source data. SimpleLabelExpression* simpleLabelExpression = new SimpleLabelExpression("[most_common_fuel]", this); 
In the map below, the total aggregate field value of each cluster is reformated, concatenated with the "MW", and displayed in a label by using an ArcadeLabelExpression. For more information about how to format Arcade expression strings, see Arcade expressions.
// Create a new arcade label expression using string relevent to the source data. ArcadeLabelExpression* arcadeLabelExpression = new ArcadeLabelExpression( "Concatenate([Text($feature.total_capacity_mw, '###,###') + ' MW'])"); 
Configure popup expressions
You can configure your app to display a popup when the user clicks on a cluster. By default, the cluster's popup displays its "point_count" value; the number of points in the cluster. If the ClusteringFeatureReduction has aggregate fields, the cluster popup will display the aggregate field values. However, if you want to present a more user-friendly text, you can create an Arcade expression, as follows:
- Create a
PopupDefinitionusing theClusteringFeatureReduction. - Assign the popup definition to the clustering feature reduction.
- Specify a title and remove all elements from the popup definition.
- Create a
PopupExpression, provide an Arcade expression, and specify that the return type is string. In this example, the Arcade expression reformats and concatenates a few aggregate fields representing the average and total capacities, along with some helpful text. - Create an
ExpressionPopupElementusing the popup expression. - Add the expression popup element to the popup definition's collection of elements.
For more information about how to add popups to your app, see the Popup view component.
// Create a new popup definition using the clustering feature reduction. PopupDefinition* popupDefinition = new PopupDefinition(m_clusteringFeatureReduction, this); // Set the popup definition on the clustering feature reduction. m_clusteringFeatureReduction->setPopupDefinition(popupDefinition); // Set title on the popup definition. m_clusteringFeatureReduction->popupDefinition()->setTitle("Cluster Summary"); // Clear all of the elements on the existing popup definition. m_clusteringFeatureReduction->popupDefinition()->elements().clear(); // Create a new popup expression (average capacity) using the default constructor. PopupExpression* popupExpression_AvgCapacity = new PopupExpression(this); // Set the Arcade expression relevent to the sourcde data on th popup expression. popupExpression_AvgCapacity->setExpression( "var result = Concatenate(['The power plants in this cluster have an average capacity of ' +" " Text($feature.average_capacity_mw, '#.00') + ' megawatts and produce a total of ' +" " Text($feature.total_capacity_mw, '###,###.00') + ' megawatts of power.']);" " return { type : 'text', text : result };"); // Define the return type enum (String) on the popup expression. popupExpression_AvgCapacity->setReturnType(PopupExpressionReturnType::String); // Create a new expression popup element for the (average capacity) using the popup expression. ExpressionPopupElement* expressionPopupElement_AvgCapacity = new ExpressionPopupElement(popupExpression_AvgCapacity, this); // Create a new popup expression (common fuel) using the default constructor. PopupExpression* popupExpression_CommonFuel = new PopupExpression(this); // Set the Arcade expression relevent to the sourcde data on th popup expression. popupExpression_CommonFuel->setExpression( "var result = Concatenate(['Most power plants in this cluster generate power from ' +" " $feature.most_common_fuel + '.']); return { type : 'text', text : result };"); // Define the return type enum (String) on the popup expression. popupExpression_CommonFuel->setReturnType(PopupExpressionReturnType::String); // Create a new expression popup element for the (common fuel) using the popup expression. ExpressionPopupElement* expressionPopupElement_CommonFuel = new ExpressionPopupElement(popupExpression_CommonFuel, this); // Get the QList of popup elements from the popup definition;s elements collection. QList<PopupElement*> popupElements = m_clusteringFeatureReduction->popupDefinition()->elements(); // Add the (average capacity) expression popup element to the popup elements. popupElements.append(expressionPopupElement_AvgCapacity); // Add the (common fuel) expression popup element to the popup elements. popupElements.append(expressionPopupElement_CommonFuel); The map below shows a popup configured with a PopupExpression.
Explore a cluster
Each cluster of points is an aggregation of geoelements called an AggregateGeoElement. If you want to find out which geoelements are aggregated into an single cluster, retrieve the cluster's collection of geoelements by calling AggregateGeoElement.geoElementsAsync. You can then iterate through the collection to display individual geoelement attribute values, for example.
// NOTE: An aggregate geoElement is typically obtained from an identify type of operation // on an cluster in the map (ex: identifyLayerResult->geoElements()->first() or // identifyLayerResult->popups()->first()->geoElement(), etc...). // If we have an aggregate geoElement selected continue. if (m_aggregateGeoElement->isSelected()) { // Call the geoElements async method on the aggregate geoElement. The return value is // a QList of geoElement objects. m_aggregateGeoElement->geoElementsAsync(this).then(this,[](QList<GeoElement*> qListGeoElements) { // Iterate over each geoElement in the QList of geoElements. for (GeoElement* geoElement : qListGeoElements) { // If you have mix of FeatureLayers and GraphicsOverlays in your map, you can // check for the type of geoElement to be a Feature or Graphic, for example. if (dynamic_cast<Feature*>(geoElement)) { // Get the attribute list model for the geoElement. AttributeListModel* attributeListModel = geoElement->attributes(); // Get the geoElement's 'name' attribute. const QString geoElementName = attributeListModel->attributeValue("name").toString(); // Print the current geoElement's 'name' in the debug window. qDebug() << geoElementName; } } }); } 
