three-globe

Three-globe is a ThreeJS WebGL class designed to represent data visualization layers on a globe using a spherical projection. It is inspired by Google's WebGL Globe and allows developers to layer various types of data (points, arcs, polygons, etc.) onto a 3D globe.

For different environments, you can use the standalone version (globe.gl) or the React Three Fiber bindings (r3f-globe).

To use three-globe, you can import it as a module or include it via a CDN script tag. Once initialized, you can configure the globe with images and data, then add the resulting object to a standard Three.js scene.

Module Import

import ThreeGlobe from 'three-globe';

Script Tag

<script src="//cdn.jsdelivr.net/npm/three-globe"></script>

Basic Usage

const myGlobe = new ThreeGlobe()
  .globeImageUrl(myImageUrl)
  .pointsData(myData);

const myScene = new THREE.Scene();
myScene.add(myGlobe);

import ThreeGlobe from 'three-globe';

// or using a script tag
// <script src="//cdn.jsdelivr.net/npm/three-globe"></script>

const myGlobe = new ThreeGlobe()
  .globeImageUrl(myImageUrl)
  .pointsData(myData);

const myScene = new THREE.Scene();
myScene.add(myGlobe);

Most layer methods in ThreeGlobe use an Accessor pattern. This allows you to pass data to the globe in three ways:

1. A direct value: e.g., pointRadius(5) sets all points to radius 5.
2. A string key: e.g., pointRadius('radius') tells the globe to look for a property named radius on each object in your data array.
3. A callback function: e.g., pointRadius(d => d.customRadius) allows for custom logic per data object.

This pattern is used across all layers (Points, Arcs, Polygons, etc.) to map your raw data to visual properties like latitude, longitude, color, altitude, and radius.

To create a new globe instance, instantiate the ThreeGlobe class. You can optionally pass a ConfigOptions object to the constructor.

ConfigOptions properties:

• waitForGlobeReady (boolean): Whether to wait for the globe to be ready.
• animateIn (boolean): Whether to animate the initial appearance of the globe.

The Points Layer represents data as cylindrical 3D objects rising from the globe surface.

Key methods include:

• pointsData(array): The list of data points to render.
• pointLat(accessor): Accessor for the cylinder's center latitude.
• pointLng(accessor): Accessor for the cylinder's center longitude.
• pointColor(accessor): Accessor for the cylinder color.
• pointAltitude(accessor): Accessor for the cylinder's altitude (0 = flat, 1 = globe radius).
• pointRadius(accessor): Accessor for the cylinder's radius in angular degrees.
• pointsMerge(boolean): If true, merges all point meshes into a single ThreeJS object for better performance.
• pointsTransitionDuration(ms): Duration for animating geometry changes. Only works if pointsMerge is disabled.

The 3D Objects Layer allows rendering custom ThreeJS Object3d instances at specific locations.

• objectsData([array]): The list of custom 3D objects.
• objectLat([num, str, or fn]): Accessor for latitude (default: 'lat').
• objectLng([num, str, or fn]): Accessor for longitude (default: 'lng').
• objectAltitude([num, str, or fn]): Accessor for altitude in globe radius units (default: 0.01).
• objectRotation([{[x], [y], [z]}, str, or fn]): Accessor for rotation in degrees. Supports partial {x, y, z} objects. Rotation order is X->Y->Z.
• objectFacesSurface([boolean, str, or fn]): Whether to rotate the object to face the globe surface (default: true).
• objectThreeObject([Object3d, str, or fn]): Accessor to define the custom 3D object (default: a yellow sphere).

The Hexed Polygons layer represents GeoJSON shapes (Polygon or MultiPolygon) as a collection of hexagons.

Key configuration options:

• hexPolygonsData: Array of polygon shapes.
• hexPolygonGeoJsonGeometry: Accessor for the GeoJSON geometry (must contain type and coordinates).
• hexPolygonResolution: H3 resolution (0-15) for the hexagons.
• hexPolygonUseDots: If true, represents polygon points as circular dots instead of hexagons.
• hexPolygonDotResolution: Resolution for circular dots (number of segments) if hexPolygonUseDots is enabled.
• hexPolygonColor: Accessor for the color of the hexagons.
• hexPolygonAltitude: Altitude in globe radius units.
• hexPolygonsTransitionDuration: Duration (ms) for animating altitude and margin changes.

Three-globe provides utility methods for converting between spherical (geographic) and cartesian (3D spatial) coordinates:

• getGlobeRadius(): Returns the cartesian distance of a globe radius in absolute spatial units.
• getCoords(lat, lng, [altitude]): Translates spherical coordinates (latitude, longitude, and optional altitude in globe radius units) to {x, y, z} cartesian spatial coordinates.
• toGeoCoords({x, y, z}): Translates cartesian {x, y, z} coordinates to {lat, lng, altitude} spherical coordinates (altitude is in globe radius units).

The Tiles layer displays spherical surface segments (tiles) that can be styled individually.

Key configuration options:

• tilesData: Array of tile objects.
• tileLat / tileLng: Accessors for the segment's centroid coordinates.
• tileWidth / tileHeight: Longitudinal width and latitudinal height in angular degrees.
• tileAltitude: Altitude in globe radius units.
• tileMaterial: Accessor for a ThreeJS Material to style the surface.
• tileUseGlobeProjection: If true, shapes the segment to the globe's projection; if false, shapes it as if on the equator.
• tileCurvatureResolution: Resolution (angular degrees) for surface curvature approximation.
• tilesTransitionDuration: Duration (ms) for animating geometry changes.