globe.gl

Globe.GL

A web component to represent data visualization layers on a 3-dimensional globe in spherical projection. This library is a convenience wrapper around the three-globe plugin, and uses ThreeJS/WebGL for 3D rendering. Largely inspired by the WebGL Globe.

Check out the examples:

• Basic (source)
• World Population (source)
• Arc Links (source)

Quick start

import Globe from 'globe.gl';

or

const Globe = require('globe.gl');

or even

<script src="//unpkg.com/globe.gl"></script>

then

const myGlobe = Globe();
myGlobe(<myDOMElement>)
  .globeImageUrl(<imageUrl>)
  .pointsData(<myData>);

API reference

Initialisation

Globe({ configOptions })(<domElement>)

Config options	Description	Default
rendererConfig: object	Configuration parameters to pass to the ThreeJS WebGLRenderer constructor.	{ antialias: true, alpha: true }
animateIn: boolean	Whether to animate the globe initialization, by scaling and rotating the globe into its inital position.	true

Container layout

Method	Description	Default
width([px])	Getter/setter for the canvas width.	<window width>
height([px])	Getter/setter for the canvas height.	<window height>
backgroundColor([str])	Getter/setter for the background color.	#000011

Globe Layer

Method	Description	Default
globeImageUrl([url])	Getter/setter for the URL of the image used in the material that wraps the globe. If no image is provided, the globe is represented as a black sphere.	null
bumpImageUrl([url])	Getter/setter for the URL of the image used to create a bump map in the material, to represent the globe's terrain.	null
showAtmosphere([boolean])	Getter/setter for whether to show a bright halo surrounding the globe, representing the atmosphere.	true
showGraticules([boolean])	Getter/setter for whether to show a graticule grid demarking latitude and longitude lines at every 10 degrees.	false

Points Layer

