<div id="myearth" class="earth-container"></div>
var myearth = new Earth( "myearth", {
location: { lat : 22.5, lng : 20 },
mapLandColor: '#333333',
mapSeaColor: '#DDDDDD'
} );
Minimal Example
Asynchronous Integration
Preload & Fallback
console.log( document.getElementById('myearth').earth.location );
{ lat: 0, lng: 0 }
The geo location at the center of the earth. Also see the goTo method.
0.3
0.0 - 1.0
Constrains the earth's rotation when far northern and southern locations are shown to shift the focus to the Equator.
0 = no limits, 1 = fully constrained, the Equator is always at the center
Also see the dragPolarLimit property.
Example: Polar Limit
#F4F4F4
#0099FF
value of mapLandColor
0.3
0.25 - 1.0
In order to avoid display errors, you should not use values smaller than 0.25. If you want no borders, set mapBorderColor to the value of mapLandColor.
This CSS string is applied to the default SVG map. You can target countries by their ISO code.
mapStyles : "#US { fill: blue; stroke: blue; }"
Example: Map Styles > Colored Countries
Example: Country Selector
"" (uses the default SVG map)
You can use a SVG or any pixel image format. The image must be in 2:1 format, with equirectangular projection. SVGs must be saved with width and height attributes (not "responsive" mode Illustrator).
Example: Map Image
Example: Custom SVG Map
false
The earth surface becomes transparent if set to true and mapSeaColor has a value like RGBA(0, 0, 255, 0.5) or you use a mapImage with transparency.
Example: Earth Transparency
1.0
0.0 - 1.0
Controls the opacity of the inside of the earth.
#FFFFFF
Multiplys a color on the inside of the earth.
true
The following properties are only available if draggable: true.
true
true
If true the earth will keep spinning a while after dragging/swiping.
0.7
0.01 - 0.99
Controls how fast the earth loses momentum after dragging/swiping.
0.3
0.0 - 1.0
Like the polarLimit property but constrains the earth's rotation during dragging/swiping.
1
Also see the zoom option of the goTo method.
false
Zoomable by mouse wheel and gestures.
0.5
1.25
1
Zoom speed when zooming by mouse wheel or gestures.
false
The following properties are only available if autoRotate: true.
1
A negative value reverses the rotation direction.
0
Like autoRotateSpeed property but for up/down rotation.
1000 (ms)
Time to wait before auto rotating starts.
1000 (ms)
Acceleration time when auto rotating starts.
in-quad
Acceleration easing when auto rotating starts.
"simple"
if light: none 1 else 0.5
Controls the overall brightness.
0.5
Intensity of the sun or simple light.
#FFFFFF
#999999
Only available if light: simple.
false
Only available if light: sun. Provide a x/y object with values from -1 to 1.
E.g. { x: 0, y: -0.8 } for light from above.
{ lat: 0, lng: 0 }
Only available if light: sun and sunDirection: false. The sun shines on the given location.
true
Only available if light: sun.
false
Only available for the default SVG map or a custom SVG map set as mapImage.
Set to true to determine the ID of the hit SVG path (country code) during click, mousedown and mouseup events.
Example: Get Location
false
Set to true to display wireframes of the marker hotspots for debugging.
3 or 4 depending on container size
1 - 6
Controls various internal parameters like texture resolution and polygon count.
1 = very low quality, 2 = low quality, 3 = good quality (up to 1000px), 4 = high quality, ...
0.1
0.0 - 1.0
Only if light: sun. Shininess of the earth surface.
false
Set to true if you need to support IE11.
false
If you use legacySupportIE11: true, you can specify a map image that is only used by IE11.
Don't use this property if you use mapImage anyway.
Reference to the canvas of the map texture.
Reference to the rendering context of the map texture. These properties are available during and after the drawtexture event.
Call updateMap() after drawing on the mapCanvas to update the earth's texture.
About CanvasRenderingContext2D
Example: Draw Map Locations
The earth is rendered to this canvas element.
false
Set to true if you want to retrieve image data of the canvas.
Example: Capture Canvas Image
false
You can pause the earth to save performance when hiding the earth. The earth is not updated.
Milliseconds since the last animation frame.
You can access the THREE.js objects that render the earth. About THREE.js
console.log( myearth.scene );
You can animate the earth's location property for navigation, but using the goTo() method has advantages:
- previous animations are stopped
- you can use the special option approachAngle to navigate only if needed and only as much as needed.
- you can use the special option zoom to start a synchronosized zoom animation
myearth.goTo( { lat: -25, lng: 131 }, { relativeDuration: 100, approachAngle: 20, zoom: 1.1 } );
Call redrawMap() if you need to change the map*Color/mapStyles/mapImage properties after initialization.
Example: Country Selector
Example: Map Image
Call updateMap() after drawing on the mapCanvas to update the earth's texture.
Only available for the default SVG map or a custom SVG map set as mapImage.
Returns the ID of the SVG path element found at location.
If you use the default SVG map the ID equals the country ISO code.
Example: getLocation / hitTest
Skips the autoRotateDelay. If easeIn is false the earth immediatly rotates at full speed.
Interrupts auto rotating. The auto rotation restarts after the autoRotateDelay.
Get a x/y point of lat/lng location relative to the container element.
Example: getPoint
Get a lat/lng object of a x/y point on the page.
Example: getLocation / hitTest
Get the current radius of the earth in pixels.
Example: getRadius
Removes the earth and frees memory.
You can add own 3d meshes for markers. Learn more
Example: Custom Marker Meshes
Returns true if WebGL is supported. For Internet Explorer 11 this method only returns true if legacySupportIE11 is true.
Example: Legacy Support (IE 11)
Returns the approximate distance between two locations in kilometers.
Multiply by 0.621371 to get the distance in miles.
Returns the approximate angle between two locations in degrees (0.0 - 180.0).
Returns a lat/lng location between from and to at time. If lerpLatLng is true the lat/lng values are lerped as numbers (avoiding the polar regions) instead of the 3d position (shortest path).
The ready event is triggered once when the earth is initialized and you can start adding objects.
The drawtexture event is triggered on initialization or when the redrawMap() method is called. You can use this event to draw on the mapCanvas to modify the earth's texture.
Example: Draw Map Locations
myearth.addEventListener( 'click', function( event ) {
console.log( event.location );
} );
The events are triggered when the earth is dragged.
The change event is triggered when the earth rotates or zooms.
The update event is triggered permanently, each animation frame.
The earth-container class is added to the container element if it is not present. You can set this class in your container elements HTML so that the earth consumes space even before the earth is initialized.
As soon as the earth is ready, the class earth-ready is added.
earth-show-fallback is added if JavaScript is enabled but the earth is not supported. See Earth.isSupported.
Child elements with the class earth-fallback are set to hidden if the earth is supported.
earth-clickable is added while hovering over a clickable hotspot.
earth-draggable is added while hovering over a draggable earth.
earth-dragging is added to the html element as long as an earth is dragged.