queryRenderFeatures continued [not ready]

CHANGELOG.md

@@ -1,5 +1,14 @@
 ## master
 
+#### Breaking Changes
+
+- `map.featuresAt` and `map.featuresIn` are removed. Use `map.queryRenderedFeatures` or `map.querySourceFeatures` instead. To migrate:
+    - replace `featuresAt` and `featuresIn` with `queryRenderedFeatures`
+    - `queryRenderedFeatures` is synchronous. Remove the callback and use the return value.
+    - rename the `layer` parameters to `layers` and make it an array of strings.
+    - remove the `radius` parameter. `radius` was often used with `featuresAt` to account for style properties like `line-width` and `circle-radius`. `queryRenderedFeatures` automatically accounts for these style properties. If you need to query a larger area, make the first argument a box instead of a point.
+    - remove the `includeGeometry` parameter. `queryRenderedFeatures` always includes geometries.
+
 #### New Features & Improvements
 
 Improve overall rendering performance. (#2221)
@@ -8,6 +17,9 @@ Add `Map#setMaxBounds` method (#2234)
 Add `isActive` and `isEnabled` methods to interaction handlers (#2238)
 Add `Map#setZoomBounds` method (#2243)
 Add touch events (#2195)
+- `map.queryRenderedFeatures` can be used to query the styled and rendered representations of features
+- `map.querySourceFeatures` can be used to get features directly from vector tiles, independent of the style.
+- interaction for labels (#303) and style-property-aware hit testing (#316) are possible with `map.queryRenderedFeatures`
 
 #### Bugfixes
 

bench/buffer_benchmark.js

@@ -163,7 +163,7 @@ function runSample(stylesheet, getGlyphs, getIcons, getTile, callback) {
         getTile(url, function(err, response) {
             if (err) throw err;
             var data = new VT.VectorTile(new Protobuf(new Uint8Array(response)));
-            workerTile.parse(data, layers, actor, function(err) {
+            workerTile.parse(data, layers, actor, null, function(err) {
                 if (err) return callback(err);
                 eachCallback();
             });

bench/index.js

@@ -15,7 +15,9 @@ function main() {
 
     var benchmarks = {
         buffer: require('./buffer_benchmark'),
-        fps: require('./fps_benchmark')
+        fps: require('./fps_benchmark'),
+        'query-point': require('./query_point_benchmark'),
+        'query-box': require('./query_box_benchmark')
     };
 
     var pathnameArray = location.pathname.split('/');

bench/query_box_benchmark.js

@@ -0,0 +1,83 @@
+'use strict';
+
+var Evented = require('../js/util/evented');
+var util = require('../js/util/util');
+
+var width = 1024;
+var height = 768;
+
+var numSamples = 10;
+
+var zoomLevels = [];
+for (var i = 4; i < 19; i++) {
+    zoomLevels.push(i);
+}
+
+module.exports = function(options) {
+    var evented = util.extend({}, Evented);
+
+    var sum = 0;
+    var count = 0;
+
+    asyncSeries(zoomLevels.length, function(n, callback) {
+        var zoomLevel = zoomLevels[zoomLevels.length - n];
+        var map = options.createMap({
+            width: width,
+            height: height,
+            zoom: zoomLevel,
+            center: [-77.032194, 38.912753],
+            style: 'mapbox://styles/mapbox/streets-v8'
+        });
+        document.getElementById('map').style.display = 'none';
+
+        map.on('load', function() {
+
+            var zoomSum = 0;
+            var zoomCount = 0;
+            asyncSeries(numSamples, function(n, callback) {
+                var start = performance.now();
+                map.queryRenderedFeatures();
+                var duration = performance.now() - start;
+                sum += duration;
+                count++;
+                zoomSum += duration;
+                zoomCount++;
+                callback();
+            }, function() {
+                evented.fire('log', {
+                    message: 'zoom ' + zoomLevel + ' average: ' + (zoomSum / zoomCount).toFixed(2) + ' ms'
+                });
+                callback();
+            });
+        });
+    }, done);
+
+
+    function done() {
+        var average = sum / count;
+        evented.fire('end', {
+            message: (average).toFixed(2) + ' ms',
+            score: average
+        });
+    }
+    setTimeout(function() {
+        evented.fire('log', {
+            message: 'loading assets',
+            color: 'dark'
+        });
+    }, 0);
+
+    return evented;
+};
+
+function asyncSeries(times, work, callback) {
+    if (times > 0) {
+        work(times, function(err) {
+            if (err) callback(err);
+            else asyncSeries(times - 1, work, callback);
+        });
+    } else {
+        callback();
+    }
+}
+

bench/query_point_benchmark.js

@@ -0,0 +1,93 @@
+'use strict';
+
+var Evented = require('../js/util/evented');
+var util = require('../js/util/util');
+
+var width = 1024;
+var height = 768;
+
+var zoomLevels = [];
+for (var i = 4; i < 19; i++) {
+    zoomLevels.push(i);
+}
+
+var queryPoints = [];
+var d = 20;
+for (var x = 0; x < d; x++) {
+    for (var y = 0; y < d; y++) {
+        queryPoints.push([
+            (x / d) * width,
+            (y / d) * height
+        ]);
+    }
+}
+
+module.exports = function(options) {
+    var evented = util.extend({}, Evented);
+
+    var sum = 0;
+    var count = 0;
+
+    asyncSeries(zoomLevels.length, function(n, callback) {
+        var zoomLevel = zoomLevels[zoomLevels.length - n];
+        var map = options.createMap({
+            width: width,
+            height: height,
+            zoom: zoomLevel,
+            center: [-77.032194, 38.912753],
+            style: 'mapbox://styles/mapbox/streets-v8'
+        });
+        document.getElementById('map').style.display = 'none';
+
+        map.on('load', function() {
+
+            var zoomSum = 0;
+            var zoomCount = 0;
+            asyncSeries(queryPoints.length, function(n, callback) {
+                var queryPoint = queryPoints[queryPoints.length - n];
+                var start = performance.now();
+                map.queryRenderedFeatures(queryPoint);
+                var duration = performance.now() - start;
+                sum += duration;
+                count++;
+                zoomSum += duration;
+                zoomCount++;
+                callback();
+            }, function() {
+                evented.fire('log', {
+                    message: 'zoom ' + zoomLevel + ' average: ' + (zoomSum / zoomCount).toFixed(2) + ' ms'
+                });
+                callback();
+            });
+        });
+    }, done);
+
+
+    function done() {
+        var average = sum / count;
+        evented.fire('end', {
+            message: (average).toFixed(2) + ' ms',
+            score: average
+        });
+    }
+    setTimeout(function() {
+        evented.fire('log', {
+            message: 'loading assets',
+            color: 'dark'
+        });
+    }, 0);
+
+    return evented;
+};
+
+function asyncSeries(times, work, callback) {
+    if (times > 0) {
+        work(times, function(err) {
+            if (err) callback(err);
+            else asyncSeries(times - 1, work, callback);
+        });
+    } else {
+        callback();
+    }
+}
+

docs/_posts/examples/3400-01-04-center-on-symbol.html

@@ -2,7 +2,7 @@
 layout: example
 category: example
 title: Center the map on a clicked marker
-description: Using featuresAt and flyTo to center the map on a symbol
+description: Using queryRenderedFeatures and flyTo to center the map on a symbol
 ---
 <div id='map'></div>
 <script>
@@ -73,26 +73,22 @@
 });
 
 map.on('click', function (e) {
-    // Use featuresAt to get features within a given radius of the click event
+    // Use queryRenderedFeatures to get features at a click event's point
     // Use layer option to avoid getting results from other layers
-    map.featuresAt(e.point, {layer: 'symbols', radius: 10, includeGeometry: true}, function (err, features) {
-        if (err) throw err;
-        // if there are features within the given radius of the click event,
-        // fly to the location of the click event
-        if (features.length) {
-            // Get coordinates from the symbol and center the map on those coordinates
-            map.flyTo({center: features[0].geometry.coordinates});
-        }
-    });
+    var features = map.queryRenderedFeatures(e.point, { layers: ['symbols'] });
+    // if there are features within the given radius of the click event,
+    // fly to the location of the click event
+    if (features.length) {
+        // Get coordinates from the symbol and center the map on those coordinates
+        map.flyTo({center: features[0].geometry.coordinates});
+    }
 });
 
 
 // Use the same approach as above to indicate that the symbols are clickable
 // by changing the cursor style to 'pointer'.
 map.on('mousemove', function (e) {
-    map.featuresAt(e.point, {layer: 'symbols', radius: 10}, function (err, features) {
-        if (err) throw err;
-        map.getCanvas().style.cursor = features.length ? 'pointer' : '';
-    });
+    var features = map.queryRenderedFeatures(e.point, { layers: ['symbols'] });
+    map.getCanvas().style.cursor = features.length ? 'pointer' : '';
 });
 </script>

docs/_posts/examples/3400-01-04-hover-styles.html

@@ -2,7 +2,7 @@
 layout: example
 category: example
 title: Highlight features under the mouse pointer
-description: Using featuresAt and a filter to change hover styles
+description: Using queryRenderedFeatures and a filter to change hover styles
 ---
 <div id='map'></div>
 <script>
@@ -59,16 +59,12 @@
     // If a feature is found, then we'll update the filter in the route-hover
     // layer to only show that state, thus making a hover effect.
     map.on("mousemove", function(e) {
-        map.featuresAt(e.point, {
-            radius: 5,
-            layer: ["state-fills"]
-        }, function (err, features) {
-            if (!err && features.length) {
-                map.setFilter("route-hover", ["==", "name", features[0].properties.name]);
-            } else {
-                map.setFilter("route-hover", ["==", "name", ""]);
-            }
-        });
+        var features = map.queryRenderedFeatures(e.point, { layers: ["state-fills"] });
+        if (features.length) {
+            map.setFilter("route-hover", ["==", "name", features[0].properties.name]);
+        } else {
+            map.setFilter("route-hover", ["==", "name", ""]);
+        }
     });
 });
 </script>

docs/_posts/examples/3400-01-05-featuresat.html → docs/_posts/examples/3400-01-05-queryrenderedfeatures.html

@@ -2,7 +2,7 @@
 layout: example
 category: example
 title: Get features under the mouse pointer
-description: Using the featuresAt API to show properties of hovered-over map elements.
+description: Using the queryRenderedFeatures API to show properties of hovered-over map elements.
 ---
 <style>
     #features {
@@ -34,10 +34,8 @@
     });
 
     map.on('mousemove', function (e) {
-        map.featuresAt(e.point, {radius: 5}, function (err, features) {
-            if (err) throw err;
-            document.getElementById('features').innerHTML = JSON.stringify(features, null, 2);
-        });
+        var features = map.queryRenderedFeatures(e.point);
+        document.getElementById('features').innerHTML = JSON.stringify(features, null, 2);
     });
 });
 </script>

docs/_posts/examples/3400-01-06-polygon-popup-on-click.html

@@ -43,38 +43,27 @@
     });
 });
 
