Configure clusters

View on GitHubSample viewer app

Add client side feature reduction on a point feature layer that is not pre-configured with clustering.

screenshot

Use case

Feature clustering can be used to dynamically aggregate groups of points that are within proximity of each other in order to represent each group with a single symbol. Such grouping allows you to see patterns in the data that are difficult to visualize when a layer contains hundreds or thousands of points that overlap and cover each other. Users can add feature clustering to point feature layers. This is useful when the layer does not have the feature reduction defined or when the existing feature reduction properties need to be overridden.

How to use the sample

Tap the Draw clusters button to set new feature reduction object on the feature layer. Interact with the controls to customize clustering feature reduction properties. Tap on any clustered aggregate geoelement to see the cluster feature count and aggregate fields in the popup.

How it works

  1. Create a map from a web map PortalItem.
  2. Create a ClassBreaksRenderer and define a FieldName and DefaultSymbol. FieldName must be one of the summary fields in the AggregateFields collection.
  3. Add ClassBreak objects each with an associated SimpleMarkerSymbol to the renderer.
  4. Create a ClusteringFeatureReduction using the renderer.
  5. Add AggregateField objects to the feature reduction where the FieldName is the name of the field to aggregate and the StatisticType is the type of aggregation to perform.
  6. Define the MinSymbolSize and MaxSymbolSize for the feature reduction. If these are not defined they default to 12 and 70 respectively.
  7. Add the ClusteringFeatureReduction to the FeatureLayer.
  8. Create a LabelDefinition with a SimpleLabelExpression and TextSymbol to define the cluster label.
  9. Configure a GeoViewTapped event handler on the MapView to display feature cluster information in a Label.

Relevant API

  • AggregateGeoElement
  • ClassBreaksRenderer
  • FeatureLayer
  • FeatureReduction
  • GeoElement
  • IdentifyLayerResult

About the data

This sample uses a web map that displays residential data for Zurich, Switzerland.

Tags

aggregate, bin, cluster, group, merge, normalize, popup, reduce, renderer, summarize

Sample Code

ConfigureClusters.cppConfigureClusters.cppConfigureClusters.hConfigureClusters.qml
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
// [WriteFile Name=ConfigureClusters, Category=Layers]
// [Legal]
// Copyright 2023 Esri.

// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0

// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// [Legal]

#ifdef PCH_BUILD
#include "pch.hpp" // IWYU pragma: keep
#endif // PCH_BUILD

#include "ConfigureClusters.h"

#include "AggregateGeoElement.h"
#include "AggregateField.h"
#include "AggregateFieldListModel.h"
#include "AttributeListModel.h"
#include "ClassBreaksRenderer.h"
#include "ClusteringFeatureReduction.h"
#include "Error.h"
#include "FeatureLayer.h"
#include "GeoElement.h"
#include "IdentifyLayerResult.h"
#include "LabelDefinition.h"
#include "LabelDefinitionListModel.h"
#include "LayerListModel.h"
#include "Map.h"
#include "MapQuickView.h"
#include "Popup.h"
#include "PopupDefinition.h"
#include "PortalItem.h"
#include "ReductionTypes.h"
#include "ServiceTypes.h"
#include "SimpleLabelExpression.h"
#include "SimpleMarkerSymbol.h"
#include "SymbolTypes.h"
#include "TextSymbol.h"
#include "Viewpoint.h"

#include <QColor>
#include <QFuture>

using namespace Esri::ArcGISRuntime;

ConfigureClusters::ConfigureClusters(QObject* parent /* = nullptr */):
  QObject(parent)
{
  // Create a map from a web map PortalItem.
  m_map = new Map(new PortalItem("aa44e79a4836413c89908e1afdace2ea", this), this);

  // Get the Zurich buildings feature layer once the map has finished loading.
  connect(m_map, &Map::doneLoading, this, [this](const Error& error)
  {
    if (!error.isEmpty())
    {
      qDebug() << "Map loading error:" << error.message() << error.additionalMessage();
      return;
    }

    const LayerListModel* operationalLayers = m_map->operationalLayers();
    if (operationalLayers->isEmpty())
      return;

    m_layer = qobject_cast<FeatureLayer*>(operationalLayers->first());
  });
}

