Introduce clusterProperties option for aggregated cluster properties

debug/cluster.html

@@ -20,7 +20,7 @@
 
 var map = window.map = new mapboxgl.Map({
     container: 'map',
-    zoom: 0,
+    zoom: 1,
     center: [0, 0],
     style: 'mapbox://styles/mapbox/cjf4m44iw0uza2spb3q0a7s41',
     hash: true
@@ -31,15 +31,20 @@
         "type": "geojson",
         "data": "/test/integration/data/places.geojson",
         "cluster": true,
-        "clusterRadius": 50
+        "clusterRadius": 50,
+        "clusterProperties": {
+            "max": ["max", 0, ["get", "scalerank"]],
+            "sum": ["+", 0, ["get", "scalerank"]],
+            "has_island": ["any", false, ["==", ["get", "featureclass"], "island"]]
+        }
     });
     map.addLayer({
         "id": "cluster",
         "type": "circle",
         "source": "geojson",
         "filter": ["==", "cluster", true],
         "paint": {
-            "circle-color": "rgba(0, 200, 0, 1)",
+            "circle-color": ["case", ["get", "has_island"], "orange", "rgba(0, 200, 0, 1)"],
             "circle-radius": 20
         }
     });
@@ -49,7 +54,7 @@
         "source": "geojson",
         "filter": ["==", "cluster", true],
         "layout": {
-            "text-field": "{point_count}",
+            "text-field": "{point_count} ({max})",
             "text-font": ["Open Sans Semibold", "Arial Unicode MS Bold"],
             "text-size": 12,
             "text-allow-overlap": true,

docs/components/expression-metadata.js

@@ -199,6 +199,7 @@ for (const name in CompoundExpression.definitions) {
 }
 
 delete types['error'];
+delete types['accumulated']; // skip documenting `accumulated` since it is internal use only
 
 export const expressions = {};
 export const expressionGroups = {};

src/source/geojson_source.js

@@ -139,7 +139,8 @@ class GeoJSONSource extends Evented implements Source {
                 extent: EXTENT,
                 radius: (options.clusterRadius || 50) * scale,
                 log: false
-            }
+            },
+            clusterProperties: options.clusterProperties
         }, options.workerOptions);
     }
 

src/source/geojson_worker_source.js

@@ -10,6 +10,8 @@ import Supercluster from 'supercluster';
 import geojsonvt from 'geojson-vt';
 import assert from 'assert';
 import VectorTileWorkerSource from './vector_tile_worker_source';