-var popup = new mapboxgl.Popup();
 
 // When a click event occurs near a marker icon, open a popup at the location of
 // the feature, with description HTML from its properties.
 map.on('click', function (e) {
-    map.featuresAt(e.point, {
-        radius: 1,
-        includeGeometry: true,
-        layer: 'states-layer'
-    }, function (err, features) {
+    var features = map.queryRenderedFeatures(e.point, { layers: ['states-layer'] });
+    if (!features.length) {
+        return;
+    }
 
-        if (err || !features.length) {
-            popup.remove();
-            return;
-        }
-
-        var feature = features[0];
+    var feature = features[0];
 
-        popup.setLngLat(map.unproject(e.point))
-            .setHTML(feature.properties.name)
-            .addTo(map);
-    });
+    var popup = new mapboxgl.Popup()
+        .setLngLat(map.unproject(e.point))
+        .setHTML(feature.properties.name)
+        .addTo(map);
 });
 
 // Use the same approach as above to indicate that the symbols are clickable
 // by changing the cursor style to 'pointer'.
 map.on('mousemove', function (e) {
-    map.featuresAt(e.point, {
-        radius: 1,
-        layer: 'states-layer'
-    }, function (err, features) {
-        map.getCanvas().style.cursor = (!err && features.length) ? 'pointer' : '';
-    });
+    var features = map.queryRenderedFeatures(e.point, { layers: ['states-layer'] });
+    map.getCanvas().style.cursor = (features.length) ? 'pointer' : '';
 });
 </script>