ConfigureClusters::~ConfigureClusters() = default;

void ConfigureClusters::init()
{
  // Register the map view for QML
  qmlRegisterType<MapQuickView>("Esri.Samples", 1, 0, "MapView");
  qmlRegisterType<ConfigureClusters>("Esri.Samples", 1, 0, "ConfigureClustersSample");
}

MapQuickView* ConfigureClusters::mapView() const
{
  return m_mapView;
}

// Set the view (created in QML)
void ConfigureClusters::setMapView(MapQuickView* mapView)
{
  if (!mapView || mapView == m_mapView)
    return;

  m_mapView = mapView;
  m_mapView->setMap(m_map);
  connect(m_mapView, &MapQuickView::mapScaleChanged, this, &ConfigureClusters::mapScaleChanged);
  connect(m_mapView, &MapQuickView::mouseClicked, this, &ConfigureClusters::mouseClicked);

  // Set the initial viewpoint to Zurich, Switzerland.
  m_mapView->setViewpointAsync(Viewpoint(47.38, 8.53, 8e4));

  emit mapViewChanged();
}

void ConfigureClusters::setClusterRadius(double clusterRadius)
{
  if (!m_clusteringFeatureReduction)
    return;

  m_clusteringFeatureReduction->setRadius(clusterRadius);
}

void ConfigureClusters::setMaxScale(double maxScale)
{
  if (!m_clusteringFeatureReduction)
    return;

  m_clusteringFeatureReduction->setMaxScale(maxScale);
}

double ConfigureClusters::mapScale() const
{
  if (!m_mapView)
    return 0.0;

  return m_mapView->mapScale();
}

void ConfigureClusters::createCustomFeatureReduction()
{
  // Add a class break for each intended value range and define a symbol to display for features in that range.
  // In this case, the average building height ranges from 0 to 8 stories.
  // For each cluster of features with a given average building height, a symbol is defined with a specified color.
  const QList<ClassBreak*> classBreaks =
  {
    new ClassBreak("0", "0", 0.0, 1.0, new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, QColor(4, 251, 255), 8.0, this), this),
    new ClassBreak("1", "1", 1.0, 2.0, new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, QColor(44, 211, 255), 8.0, this), this),
    new ClassBreak("2", "2", 2.0, 3.0, new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, QColor(74, 181, 255), 8.0, this), this),
    new ClassBreak("3", "3", 3.0, 4.0, new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, QColor(120, 135, 255), 8.0, this), this),
    new ClassBreak("4", "4", 4.0, 5.0, new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, QColor(165, 90, 255), 8.0, this), this),
    new ClassBreak("5", "5", 5.0, 6.0, new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, QColor(194, 61, 255), 8.0, this), this),
    new ClassBreak("6", "6", 6.0, 7.0, new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, QColor(224, 31, 255), 8.0, this), this),
    new ClassBreak("7", "7", 7.0, 8.0, new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, QColor(254, 1, 255), 8.0, this), this)
  };

  // Create a class breaks renderer to apply to the custom feature reduction.
  // Define the field to use for the class breaks renderer.
  // Note that this field name must match the name of an aggregate field contained in the clustering feature reduction's aggregate fields property.
  ClassBreaksRenderer* classBreaksRenderer = new ClassBreaksRenderer("Average Building Height", classBreaks, this);

  // Define a default symbol to use for features that do not fall within any of the ranges defined by the class breaks.
  classBreaksRenderer->setDefaultSymbol(new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, QColorConstants::Svg::pink, 8, this));

  // Create a new clustering feature reduction using the class breaks renderer.
  m_clusteringFeatureReduction = new ClusteringFeatureReduction(classBreaksRenderer, this);

  // Set the feature reduction's aggregate fields. Note that the field names must match the names of fields in the feature layer's dataset.
  // The aggregate fields summarize values based on the defined aggregate statistic type.
  m_clusteringFeatureReduction->aggregateFields()->append(
      new AggregateField("Total Residential Buildings", "Residential_Buildings", AggregateStatisticType::Sum, this));

  m_clusteringFeatureReduction->aggregateFields()->append(
      new AggregateField("Average Building Height", "Most_common_number_of_storeys", AggregateStatisticType::Mode, this));

  // Enable the feature reduction.
  m_clusteringFeatureReduction->setEnabled(true);

  // Set the popup definition for the custom feature reduction.
  m_clusteringFeatureReduction->setPopupDefinition(new PopupDefinition(m_clusteringFeatureReduction, this));

  // Set values for the feature reduction's cluster minimum and maximum symbol sizes.
  // Note that the default values for Max and Min symbol size are 70 and 12 respectively.
  m_clusteringFeatureReduction->setMinSymbolSize(5.0);
  m_clusteringFeatureReduction->setMaxSymbolSize(90.0);

  // Set the feature reduction for the layer.
  m_layer->setFeatureReduction(m_clusteringFeatureReduction);

  // Set initial slider values.
  // Note that the default value for cluster radius is 60.
  // Increasing the cluster radius increases the number of features that are grouped together into a cluster.
  m_clusteringFeatureReduction->setRadius(60.0);

  // Note that the default value for max scale is 0.
  // The max scale value is the maximum scale at which clustering is applied.
  m_clusteringFeatureReduction->setMaxScale(0.0);
}