+import { createExpression } from '../style-spec/expression';
+import { isGlobalPropertyConstant, isFeatureConstant } from '../style-spec/expression/is_constant';
 
 import type {
     WorkerTileParameters,
@@ -30,7 +32,8 @@ export type LoadGeoJSONParameters = {
     source: string,
     cluster: boolean,
     superclusterOptions?: Object,
-    geojsonVtOptions?: Object
+    geojsonVtOptions?: Object,
+    clusterProperties?: Object
 };
 
 export type LoadGeoJSON = (params: LoadGeoJSONParameters, callback: ResponseCallback<Object>) => void;
@@ -171,7 +174,7 @@ class GeoJSONWorkerSource extends VectorTileWorkerSource {
 
                 try {
                     this._geoJSONIndex = params.cluster ?
-                        new Supercluster(params.superclusterOptions).load(data.features) :
+                        new Supercluster(getSuperclusterOptions(params)).load(data.features) :
                         geojsonvt(data, params.geojsonVtOptions);
                 } catch (err) {
                     return callback(err);
@@ -293,4 +296,70 @@ class GeoJSONWorkerSource extends VectorTileWorkerSource {
     }
 }
 
+function getSuperclusterOptions({superclusterOptions, clusterProperties}) {
+    if (!clusterProperties || !superclusterOptions) return superclusterOptions;
+
+    const initialValues = {};
+    const mapExpressions = {};
+    const reduceExpressions = {};
+    const globals = {accumulated: null, zoom: 0};
+    const feature = {properties: null};
+    const propertyNames = Object.keys(clusterProperties);
+
+    for (const key of propertyNames) {
+        const [operator, initialExpression, mapExpression] = clusterProperties[key];
+
+        const parsed = createExpression(clusterProperties[key]);
+        if (parsed.result === 'error') {
+            const message = parsed.value.map(e => e.message).join('; ');
+            throw new Error(`Error parsing expression for cluster property "${key}": ${message}`);
+
+        } else if (!isGlobalPropertyConstant(parsed.value.expression, ['zoom'])) {
+            throw new Error(`Error parsing expression for cluster property "${key}": zoom expressions not supported.`);
+        }
+
+        const initialExpressionParsed = createExpression(initialExpression);
+        const mapExpressionParsed = createExpression(mapExpression);
+        const reduceExpressionParsed = createExpression([operator, ['accumulated'], ['get', key]]);
+
+        if (initialExpressionParsed.result === 'success') {
+            if (!isFeatureConstant(initialExpressionParsed.value.expression))
+                throw new Error(`Error parsing expression for cluster property "${key}": can't use feature properties in initial expression.`);
+
+            initialValues[key] = initialExpressionParsed.value.evaluate(globals);
+        }
+
+        if (mapExpressionParsed.result === 'success')
+            mapExpressions[key] = mapExpressionParsed.value;
+
+        if (reduceExpressionParsed.result === 'success')
+            reduceExpressions[key] = reduceExpressionParsed.value;
+    }
+
+    superclusterOptions.initial = () => {
+        const properties = {};
+        for (const key of propertyNames) {
+            properties[key] = initialValues[key];
+        }
+        return properties;
+    };
+    superclusterOptions.map = (pointProperties) => {
+        feature.properties = pointProperties;
+        const properties = {};
+        for (const key of propertyNames) {
+            properties[key] = mapExpressions[key].evaluate(globals, feature);
+        }
+        return properties;
+    };
+    superclusterOptions.reduce = (accumulated, clusterProperties) => {
+        feature.properties = clusterProperties;
+        for (const key of propertyNames) {
+            globals.accumulated = accumulated[key];
+            accumulated[key] = reduceExpressions[key].evaluate(globals, feature);
+        }
+    };
+
+    return superclusterOptions;
+}
+
 export default GeoJSONWorkerSource;

src/style-spec/expression/definitions/index.js

@@ -201,6 +201,11 @@ CompoundExpression.register(expressions, {
         [],
         (ctx) => ctx.globals.lineProgress || 0
     ],
+    'accumulated': [
+        ValueType,
+        [],
+        (ctx) => ctx.globals.accumulated === undefined ? null : ctx.globals.accumulated
+    ],
     '+': [
         NumberType,
         varargs(NumberType),

src/style-spec/expression/index.js

@@ -38,7 +38,8 @@ export type GlobalProperties = $ReadOnly<{
     zoom: number,
     heatmapDensity?: number,
     lineProgress?: number,
-    isSupportedScript?: (string) => boolean
+    isSupportedScript?: (string) => boolean,
+    accumulated?: Value
 }>;
 
 export class StyleExpression {
@@ -49,12 +50,12 @@ export class StyleExpression {
     _warningHistory: {[key: string]: boolean};
     _enumValues: ?{[string]: any};
 
-    constructor(expression: Expression, propertySpec: StylePropertySpecification) {
+    constructor(expression: Expression, propertySpec: ?StylePropertySpecification) {
         this.expression = expression;
         this._warningHistory = {};
         this._evaluator = new EvaluationContext();
-        this._defaultValue = getDefaultValue(propertySpec);
-        this._enumValues = propertySpec.type === 'enum' ? propertySpec.values : null;
+        this._defaultValue = propertySpec ? getDefaultValue(propertySpec) : null;
+        this._enumValues = propertySpec && propertySpec.type === 'enum' ? propertySpec.values : null;
     }
 
     evaluateWithoutErrorHandling(globals: GlobalProperties, feature?: Feature, featureState?: FeatureState): any {
@@ -105,12 +106,12 @@ export function isExpression(expression: mixed) {
  *
  * @private
  */
-export function createExpression(expression: mixed, propertySpec: StylePropertySpecification): Result<StyleExpression, Array<ParsingError>> {
-    const parser = new ParsingContext(definitions, [], getExpectedType(propertySpec));
+export function createExpression(expression: mixed, propertySpec: ?StylePropertySpecification): Result<StyleExpression, Array<ParsingError>> {
+    const parser = new ParsingContext(definitions, [], propertySpec ? getExpectedType(propertySpec) : undefined);
 
     // For string-valued properties, coerce to string at the top level rather than asserting.
     const parsed = parser.parse(expression, undefined, undefined, undefined,
-        propertySpec.type === 'string' ? {typeAnnotation: 'coerce'} : undefined);
+        propertySpec && propertySpec.type === 'string' ? {typeAnnotation: 'coerce'} : undefined);
 
     if (!parsed) {
         assert(parser.errors.length > 0);

src/style-spec/expression/parsing_context.js

@@ -226,5 +226,5 @@ function isConstant(expression: Expression) {
     }
 
     return isFeatureConstant(expression) &&
-        isGlobalPropertyConstant(expression, ['zoom', 'heatmap-density', 'line-progress', 'is-supported-script']);
+        isGlobalPropertyConstant(expression, ['zoom', 'heatmap-density', 'line-progress', 'accumulated', 'is-supported-script']);
 }

src/style-spec/reference/v8.json

@@ -373,6 +373,10 @@
       "type": "number",
       "doc": "Max zoom on which to cluster points if clustering is enabled. Defaults to one zoom less than maxzoom (so that last zoom features are not clustered)."
     },
+    "clusterProperties": {
+      "type": "*",
+      "doc": "An object defining custom properties on the generated clusters if clustering is enabled, aggregating values from clustered points. Has the form `{\"property_name\": [operator, initial_expression, map_expression]}`. `operator` is any expression function that accepts at least 2 operands (e.g. `\"+\"` or `\"max\"`) — it accumulates the property value from clusters/points the cluster contains; `initial_expression` evaluates the initial value of the property before accummulating other points/clusters; `map_expression` produces the value of a single point.\n\nExample: `{\"sum\": [\"+\", 0, [\"get\", \"scalerank\"]]}`."
+    },
     "lineMetrics": {
       "type": "boolean",
       "default": false,

src/style-spec/types.js

@@ -121,6 +121,7 @@ export type GeoJSONSourceSpecification = {|
     "cluster"?: boolean,
     "clusterRadius"?: number,
     "clusterMaxZoom"?: number,
+    "clusterProperties"?: mixed,
     "lineMetrics"?: boolean,
     "generateId"?: boolean
 |}

test/integration/render-tests/geojson/clustered-properties/style.json

@@ -0,0 +1,78 @@
+{
+  "version": 8,
+  "metadata": {
+    "test": {
+      "width": 256,
+      "height": 128
+    }
+  },
+  "center": [
+    -10,
+    -5
+  ],
+  "zoom": 0,
+  "sources": {
+    "geojson": {
+      "type": "geojson",
+      "data": "local://data/places.geojson",
+      "cluster": true,
+      "clusterRadius": 50,
+      "clusterProperties": {
+        "max": ["max", 0, ["get", "scalerank"]],
+        "sum": ["+", 0, ["get", "scalerank"]],
+        "has_island": ["any", false, ["==", ["get", "featureclass"], "island"]]
+      }
+    }
+  },
+  "glyphs": "local://glyphs/{fontstack}/{range}.pbf",
+  "layers": [
+    {
+      "id": "cluster",
+      "type": "circle",
+      "source": "geojson",
+      "filter": [
+        "==",
+        "cluster",
+        true
+      ],
+      "paint": {
+        "circle-color": ["case", ["get", "has_island"], "orange", "rgba(0, 200, 0, 1)"],
+        "circle-radius": 20
+      }
+    },
+    {
+      "id": "cluster_label",
+      "type": "symbol",
+      "source": "geojson",
+      "filter": [
+        "==",
+        "cluster",
+        true
+      ],
+      "layout": {
+        "text-field": "{sum},{max}",
+        "text-font": [
+          "Open Sans Semibold",
+          "Arial Unicode MS Bold"
+        ],
+        "text-size": 12,
+        "text-allow-overlap": true,
+        "text-ignore-placement": true
+      }
+    },
+    {
+      "id": "unclustered_point",
+      "type": "circle",
+      "source": "geojson",
+      "filter": [
+        "!=",
+        "cluster",
+        true
+      ],
+      "paint": {
+        "circle-color": "rgba(0, 0, 200, 1)",
+        "circle-radius": 10
+      }
+    }
+  ]
+}

test/unit/style-spec/expression.test.js

@@ -7,7 +7,7 @@ import {expressions as definitionMetadata} from '../../../docs/components/expres
 // filter out interal "error" and "filter-*" expressions from definition list
 const filterExpressionRegex = /filter-/;
 const definitionList = Object.keys(definitions).filter((expression) => {
-    return expression !== 'error' && !filterExpressionRegex.exec(expression);
+    return expression !== 'error' && expression !== 'accumulated' && !filterExpressionRegex.exec(expression);
 }).sort();
 
 test('v8.json includes all definitions from style-spec', (t) => {