react-globe.gl 2.29.5 → 2.31.0

package/README.md

@@ -90,6 +90,7 @@ ReactDOM.render(
 * [Hex Bin Layer](#hex-bin-layer)
 * [Hexed Polygons Layer](#hexed-polygons-layer)
 * [Tiles Layer](#tiles-layer)
+* [Particles Layer](#particles-layer)
 * [Rings Layer](#rings-layer)
 * [Labels Layer](#labels-layer)
 * [HTML Elements Layer](#html-elements-layer)
@@ -320,6 +321,28 @@ ReactDOM.render(
 | <b>onTileRightClick</b> | <i>func</i> | *-* | Callback function for tile right-clicks. The tile object, the event object and the clicked coordinates are included as arguments: `onTileRightClick(tile, event, { lat, lng, altitude })`. |
 | <b>onTileHover</b> | <i>func</i> | *-* | Callback function for tile mouse over events. The tile object (or `null` if there's no tile under the mouse line of sight) is included as the first argument, and the previous tile object (or `null`) as second argument: `onTileHover(tile, prevTile)`. |
 
+### Particles Layer
+
+<p align="center">
+   <a href="//vasturiano.github.io/react-globe.gl/example/satellites/"><img width="70%" src="https://vasturiano.github.io/react-globe.gl/example/satellites/preview.png"></a>
+</p>
+
+| Prop | Type | Default | Description |
+| --- | :--: | :--: | --- |
+| <b>particlesData</b> | <i>array</i> | `[]` | List of particle sets to represent in the particles map layer. Each particle set is displayed as a group of [Points](https://threejs.org/docs/#api/en/objects/Points). Each point in the group is a geometry vertex and can be individually positioned anywhere relative to the globe. |
+| <b>particlesList</b> | <i>string</i> or <i>func</i> | `d => d` | Particle set accessor function or attribute for the list of particles in the set. By default, the data structure is expected to be an array of arrays of individual particle objects. |
+| <b>particleLabel</b> | <i>string</i> or <i>func</i> | `name` | Particle object accessor function or attribute for label (shown as tooltip). Supports plain text or HTML content. |
+| <b>particleLat</b> | <i>number</i>, <i>string</i> or <i>func</i> | `lat` | Particle object accessor function, attribute or a numeric constant for the latitude coordinate. |
+| <b>particleLng</b> | <i>number</i>, <i>string</i> or <i>func</i> | `lng` | Particle object accessor function, attribute or a numeric constant for the longitude coordinate. |
+| <b>particleAltitude</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0.01 | Particle object accessor function, attribute or a numeric constant for the altitude in terms of globe radius units. |
+| <b>particlesSize</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0.5 | Particle set accessor function, attribute or a numeric constant for the size of all the particles in the group. |
+| <b>particlesSizeAttenuation</b> | <i>bool</i>, <i>string</i> or <i>func</i> | `true` | Particle set accessor function, attribute or a boolean constant for whether the size of each particle on the screen should be attenuated according to the distance to the camera. |
+| <b>particlesColor</b> | <i>string</i> or <i>func</i> | `white` | Particle set accessor function or attribute for the color of all the particles in the group. This setting will be ignored if `particlesTexture` is defined. |
+| <b>particlesTexture</b> | <i>string</i> or <i>func</i> | - | Particle set accessor function or attribute for the [Texture](https://threejs.org/docs/#api/en/textures/Texture) to be applied to all the particles in the group. |
+| <b>onParticleClick</b> | <i>func</i> | - | Callback function for particle (left-button) clicks. The particle object, the event object and the clicked coordinates are included as arguments: `onParticleClick(particle, event, { lat, lng, altitude })`. |
+| <b>onParticleRightClick</b> | <i>func</i> | - | Callback function for particle right-clicks. The particle object, the event object and the clicked coordinates are included as arguments: `onParticleRightClick(particle, event, { lat, lng, altitude })`. |
+| <b>onParticleHover</b> | <i>func</i> | - | Callback function for particle mouse over events. The particle object (or `null` if there's no particle under the mouse line of sight) is included as the first argument, and the previous particle object (or `null`) as second argument: `onParticleHover(particle, prevParticle)`. |
+
 ### Rings Layer
 
 <p align="center">
@@ -382,10 +405,6 @@ ReactDOM.render(
 
 ### 3D Objects Layer
 
-<p align="center">
-   <a href="//vasturiano.github.io/react-globe.gl/example/satellites/"><img width="70%" src="https://vasturiano.github.io/react-globe.gl/example/satellites/preview.png"></a>
-</p>
-
 | Prop | Type | Default | Description |
 | --- | :--: | :--: | --- |
 | <b>objectsData</b> | <i>array</i> | `[]` | Getter/setter for the list of custom 3D objects to represent in the objects layer. Each object is rendered according to the `objectThreeObject` method. |
@@ -423,7 +442,7 @@ ReactDOM.render(
 | <b>rendererConfig</b> | <i>object</i> | `{ antialias: true, alpha: true }` | Configuration parameters to pass to the [ThreeJS WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer) constructor. This prop only has an effect on component mount. |
 | <b>enablePointerInteraction</b> | <i>bool</i> | `true` | Whether to enable the mouse tracking events. This activates an internal tracker of the canvas mouse position and enables the functionality of object hover/click and tooltip labels, at the cost of performance. If you're looking for maximum gain in your globe performance it's recommended to switch off this property. |
 | <b>pointerEventsFilter</b> | <i>func</i> | `() => true` | Filter function which defines whether a particular object can be the target of pointer interactions. In general, objects that are closer to the camera get precedence in capturing pointer events. This function allows having ignored object layers so that pointer events can be passed through to deeper objects in the various globe layers. The ThreeJS object and its associated data (if any) are passed as arguments: `pointerEventsFilter(obj, data)`. The function should return a boolean value. |
-| <b>lineHoverPrecision</b> | <i>number</i> | 0.2 | Precision to use when detecting hover events over [Line](https://threejs.org/docs/#api/objects/Line) objects, such as arcs and paths. |
+| <b>lineHoverPrecision</b> | <i>number</i> | 0.2 | Precision to use when detecting hover events over [Line](https://threejs.org/docs/#api/objects/Line) and [Points](https://threejs.org/docs/#api/objects/Points) objects, such as arcs, paths or particles. |
 
 | Method | Arguments | Description |
 | --- | :--: | --- |

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

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Material, Object3D, Light, Scene, Camera, WebGLRenderer } from 'three';
+import { Material, Texture, Object3D, Light, Scene, Camera, WebGLRenderer } from 'three';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
 import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
 import { ConfigOptions, GlobeInstance } from 'globe.gl';
@@ -8,6 +8,8 @@ type Accessor<In, Out> = Out | string | ((obj: In) => Out);
 type ObjAccessor<T> = Accessor<object, T>;
 type HexBinAccessor<T> = Accessor<HexBin, T>;
 
+type TooltipContent = string | React.ReactHTMLElement<HTMLElement>;
+
 interface HexBin {
   points: object[],
   sumWeight: number,
@@ -71,7 +73,7 @@ interface GlobeProps extends ConfigOptions {
   pointResolution?: number;
   pointsMerge?: boolean;
   pointsTransitionDuration?: number;
-  pointLabel?: ObjAccessor<string>;
+  pointLabel?: ObjAccessor<TooltipContent>;
   onPointClick?: (point: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onPointRightClick?: (point: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onPointHover?: (point: object | null, prevPoint: object | null) => void;
@@ -93,7 +95,7 @@ interface GlobeProps extends ConfigOptions {
   arcDashInitialGap?: ObjAccessor<number>;
   arcDashAnimateTime?: ObjAccessor<number>;
   arcsTransitionDuration?: number;
-  arcLabel?: ObjAccessor<string>;
+  arcLabel?: ObjAccessor<TooltipContent>;
   onArcClick?: (arc: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onArcRightClick?: (arc: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onArcHover?: (arc: object | null, prevArc: object | null) => void;
@@ -109,7 +111,7 @@ interface GlobeProps extends ConfigOptions {
   polygonAltitude?: ObjAccessor<number>;
   polygonCapCurvatureResolution?: ObjAccessor<number>;
   polygonsTransitionDuration?: number;
-  polygonLabel?: ObjAccessor<string>;
+  polygonLabel?: ObjAccessor<TooltipContent>;
   onPolygonClick?: (polygon: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onPolygonRightClick?: (polygon: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onPolygonHover?: (polygon: object | null, prevPolygon: object | null) => void;
@@ -128,7 +130,7 @@ interface GlobeProps extends ConfigOptions {
   pathDashInitialGap?: ObjAccessor<number>;
   pathDashAnimateTime?: ObjAccessor<number>;
   pathTransitionDuration?: number;
-  pathLabel?: ObjAccessor<string>;
+  pathLabel?: ObjAccessor<TooltipContent>;
   onPathClick?: (path: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onPathRightClick?: (path: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onPathHover?: (path: object | null, prevPath: object | null) => void;
@@ -162,7 +164,7 @@ interface GlobeProps extends ConfigOptions {
   hexSideColor?: HexBinAccessor<string>;
   hexBinMerge?: boolean;
   hexTransitionDuration?: number;
-  hexLabel?: HexBinAccessor<string>;
+  hexLabel?: HexBinAccessor<TooltipContent>;
   onHexClick?: (hex: HexBin, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onHexRightClick?: (hex: HexBin, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onHexHover?: (hex: HexBin | null, prevHex: HexBin | null) => void;
@@ -178,7 +180,7 @@ interface GlobeProps extends ConfigOptions {
   hexPolygonCurvatureResolution?: ObjAccessor<number>;
   hexPolygonDotResolution?: ObjAccessor<number>;
   hexPolygonsTransitionDuration?: number;
-  hexPolygonLabel?: ObjAccessor<string>;
+  hexPolygonLabel?: ObjAccessor<TooltipContent>;
   onHexPolygonClick?: (polygon: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onHexPolygonRightClick?: (polygon: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onHexPolygonHover?: (polygon: object | null, prevPolygon: object | null) => void;
@@ -194,11 +196,26 @@ interface GlobeProps extends ConfigOptions {
   tileMaterial?: ObjAccessor<Material>;
   tileCurvatureResolution?: ObjAccessor<number>;
   tilesTransitionDuration?: number;
-  tileLabel?: ObjAccessor<string>;
+  tileLabel?: ObjAccessor<TooltipContent>;
   onTileClick?: (tile: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onTileRightClick?: (tile: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onTileHover?: (tile: object | null, prevTile: object | null) => void;
 
+  // Particles layer
+  particlesData?: object[];
+  particlesList?: ObjAccessor<object[]>;
+  particleLat?: ObjAccessor<number>;
+  particleLng?: ObjAccessor<number>;
+  particleAltitude?: ObjAccessor<number>;
+  particlesSize?: ObjAccessor<number>;
+  particlesSizeAttenuation?: ObjAccessor<boolean>;
+  particlesColor?: ObjAccessor<string>;
+  particlesTexture?: ObjAccessor<Texture>;
+  particleLabel?: ObjAccessor<TooltipContent>;
+  onParticleClick?: (particle: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
+  onParticleRightClick?: (particle: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
+  onParticleHover?: (particle: object | null, prevParticle: object | null) => void;
+
   // Rings Layer
   ringsData?: object[];
   ringLat?: ObjAccessor<number>;
@@ -225,7 +242,7 @@ interface GlobeProps extends ConfigOptions {
   labelDotRadius?: ObjAccessor<number>;
   labelDotOrientation?: ObjAccessor<LabelOrientation>;
   labelsTransitionDuration?: number;
-  labelLabel?: ObjAccessor<string>;
+  labelLabel?: ObjAccessor<TooltipContent>;
   onLabelClick?: (label: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onLabelRightClick?: (label: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onLabelHover?: (label: object | null, prevLabel: object | null) => void;
@@ -246,7 +263,7 @@ interface GlobeProps extends ConfigOptions {
   objectRotation?: ObjAccessor<{ x?: number, y?: number, z?: number } | null>;
   objectFacesSurfaces?: ObjAccessor<boolean>;
   objectThreeObject?: Object3D | string | ((d: object) => Object3D);
-  objectLabel?: ObjAccessor<string>;
+  objectLabel?: ObjAccessor<TooltipContent>;
   onObjectClick?: (obj: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onObjectRightClick?: (obj: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onObjectHover?: (obj: object | null, prevObj: object | null) => void;
@@ -255,7 +272,7 @@ interface GlobeProps extends ConfigOptions {
   customLayerData?: object[];
   customThreeObject?: Object3D | string | ((d: object) => Object3D);
   customThreeObjectUpdate?: string | ((obj: Object3D, objData: object) => void);
-  customLayerLabel?: ObjAccessor<string>;
+  customLayerLabel?: ObjAccessor<TooltipContent>;
   onCustomLayerClick?: (obj: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onCustomLayerRightClick?: (obj: object, event: MouseEvent, coords: { lat: number, lng: number, altitude: number }) => void;
   onCustomLayerHover?: (obj: object | null, prevObj: object | null) => void;