Method	Description	Default
pointsData([array])	Getter/setter for the list of points to represent in the points map layer. Each point is displayed as a cylindrical 3D object rising perpendicularly from the surface of the globe.	[]
pointLabel([str or fn])	Point object accessor function or attribute for label (shown as tooltip). Supports plain text or HTML content.	name
pointLat([num, str or fn])	Point object accessor function, attribute or a numeric constant for the cylinder's center latitude coordinate.	lat
pointLng([num, str or fn])	Point object accessor function, attribute or a numeric constant for the cylinder's center longitude coordinate.	lat
pointColor([str or fn])	Point object accessor function or attribute for the cylinder color.	() => '#ffffaa'
pointAltitude([num, str or fn])	Point object accessor function, attribute or a numeric constant for the cylinder's altitude in terms of globe radius units (0 = 0 altitude (flat circle), 1 = globe radius).	0.1
pointRadius([num, str or fn])	Point object accessor function, attribute or a numeric constant for the cylinder's radius, in angular degrees.	0.25
pointResolution([num])	Getter/setter for the radial geometric resolution of each cylinder, expressed in how many slice segments to divide the circumference. Higher values yield smoother cylinders.	12
pointsMerge([boolean])	Getter/setter for whether to merge all the point meshes into a single ThreeJS object, for improved rendering performance. Visually both options are equivalent, setting this option only affects the internal organization of the ThreeJS objects.	false
pointsTransitionDuration([num])	Getter/setter for duration (ms) of the transition to animate point changes involving geometry modifications. A value of 0 will move the objects immediately to their final position. New objects are animated by scaling them from the ground up. Only works if pointsMerge=false.	1000
onPointClick(fn)	Callback function for point (left-button) clicks. The point object is included as single argument onPointClick(point). Only works if pointsMerge is disabled.	-
onPointRightClick(fn)	Callback function for point right-clicks. The point object is included as single argument onPointRightClick(point). Only works if pointsMerge is disabled.	-
onPointHover(fn)	Callback function for point mouse over events. The point object (or null if there's no point under the mouse line of sight) is included as the first argument, and the previous point object (or null) as second argument: onPointHover(point, prevPoint). Only works if pointsMerge is disabled.	-

Arcs Layer

Method	Description	Default
arcsData([array])	Getter/setter for the list of links to represent in the arcs map layer. Each link is displayed as an arc line that rises from the surface of the globe, connecting the start to the end coordinates.	[]
arcLabel([str or fn])	Arc object accessor function or attribute for label (shown as tooltip). Supports plain text or HTML content.	name
arcStartLat([num, str or fn])	Arc object accessor function, attribute or a numeric constant for the line's start latitude coordinate.	startLat
arcStartLng([num, str or fn])	Arc object accessor function, attribute or a numeric constant for the line's start longitude coordinate.	startLng
arcEndLat([num, str or fn])	Arc object accessor function, attribute or a numeric constant for the line's end latitude coordinate.	endLat
arcEndLng([num, str or fn])	Arc object accessor function, attribute or a numeric constant for the line's end longitude coordinate.	endLng
arcColor([str or fn])	Arc object accessor function or attribute for the line's color.	() => '#ffffaa'
arcAltitude([num, str or fn])	Arc object accessor function, attribute or a numeric constant for the arc's maximum altitude (ocurring at the half-way distance between the two points) in terms of globe radius units (0 = 0 altitude (ground line), 1 = globe radius). If a value of null or undefined is used, the altitude is automatically set proportionally to the distance between the two points, according to the scale set in arcAltitudeAutoScale.	null
arcAltitudeAutoScale([num, str or fn])	Arc object accessor function, attribute or a numeric constant for the scale of the arc's automatic altitude, in terms of units of the great-arc distance between the two points. A value of 1 indicates the arc should be as high as its length on the ground. Only applicable if arcAltitude is not set.	0.5
arcStroke([num, str or fn])	Arc 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 whose width is constant (1px) regardless of the camera distance. Otherwise, a TubeGeometry is used.	null
arcCurveResolution([num])	Getter/setter for the arc's curve resolution, expressed in how many straight line segments to divide the curve by. Higher values yield smoother curves.	64
arcCircularResolution([num])	Getter/setter for the radial geometric resolution of each line, expressed in how many slice segments to divide the tube's circumference. Only applicable when using Tube geometries (defined arcStroke).	6
arcsTransitionDuration([num])	Getter/setter for duration (ms) of the transition to animate arc changes involving geometry modifications. A value of 0 will move the objects immediately to their final position. New arcs are animated by rising them from the ground up.	1000
onArcClick(fn)	Callback function for arc (left-button) clicks. The arc object is included as single argument onArcClick(arc).	-
onArcRightClick(fn)	Callback function for arc right-clicks. The arc object is included as single argument onArcRightClick(arc).	-
onArcHover(fn)	Callback function for arc mouse over events. The arc object (or null if there's no arc under the mouse line of sight) is included as the first argument, and the previous arc object (or null) as second argument: onArcHover(arc, prevArc).	-

Custom Layer

Method	Description	Default
customLayerData([array])	Getter/setter for the list of items to represent in the custom map layer. Each item is rendered according to the customThreeObject method.	[]
customLayerLabel([str or fn])	Object accessor function or attribute for label (shown as tooltip). Supports plain text or HTML content.	name
customThreeObject([Object3d, str or fn])	Object accessor function or attribute for generating a custom 3d object to render as part of the custom map layer. Should return an instance of ThreeJS Object3d. The callback method's signature includes the object's data as well as the globe radius: customThreeObject((objData, globeRadius) => { ... }).	null
customThreeObjectUpdate([str or fn])	Object accessor function or attribute for updating an existing custom 3d object with new data. This can be used for performance improvement on data updates as the objects don't need to be removed and recreated at each update. The callback method's signature includes the object to be update, its new data and the globe radius: customThreeObjectUpdate((obj, objData, globeRadius) => { ... }).	null
onCustomLayerClick(fn)	Callback function for custom object (left-button) clicks. The custom object is included as single argument onCustomLayerClick(obj).	-
onCustomLayerRightClick(fn)	Callback function for custom object right-clicks. The custom object is included as single argument onCustomLayerRightClick(obj).	-
onCustomLayerHover(fn)	Callback function for custom object mouse over events. The custom object (or null if there's no object under the mouse line of sight) is included as the first argument, and the previous custom object (or null) as second argument: onCustomLayerHover(obj, prevObj).	-

Render control

Method	Description	Default
pauseAnimation()	Pauses the rendering cycle of the component, effectively freezing the current view and cancelling all user interaction. This method can be used to save performance in circumstances when a static image is sufficient.
resumeAnimation()	Resumes the rendering cycle of the component, and re-enables the user interaction. This method can be used together with pauseAnimation for performance optimization purposes.
enablePointerInteraction([boolean])	Getter/setter for 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 chart performance it's recommended to switch off this property.	true
cameraPosition([{x,y,z}], [lookAt], [ms])	Getter/setter for the camera position, in terms of x, y, z coordinates. Each of the coordinates is optional, allowing for motion in just some dimensions. The optional second argument can be used to define the direction that the camera should aim at, in terms of an {x,y,z} point in the 3D space. The 3rd optional argument defines the duration of the transition (in ms) to animate the camera motion. A value of 0 (default) moves the camera immediately to the final position.	By default the camera will face the center of the globe at a sensible z distance.
scene()	Access the internal ThreeJS Scene. Can be used to extend the current scene with additional objects not related to globe.gl.
camera()	Access the internal ThreeJS Camera.
renderer()	Access the internal ThreeJS WebGL renderer.
controls()	Access the internal ThreeJS orbit controls object.

Utility

Method	Description	Default
getCoords(lat, lng [,altitude])	Utility method to translate spherical coordinates. Given a pair of latitude/longitude coordinates and optionally altitude (in terms of globe radius units), returns the equivalent {x, y, z} cartesian spatial coordinates.