Add heatmaps docs and examples

README.md

@@ -12,6 +12,8 @@ Globe.GL
    <a href="//vasturiano.github.io/globe.gl/example/submarine-cables/"><img width="48%" src="https://vasturiano.github.io/globe.gl/example/submarine-cables/preview.png"></a>
    <a href="//vasturiano.github.io/globe.gl/example/hexed-polygons/"><img width="48%" src="https://vasturiano.github.io/globe.gl/example/hexed-polygons/preview.png"></a>
    <a href="//vasturiano.github.io/globe.gl/example/world-cities/"><img width="48%" src="https://vasturiano.github.io/globe.gl/example/world-cities/preview.png"></a>
+   <a href="//vasturiano.github.io/globe.gl/example/population-heatmap/"><img width="48%" src="https://vasturiano.github.io/globe.gl/example/population-heatmap/preview.png"></a>
+   <a href="//vasturiano.github.io/globe.gl/example/clouds/"><img width="48%" src="https://vasturiano.github.io/globe.gl/example/clouds/preview.png"></a>
    <a href="//vasturiano.github.io/globe.gl/example/satellites/"><img width="48%" src="https://vasturiano.github.io/globe.gl/example/satellites/preview.png"></a>
    <a href="//vasturiano.github.io/globe.gl/example/moon-landing-sites/"><img width="48%" src="https://vasturiano.github.io/globe.gl/example/moon-landing-sites/preview.png"></a>
 </p>