void ConfigureClusters::drawClusters()
{
  // If the layer is not yet loaded, do nothing.
  if (!m_layer)
    return;

  // Create a new clustering feature reduction.
  createCustomFeatureReduction();
}

void ConfigureClusters::displayLabels(bool checked)
{
  if (!m_clusteringFeatureReduction)
    return;

  if (checked)
  {
    // Create a label definition with a simple label expression.
    SimpleLabelExpression* simpleLabelExpression = new SimpleLabelExpression("[cluster_count]", this);
    TextSymbol* textSymbol = new TextSymbol("", QColorConstants::Svg::black, 15.0, HorizontalAlignment::Center, VerticalAlignment::Middle, this);
    textSymbol->setFontWeight(FontWeight::Bold);
    LabelDefinition* labelDefinition = new LabelDefinition(simpleLabelExpression, textSymbol, this);
    labelDefinition->setPlacement(LabelingPlacement::PointCenterCenter);

    // Add the label definition to the feature reduction.
    m_clusteringFeatureReduction->labelDefinitions()->append(labelDefinition);
  }
  else
  {
    m_clusteringFeatureReduction->labelDefinitions()->clear();
  }
}

void ConfigureClusters::mouseClicked(QMouseEvent& mouseEvent)
{
  if (!m_layer)
    return;

  // clear the list of popup content
  m_popupContent.clear();

  // clear cluster selection
  if (m_aggregateGeoElement)
    m_aggregateGeoElement->setSelected(false);

  // Clean up any children objects associated with this parent
  m_resultParent.reset(new QObject(this));
  m_aggregateGeoElement = nullptr;

  // Identify the tapped observation.
  m_mapView->identifyLayerAsync(m_layer, mouseEvent.position(), 3.0, true, m_resultParent.get()).then(this, [this](IdentifyLayerResult* result)
  {
    // clear cluster selection
    if (m_aggregateGeoElement)
      m_aggregateGeoElement->setSelected(false);

    for (Popup* popup: result->popups())
    {
      // if the identified object is a cluster, select it
      m_aggregateGeoElement = dynamic_cast<AggregateGeoElement*>(popup->geoElement());
      if (m_aggregateGeoElement)
        m_aggregateGeoElement->setSelected(true);

      const auto attributes = popup->geoElement()->attributes();
      for (const QString& name: attributes->attributeNames())
      {
        m_popupContent += name + ": " + attributes->attributeValue(name).toString() + "\n";
      }
    }

    // notify QML that popup content has changed and to display the popup(s).
    emit popupContentChanged();
  });
}

QString ConfigureClusters::popupContent() const
{
  return m_popupContent;
}

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.