react-globe.gl 2.24.3 → 2.25.0

package/README.md

@@ -14,6 +14,8 @@ React bindings for the [globe.gl](https://github.com/vasturiano/globe.gl) UI com
    <a href="//vasturiano.github.io/react-globe.gl/example/submarine-cables/"><img width="48%" src="https://vasturiano.github.io/react-globe.gl/example/submarine-cables/preview.png"></a>
    <a href="//vasturiano.github.io/react-globe.gl/example/hexed-polygons/"><img width="48%" src="https://vasturiano.github.io/react-globe.gl/example/hexed-polygons/preview.png"></a>
    <a href="//vasturiano.github.io/react-globe.gl/example/world-cities/"><img width="48%" src="https://vasturiano.github.io/react-globe.gl/example/world-cities/preview.png"></a>
+   <a href="//vasturiano.github.io/react-globe.gl/example/population-heatmap/"><img width="48%" src="https://vasturiano.github.io/react-globe.gl/example/population-heatmap/preview.png"></a>
+   <a href="//vasturiano.github.io/react-globe.gl/example/clouds/"><img width="48%" src="https://vasturiano.github.io/react-globe.gl/example/clouds/preview.png"></a>
    <a href="//vasturiano.github.io/react-globe.gl/example/satellites/"><img width="48%" src="https://vasturiano.github.io/react-globe.gl/example/satellites/preview.png"></a>
    <a href="//vasturiano.github.io/react-globe.gl/example/moon-landing-sites/"><img width="48%" src="https://vasturiano.github.io/react-globe.gl/example/moon-landing-sites/preview.png"></a>
 </p>
@@ -28,6 +30,7 @@ A React component to represent data visualization layers on a 3-dimensional glob
 * [Elevated Polygons](https://vasturiano.github.io/react-globe.gl/example/countries-population/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/countries-population/index.html))
 * [Hollow Globe](https://vasturiano.github.io/react-globe.gl/example/hollow-globe/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/hollow-globe/index.html))
 * [Path Lines](https://vasturiano.github.io/react-globe.gl/example/random-paths/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/random-paths/index.html))
+* [Heatmap](https://vasturiano.github.io/react-globe.gl/example/heatmap/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/heatmap/index.html))
 * [Map Labels](https://vasturiano.github.io/react-globe.gl/example/world-cities/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/world-cities/index.html))
 * [HTML Markers](https://vasturiano.github.io/react-globe.gl/example/html-markers/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/html-markers/index.html))
 * [Hexed Country Polygons](https://vasturiano.github.io/react-globe.gl/example/hexed-polygons/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/hexed-polygons/index.html))
@@ -39,8 +42,10 @@ A React component to represent data visualization layers on a 3-dimensional glob
 * [Custom Globe Styling](https://vasturiano.github.io/react-globe.gl/example/custom-globe-styling/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/custom-globe-styling/index.html))
 * [Custom Layer](https://vasturiano.github.io/react-globe.gl/example/custom-layer/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/custom-layer/index.html))
 * [World Population](https://vasturiano.github.io/react-globe.gl/example/world-population/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/world-population/index.html))
+* [Population Heatmap](https://vasturiano.github.io/react-globe.gl/example/population-heatmap/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/population-heatmap/index.html))
 * [Recent Earthquakes](https://vasturiano.github.io/react-globe.gl/example/earthquakes/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/earthquakes/index.html))
 * [World Volcanoes](https://vasturiano.github.io/react-globe.gl/example/volcanoes/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/volcanoes/index.html))
+* [Volcanoes Heatmap](https://vasturiano.github.io/react-globe.gl/example/volcanoes-heatmap/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/volcanoes-heatmap/index.html))
 * [US outbound international airline routes](https://vasturiano.github.io/react-globe.gl/example/airline-routes/us-international-outbound.html) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/airline-routes/us-international-outbound.html))
 * [Earth Shield](https://vasturiano.github.io/react-globe.gl/example/earth-shield/) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/earth-shield/index.html))
 * [Satellites](https://vasturiano.github.io/react-globe.gl/example/satellites/index.html) ([source](https://github.com/vasturiano/react-globe.gl/blob/master/example/satellites/index.html))
@@ -78,6 +83,7 @@ ReactDOM.render(
 * [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)
@@ -200,22 +206,45 @@ ReactDOM.render(
 | --- | :--: | :--: | --- |
 | <b>pathsData</b> | <i>array</i> | `[]` | List of lines to represent in the paths map layer. Each path is displayed as a line that connects all the coordinate pairs in the path array. |
 | <b>pathLabel</b> | <i>string</i> or <i>func</i> | `name` | Path object accessor function or attribute for label (shown as tooltip). Supports plain text or HTML content. |
-| <b>pathPoints | <i>array</i>, <i>string</i> or <i>func</i> | `pnts => pnts` | Path object accessor function, attribute or an array for the set of points that define the path line. By default, each path point is assumed to be a 2-position array (`[<lat>, <lon>]`). This default behavior can be modified using the `pathPointLat` and `pathPointLng` methods. |
-| <b>pathPointLat | <i>number</i>, <i>string</i> or <i>func</i> | `arr => arr[0]` | Path point object accessor function, attribute or a numeric constant for the latitude coordinate. |
-| <b>pathPointLng | <i>number</i>, <i>string</i> or <i>func</i> | `arr => arr[1]` | Path point object accessor function, attribute or a numeric constant for the longitude coordinate. |
-| <b>pathPointAlt | <i>number</i>, <i>string</i> or <i>func</i> | 0.001 | Path point object accessor function, attribute or a numeric constant for the point altitude, in terms of globe radius units (`0` = 0 altitude (ground), `1` = globe radius). |
-| <b>pathResolution | <i>number</i> | 2 | The path's angular resolution, in lat/lng degrees. If the ground distance (excluding altitude) between two adjacent path points is larger than this value, the line segment will be interpolated in order to approximate the curvature of the sphere surface. Lower values yield more perfectly curved lines, at the cost of performance. |
-| <b>pathColor | <i>string</i>, <i>[string, ...]</i> or <i>func</i> | `() => '#ffffaa'` | Path object accessor function or attribute for the line's color. Also supports color gradients by passing an array of colors, or a color interpolator function. Transparent colors are not supported in Fat Lines with set width. |
-| <b>pathStroke | <i>number</i>, <i>string</i> or <i>func</i> | `null` | Path object accessor function, attribute or a numeric constant for the line's diameter, in angular degrees. A value of `null` or `undefined` will render a [ThreeJS Line](https://threejs.org/docs/#api/objects/Line) whose width is constant (`1px`) regardless of the camera distance. Otherwise, a [FatLine](https://github.com/vasturiano/three-fatline) is used. |
-| <b>pathDashLength | <i>number</i>, <i>string</i> or <i>func</i> | 1 | Path object accessor function, attribute or a numeric constant for the length of the dashed segments in the path line, in terms of relative length of the whole line (`1` = full line length). |
-| <b>pathDashGap | <i>number</i>, <i>string</i> or <i>func</i> | 0 | Path object accessor function, attribute or a numeric constant for the length of the gap between dash segments, in terms of relative line length. |
-| <b>pathDashInitialGap | <i>number</i>, <i>string</i> or <i>func</i> | 0 | 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. |
-| <b>pathDashAnimateTime | <i>number</i>, <i>string</i> or <i>func</i> | 0 | 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. |
-| <b>pathTransitionDuration | <i>number</i> | 1000 | 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. |
-| <b>onPathClick</b> | <i>func</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>func</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>pathPoints</b> | <i>array</i>, <i>string</i> or <i>func</i> | `pnts => pnts` | Path object accessor function, attribute or an array for the set of points that define the path line. By default, each path point is assumed to be a 2-position array (`[<lat>, <lon>]`). This default behavior can be modified using the `pathPointLat` and `pathPointLng` methods. |
+| <b>pathPointLat</b> | <i>number</i>, <i>string</i> or <i>func</i> | `arr => arr[0]` | Path point object accessor function, attribute or a numeric constant for the latitude coordinate. |
+| <b>pathPointLng</b> | <i>number</i>, <i>string</i> or <i>func</i> | `arr => arr[1]` | Path point object accessor function, attribute or a numeric constant for the longitude coordinate. |
+| <b>pathPointAlt</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0.001 | Path point object accessor function, attribute or a numeric constant for the point altitude, in terms of globe radius units (`0` = 0 altitude (ground), `1` = globe radius). |
+| <b>pathResolution</b> | <i>number</i> | 2 | The path's angular resolution, in lat/lng degrees. If the ground distance (excluding altitude) between two adjacent path points is larger than this value, the line segment will be interpolated in order to approximate the curvature of the sphere surface. Lower values yield more perfectly curved lines, at the cost of performance. |
+| <b>pathColor</b> | <i>string</i>, <i>[string, ...]</i> or <i>func</i> | `() => '#ffffaa'` | Path object accessor function or attribute for the line's color. Also supports color gradients by passing an array of colors, or a color interpolator function. Transparent colors are not supported in Fat Lines with set width. |
+| <b>pathStroke</b> | <i>number</i>, <i>string</i> or <i>func</i> | `null` | Path object accessor function, attribute or a numeric constant for the line's diameter, in angular degrees. A value of `null` or `undefined` will render a [ThreeJS Line](https://threejs.org/docs/#api/objects/Line) whose width is constant (`1px`) regardless of the camera distance. Otherwise, a [FatLine](https://github.com/vasturiano/three-fatline) is used. |
+| <b>pathDashLength</b> | <i>number</i>, <i>string</i> or <i>func</i> | 1 | Path object accessor function, attribute or a numeric constant for the length of the dashed segments in the path line, in terms of relative length of the whole line (`1` = full line length). |
+| <b>pathDashGap</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0 | Path object accessor function, attribute or a numeric constant for the length of the gap between dash segments, in terms of relative line length. |
+| <b>pathDashInitialGap</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0 | 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. |
+| <b>pathDashAnimateTime</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0 | 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. |
+| <b>pathTransitionDuration</b> | <i>number</i> | 1000 | 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. |
+| <b>onPathClick</b> | <i>func</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>func</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>func</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/react-globe.gl/example/heatmap/"><img width="70%" src="https://vasturiano.github.io/react-globe.gl/example/heatmap/preview.png"></a>
+</p>
+
+| Prop | Type | Default | Description |
+| --- | :--: | :--: | --- |
+| <b>heatmapsData</b> | <i>array</i> | `[]` | 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>string</i> or <i>func</i> | `pnts => pnts` | 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. |
+| <b>heatmapPointLat</b> | <i>number</i>, <i>string</i> or <i>func</i> | `arr => arr[0]` | Heatmap point object accessor function, attribute or a numeric constant for the latitude coordinate. |
+| <b>heatmapPointLng</b> | <i>number</i>, <i>string</i> or <i>func</i> | `arr => arr[1]` | Heatmap point object accessor function, attribute or a numeric constant for the longitude coordinate. |
+| <b>heatmapPointWeight</b> | <i>number</i>, <i>string</i> or <i>func</i> | 1 | 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. |
+| <b>heatmapBandwidth</b> | <i>number</i>, <i>string</i> or <i>func</i> | 4 | 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. |
+| <b>heatmapColorFn</b> | <i>string</i> or <i>func</i> | [Turbo colormap](https://blog.research.google/2019/08/turbo-improved-rainbow-colormap-for.html) interpolator with fading opacity | 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. |
+| <b>heatmapColorSaturation</b> | <i>number</i>, <i>string</i> or <i>func</i> | 1.5 | 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. |
+| <b>heatmapBaseAltitude</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0.01 | 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). |
+| <b>heatmapTopAltitude</b> | <i>number</i>, <i>string</i> or <i>func</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>number</i> | 0 | 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. |
+| <b>onHeatmapClick</b> | <i>func</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>func</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>func</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">
@@ -358,7 +387,7 @@ ReactDOM.render(
 | <b>objectLat</b> | <i>number</i>, <i>string</i> or <i>func</i> | `lat` | Object accessor function, attribute or a numeric constant for the latitude coordinate of the object's position. |
 | <b>objectLng</b> | <i>number</i>, <i>string</i> or <i>func</i> | `lng` | Object accessor function, attribute or a numeric constant for the longitude coordinate of the object's position. |
 | <b>objectAltitude</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0.01 | Object accessor function, attribute or a numeric constant for the altitude coordinate of the object's position, in terms of globe radius units. |
-| <b>objectRotation</b> | <i>{[x], [y], [z]}</i>, <i>str</i> or <i>func</i> | | Object accessor function, attribute or a `{x, y, z}` object for the object's rotation (in degrees). Each dimension is optional, allowing for rotation only in some axes. Rotation is applied in the order **X**->**Y**->**Z**. |
+| <b>objectRotation</b> | <i>{[x], [y], [z]}</i>, <i>string</i> or <i>func</i> | | Object accessor function, attribute or a `{x, y, z}` object for the object's rotation (in degrees). Each dimension is optional, allowing for rotation only in some axes. Rotation is applied in the order **X**->**Y**->**Z**. |
 | <b>objectFacesSurface</b> | <i>bool</i>, <i>string</i> or <i>func</i> | `true` | Object accessor function, attribute or a boolean constant for whether the object should be rotated to face (away from) the globe surface (`true`), or be left in its original universe orientation (`false`). |
 | <b>objectThreeObject</b> | <i>Object3d</i>, <i>string</i> or <i>func</i> | *A yellow sphere* | Object accessor function or attribute for defining a custom 3d object to render as part of the objects map layer. Should return an instance of [ThreeJS Object3d](https://threejs.org/docs/index.html#api/core/Object3D). |
 | <b>onObjectClick</b> | <i>func</i> | *-* | Callback function for object (left-button) clicks. The object itself, the event and the clicked coordinates are included as arguments: `onObjectClick(obj, event, { lat, lng, altitude })`. |

package/dist/react-globe.gl.d.ts

@@ -132,6 +132,22 @@ interface GlobeProps extends ConfigOptions {
   onPathRightClick?: (path: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onPathHover?: (path: object | null, prevPath: object | null) => void;
 
+  // Heatmaps layer
+  heatmapsData?: object[];
+  heatmapPoints?: ObjAccessor<any[]>;
+  heatmapPointLat?: Accessor<any, number>;
+  heatmapPointLng?: Accessor<any, number>;
+  heatmapPointWeight?: Accessor<any, number>;
+  heatmapBandwidth?: ObjAccessor<number>;
+  heatmapColorFn?: ObjAccessor<(t: number) => string>;
+  heatmapColorSaturation?: ObjAccessor<number>;
+  heatmapBaseAltitude?: ObjAccessor<number>;
+  heatmapTopAltitude?: ObjAccessor<number>;
+  heatmapsTransitionDuration?: number;
+  onHeatmapClick?: (heatmap: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
+  onHeatmapRightClick?: (heatmap: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
+  onHeatmapHover?: (heatmap: object | null, prevHeatmap: object | null) => void;
+
   // Hex Bin layer
   hexBinPointsData?: object[];
   hexBinPointLat?: ObjAccessor<number>;
@@ -272,4 +288,4 @@ type FCwithRef<P = {}, R = {}> = React.FunctionComponent<P & { ref?: React.Mutab
 
 declare const Globe: FCwithRef<GlobeProps, GlobeMethods>;
 
-export { GlobeMethods, GlobeProps, Globe as default };
+export { type GlobeMethods, type GlobeProps, Globe as default };