@@ -32,6 +34,7 @@ And check out the [React bindings](https://github.com/vasturiano/react-globe.gl)
 * [Elevated Polygons](https://vasturiano.github.io/globe.gl/example/countries-population/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/countries-population/index.html))
 * [Hollow Globe](https://vasturiano.github.io/globe.gl/example/hollow-globe/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/hollow-globe/index.html))
 * [Path Lines](https://vasturiano.github.io/globe.gl/example/random-paths/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/random-paths/index.html))
+* [Heatmap](https://vasturiano.github.io/globe.gl/example/heatmap/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/heatmap/index.html))
 * [Map Labels](https://vasturiano.github.io/globe.gl/example/world-cities/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/world-cities/index.html))
 * [HTML Markers](https://vasturiano.github.io/globe.gl/example/html-markers/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/html-markers/index.html))
 * [Hexed Country Polygons](https://vasturiano.github.io/globe.gl/example/hexed-polygons/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/hexed-polygons/index.html))
@@ -43,8 +46,10 @@ And check out the [React bindings](https://github.com/vasturiano/react-globe.gl)
 * [Custom Globe Styling](https://vasturiano.github.io/globe.gl/example/custom-globe-styling/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/custom-globe-styling/index.html))
 * [Custom Layer](https://vasturiano.github.io/globe.gl/example/custom-layer/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/custom-layer/index.html))
 * [World Population](https://vasturiano.github.io/globe.gl/example/world-population/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/world-population/index.html))
+* [Population Heatmap](https://vasturiano.github.io/globe.gl/example/population-heatmap/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/population-heatmap/index.html))
 * [Recent Earthquakes](https://vasturiano.github.io/globe.gl/example/earthquakes/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/earthquakes/index.html))
 * [World Volcanoes](https://vasturiano.github.io/globe.gl/example/volcanoes/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/volcanoes/index.html))
+* [Volcanoes Heatmap](https://vasturiano.github.io/globe.gl/example/volcanoes-heatmap/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/volcanoes-heatmap/index.html))
 * [US outbound international airline routes](https://vasturiano.github.io/globe.gl/example/airline-routes/us-international-outbound.html) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/airline-routes/us-international-outbound.html))
 * [Earth Shield](https://vasturiano.github.io/globe.gl/example/earth-shield/) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/earth-shield/index.html))
 * [Satellites](https://vasturiano.github.io/globe.gl/example/satellites/index.html) ([source](https://github.com/vasturiano/globe.gl/blob/master/example/satellites/index.html))
@@ -77,6 +82,7 @@ myGlobe(myDOMElement)
 * [Arcs Layer](#arcs-layer)
 * [Polygons Layer](#polygons-layer)
 * [Paths Layer](#paths-layer)
+* [Heatmaps Layer](#heatmaps-layer)
 * [Hex Bin Layer](#hex-bin-layer)
 * [Hexed Polygons Layer](#hexed-polygons-layer)
 * [Tiles Layer](#tiles-layer)
@@ -221,10 +227,33 @@ Globe({ configOptions })(<domElement>)
 | <b>pathDashInitialGap</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Path object accessor function, attribute or a numeric constant for the length of the initial gap before the first dash segment, in terms of relative line length. | 0 |
 | <b>pathDashAnimateTime</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Path object accessor function, attribute or a numeric constant for the time duration (in `ms`) to animate the motion of dash positions from the start to the end point for a full line length. A value of `0` disables the animation. | 0 |
 | <b>pathTransitionDuration</b>([<i>num</i>]) | Getter/setter for duration (ms) of the transition to animate path changes. A value of `0` will move the paths immediately to their final position. New paths are animated from start to end. | 1000 |
-| <b>onPathClick</b>(<i>fn</i>) | Callback function for path (left-button) clicks. The path object, the event object and the clicked coordinates are included as arguments: `onPathClick(arc, event, { lat, lng, altitude })`. | - |
-| <b>onPathRightClick</b>(<i>fn</i>) | Callback function for path right-clicks. The path object, the event object and the clicked coordinates are included as arguments: `onPathRightClick(arc, event, { lat, lng, altitude })`. | - |
+| <b>onPathClick</b>(<i>fn</i>) | Callback function for path (left-button) clicks. The path object, the event object and the clicked coordinates are included as arguments: `onPathClick(path, event, { lat, lng, altitude })`. | - |
+| <b>onPathRightClick</b>(<i>fn</i>) | Callback function for path right-clicks. The path object, the event object and the clicked coordinates are included as arguments: `onPathRightClick(path, event, { lat, lng, altitude })`. | - |
 | <b>onPathHover</b>(<i>fn</i>) | Callback function for path mouse over events. The path object (or `null` if there's no path under the mouse line of sight) is included as the first argument, and the previous path object (or `null`) as second argument: `onPathHover(path, prevPath)`. | - |
 
+### Heatmaps Layer
+
+<p align="center">
+   <a href="//vasturiano.github.io/globe.gl/example/heatmap/"><img width="70%" src="https://vasturiano.github.io/globe.gl/example/heatmap/preview.png"></a>
+</p>
+
+| Method | Description | Default |
+| --- | --- | :--: |
+| <b>heatmapsData</b>([<i>array</i>]) | Getter/setter for the list of heatmap datasets to represent in the heatmaps map layer. Each set of points is represented as an individual global heatmap with varying color and/or altitude, according to the point density. It uses a [Gaussian KDE](https://en.wikipedia.org/wiki/Kernel_density_estimation) to perform the density estimation, based on the great-arc distance between points. | `[]` |
+| <b>heatmapPoints</b>([<i>array</i>, <i>str</i> or <i>fn</i>]) | Heatmap object accessor function, attribute or an array for the set of points that define the heatmap. By default, each point is assumed to be a 2-position array (`[<lat>, <lon>]`). This default behavior can be modified using the `heatmapPointLat` and `heatmapPointLng` methods. | `pnts => pnts` |
+| <b>heatmapPointLat</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Heatmap point object accessor function, attribute or a numeric constant for the latitude coordinate. | `arr => arr[0]` |
+| <b>heatmapPointLng</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Heatmap point object accessor function, attribute or a numeric constant for the longitude coordinate. | `arr => arr[1]` |
+| <b>heatmapPointWeight</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Heatmap point object accessor function, attribute or a numeric constant for the weight of the point. The weight of a point determines its influence on the density of the surrounding area. | 1 |
+| <b>heatmapBandwidth</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Heatmap object accessor function, attribute or a numeric constant for the heatmap bandwidth, in angular degrees. The bandwidth is an internal parameter of the [Gaussian kernel function](https://en.wikipedia.org/wiki/Gaussian_function) and defines how localized is the influence of a point on distant locations. A narrow bandwidth leads to a more spiky representation, while a broad one has smoother curves. | 4 |
+| <b>heatmapColorFn</b>([<i>str</i> or <i>fn</i>]) | Heatmap object accessor function or attribute for the color interpolator function to represent density in the heatmap. This function should receive a number between `0` and `1` (or potentially higher if saturation > 1), and return a color string. | [Turbo colormap](https://blog.research.google/2019/08/turbo-improved-rainbow-colormap-for.html) interpolator with fading opacity |
+| <b>heatmapColorSaturation</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Heatmap object accessor function, attribute or a numeric constant for the color scale saturation. The saturation is a multiplier of the normalized density value (`[0,1]`) before passing it to the color interpolation function. It can be used to dampen outlier peaks in density and bring the data floor into view. | 1.5 |
+| <b>heatmapBaseAltitude</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Heatmap polygon object accessor function, attribute or a numeric constant for the heatmap base floor altitude in terms of globe radius units (`0` = 0 altitude, `1` = globe radius). | 0.01 |
+| <b>heatmapTopAltitude</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Heatmap polygon object accessor function, attribute or a numeric constant for the heatmap top peak altitude in terms of globe radius units (`0` = 0 altitude, `1` = globe radius). An equal value to the base altitude will yield a surface flat heatmap. If a top altitude is set, the variations in density will be used to define the altitude curves between base and top. | - |
+| <b>heatmapsTransitionDuration</b>([<i>num</i>]) | Getter/setter for duration (ms) of the transition to animate heatmap changes. A value of `0` will set the heatmap colors/altitudes immediately in their final position. New heatmaps are animated by rising them from the ground up and gently fading in through the color scale. | 0 |
+| <b>onHeatmapClick</b>(<i>fn</i>) | Callback function for heatmap (left-button) clicks. The heatmap object, the event object and the clicked coordinates are included as arguments: `onHeatmapClick(heatmap, event, { lat, lng, altitude })`. | - |
+| <b>onHeatmapRightClick</b>(<i>fn</i>) | Callback function for heatmap right-clicks. The heatmap object, the event object and the clicked coordinates are included as arguments: `onHeatmapRightClick(heatmap, event, { lat, lng, altitude })`. | - |
+| <b>onHeatmapHover</b>(<i>fn</i>) | Callback function for heatmap mouse over events. The heatmap object (or `null` if there's no heatmap under the mouse line of sight) is included as the first argument, and the previous heatmap object (or `null`) as second argument: `onHeatmapHover(heatmap, prevHeatmap)`. | - |
+
 ### Hex Bin Layer
 
 <p align="center">

example/heatmap/index.html

@@ -0,0 +1,31 @@
+<head>
+  <style> body { margin: 0; } </style>
+
+  <script src="//unpkg.com/globe.gl"></script>
+<!--  <script src="../../dist/globe.gl.js"></script>-->
+</head>
+
+<body>
+  <div id="globeViz"></div>
+
+  <script>
+    // Gen random data
+    const N = 300;
+    const gData = [...Array(N).keys()].map(() => ({
+      lat: (Math.random() - 0.5) * 160,
+      lng: (Math.random() - 0.5) * 360,
+      weight: Math.random()
+    }));
+
+    const world = Globe()
+      .globeImageUrl('//unpkg.com/three-globe/example/img/earth-dark.jpg')
+      .heatmapsData([gData])
+      .heatmapPointLat('lat')
+      .heatmapPointLng('lng')
+      .heatmapPointWeight('weight')
+      .heatmapTopAltitude(0.7)
+      .heatmapsTransitionDuration(3000)
+      .enablePointerInteraction(false)
+      (document.getElementById('globeViz'));
+  </script>
+</body>

example/population-heatmap/index.html

@@ -0,0 +1,28 @@
+<head>
+  <style> body { margin: 0; } </style>
+
+  <script src="//unpkg.com/d3-dsv"></script>
+
+  <script src="//unpkg.com/globe.gl"></script>
+<!--  <script src="../../dist/globe.gl.js"></script>-->
+</head>
+
+<body>
+  <div id="globeViz"></div>
+
+  <script>
+    const world = Globe()
+      .globeImageUrl('//unpkg.com/three-globe/example/img/earth-night.jpg')
+      .heatmapPointLat('lat')
+      .heatmapPointLng('lng')
+      .heatmapPointWeight('pop')
+      .heatmapBandwidth(0.9)
+      .heatmapColorSaturation(2.8)
+      .enablePointerInteraction(false)
+      (document.getElementById('globeViz'));
+
+    fetch('../datasets/world_population.csv').then(res => res.text())
+      .then(csv => d3.csvParse(csv, ({ lat, lng, pop }) => ({ lat: +lat, lng: +lng, pop: +pop })))
+      .then(data => world.heatmapsData([data]));
+  </script>
+</body>

example/volcanoes-heatmap/index.html

@@ -0,0 +1,27 @@
+<head>
+  <style> body { margin: 0; } </style>
+
+  <script src="//unpkg.com/globe.gl"></script>
+<!--  <script src="../../dist/globe.gl.js"></script>-->
+</head>
+
+<body>
+  <div id="globeViz"></div>
+
+  <script>
+    const world = Globe()
+      .globeImageUrl('//unpkg.com/three-globe/example/img/earth-blue-marble.jpg')
+      .heatmapPointLat('lat')
+      .heatmapPointLng('lon')
+      .heatmapPointWeight(d => d.elevation * 5e-5)
+      .heatmapTopAltitude(0.2)
+      .heatmapBandwidth(1.35)
+      .heatmapColorSaturation(3.2)
+      .enablePointerInteraction(false)
+      (document.getElementById('globeViz'));
+
+    fetch('../datasets/world_volcanoes.json').then(res => res.json()).then(volcanoes => {
+      world.heatmapsData([volcanoes])
+    });
+  </script>
+</body>