WebGL Earth JavaScript API


The fastest way to embed a 3D globe in a webpage with 
an easy to use JavaScript API - mimicking LeafletJS.

WebGL Earth is an open-source virtual globe made with HTML5 and Canvas WebGL technology. It comes with a JavaScript API
 adapting the popular LeafletJS API. If you are familiar with Leaflet mapping library or Google Maps API you can easily start to use WebGL Earth API in your mashups and give your mapping applications third dimension with nice fly animations.

Things like markers, pop-ups, centering and flying to a place on given latitude and longitude or loading your own map layers are all possible. 
The code from Leaflet can be also mixed with WE - you can pass L.LatLng and L.LatLngBounds, etc.

Map layers such as OpenStreetMap, MapBox, Bing, etc. can be easily loaded. Custom geodata, such as GeoTIFF, ECW, MrSID, etc can be easily turned to compatible tiles with MapTiler. With custom tiles the globes can be used even in intranet or offline.

WebGL Earth uses under the hood the great CesiumJS project for the rendering of the data.
Fork me on GitHub
 
To learn how to use WebGL Earth JavaScript API please see a simple example:

The "Hello World"

<!DOCTYPE HTML>
<html>
<head>
<script src="http://www.webglearth.com/api.js"></script>
<script>
  function initialize() {
    var options = { zoom: 3.0, position: [47.19537,8.524404] };
    var earth = new WE.map('earth_div', options); 
  }
</script>
</head>
<body onload="initialize()">
  <h1>WebGL Earth API: Hello World</h1>
  <div id="earth_div" style="width:600px;height:400px;border:1px solid gray; padding:2px;"></div>
</body>
</html>

Try the live examples: examples.webglearth.org

As you see, first you need to load the WebGL Earth API from http://www.webglearth.com/v2/api.js.
You choose an HTML container (the <div> element typically) - to embed the earth to. Finally you call the initialization of the object WE.map('earth_div') from JavaScript - to display the Earth inside of the provided div element.

Please check the other examples of the JavaScript API on the right side of this page. Feel free to copy&paste any of these and start to create something cool! And let us know at the mailing-list

JavaScript API Reference

In this moment the JavaScript API is pretty simple, but it will grow in the future. Review the list of available methods:

 WE.map  It is used to create a globe on page. 
 WE.tileLayer  Used to load and display tilelayer on globe.
 WE.tileLayerJSON  Loads tile layer via TileJSON specification.
 WE.marker  Instantiates a Marker object given a geographical point.
 WE.polygon  For insert custom polygon to globe.

WE.map object

This object can be constructed via WE.map method.
 
Constructor

 Constructor  Description
WE.map(HTMLElementId:String, options?) Creates a map.

Options

 Option  Type  Default  Description
 center  Array  null  Lat, lng center of view.
 zoom  Number  null  Sets zoom.
 altitude Number 7000000 Sets altitude of view in meters.
 atmosphere Boolean false Show the athmosphere. Best used with black background sets by CSS.
 sky Boolean false Show stars.
 minZoom  Number  null  Sets minzoom.
 maxZoom  Number  null  Sets maxzoom.
 dragging  Boolean  true  Allow interaction. 
 tilting Boolean true Allow tilt the view.
 zooming Boolean true Allow zooming.
 scrollWheelZoom  Boolean  true  Sets mouse scroll wheel zoom.
 proxyHost String  Link to proxy map tiles cross-domain (without CORS headers on server)

Methods

 Method  Returns Description
 fitBounds(bounds:array) this Fits map to bounds as: [[minLat,minLong],[maxLat,maxLng]] or Leaflet's latLngBounds object
setView([lat,lng],zoom)  thisSets camera to the given latitude / longitude position. Leaflet's LatLng is supported
setZoom(zoom)  thisSet the zoom level of the Earth in Mercator tiles at given level.
 zoomIn(?)  this Increases the zoom of the map by delta (1 by default).
  zoomOut(?) this Decreases the zoom of the map by delta (1 by default)..
 panTo(center, options?) this Pan to point with animation. Options: duration
  panInsideBounds(bounds:array) this Pan to fit bounds with animation.
 getCenter()  center 
 getZoom()  Number Return the actual zoom level (real number)
 getBounds() bounds Returns bounds of map.
  on(type:string, function(event)) : number? this Registers function to be called when certain event occurs. Passed  argument is standard browser event object  plus latitude and longitude:

 var showInfo = function(e) {
   alert(e.latitude + ', ' + e.longitude);
   alert('at ' + e.screenX + ', ' + e.screenY);

 }
 earth.on('click', showInfo);

 This function returns the listen key which can be used to unregister the  listener.
 setTilt() this Sets camera tilt (in degrees); 0 - Looking down, 90 - Along the horizon,  180 - Up
 getTilt()  Number Gets camera tilt
 setRoll(number)  this Sets camera roll (in degrees)
 getRoll()  Number Gets camera roll
 setAltitude()  this Sets camera altitude to given value (in meters).
 setHeading()  this Sets camera heading (in degrees); 0 - North, 90 - West, 180 - South, ...

WE.tileLayer object

This object can be constructed via WE.tileLayer

Example

var options = { bounds: [[35.98245136, -112.26379395],[36.13343831, -112.10998535]], 
                minZoom: 10,
                maxZoom: 16 };
var grandcanyon = WE.tileLayer('http://tileserver.maptiler.com/grandcanyon/{z}/{x}/{y}.png',                       options); 
grandcanyon.addTo(earth);
 

Constructor

 Constructor  Description
WE.tileLayer(urlTemplate:string, options?) Creates a tile layer.


Options

 Option  Type  Default  Description
 subdomains  String  'abc'  Subdomain's prefixes of the service.
 bounds  Array  null  When this option is set, the TileLayer only loads tiles that are in the  given bounds.
 minZoom  Number  0  Minimum zoom level.    
 maxZoom  Number  18  Maximum zoom level.
 tileSize  Number  256  Size of tile in pixels.
 tms  Boolean  false  True for inverses Y axes.
 attribution  String  null  Sets opacity of this map. (1 - Fully opaque, 0 - Fully transparent)
 opacity  Number  1.0  The opacity of layer.

Methods

 Method  Returns  Description
 addTo(map:Map)  this  Add layer to map.
 setOpacity(Number)  this  Changes the opacity of the tile layer.


WE.tileLayerJSON object

This object can be constructed via WE.tileLayerJSON() 

Example

var json = {"profile":"mercator",
            "name":"Grand Canyon USGS",
            "format":"png",
            "bounds": -112.26379395,35.98245136,-112.10998535,36.13343831],
            "minzoom":10,
            "version":"1.0.0",
            "maxzoom":16,
            "center":[-112.18688965,36.057944835,13],
            "type":"overlay",
            "description":"",
            "basename":"grandcanyon",
            "tilejson":"2.0.0",
            "sheme":"xyz",
            "tiles":["http://tileserver.maptiler.com/grandcanyon/{z}/{x}/{y}.png"]};

var overlay = API.tileLayerJSON(json);

Or simply:
        
var swiss = WE.tileLayerJSON('http://tileserver.maptiler.com/swissimage25m.json'); 


Constructor

 Constructor  Description
WE.tileLayerJSON(TileJSON:object, options?) Creates a tile layer from TileJSON.


Methods

 Method  Returns  Description
 addTo(map:Map)  this  Adds layer to map.

Options

 Option  Type  Default  Description
 url  String  null  Url template.
 bounds  Array  undefined  When this option is set, the TileLayer only loads tiles that are in the  given bounds.
 minZoom  Number  0  Minimum zoom level.    
 maxZoom  Number  18  Maximum zoom level.
 attribution  String  null  Sets opacity of this map. (1 - Fully opaque, 0 - Fully transparent)

WE.marker object

This object can be constructed via WE.marker() method.

Example

var marker = WE.marker([51.5, -0.1]).addTo(earth)
marker.bindPopup('<b>Hello world!</b>');


Constructor

 Constructor  Description
WE.marker(position:array) Creates a simple marker.

Methods

 Method  Returns  Description
 addTo(map:Map)  this  Add marker to map.
 setLatLng(lat:number, lng:number)  this  Sets new position for the marker.
 bindPopup(content:string, maxWidth:number?, closeBtn:boolean?)  this  Creates new popup attached to this marker with HTML code specified in content. You can also set different maxWidth (default is 300px) and disable close button by passing false as the third argument.
 openPopup()  this      Open popup.
 closePopup()  this  Close popup.

WE.polygon object

This object can be constructed via WE.polygon() method.

Example

var options = {color: '#ff0', opacity: 1, fillColor: '#f00', fillOpacity: 0.1, weight: 2};
var polygonB = WE.polygon([[50, 3], [51, 2.5], [50.5, 4.5]], options).addTo(earth);


Constructor

 Constructor  Description
WE.polygon(position:array, options?) Creates a simple polygon.

Options

 Option  Type  Default  Description
 editable  Boolean  false  Defines if is polygon editable.
 color  String  '#03f'  Sets color of polygon's boundary.
 opacity  Number  0.5  Sets opacity of polygon.   
 fillColor  String  '#03f'  Sets color of polygon's fill.
 fillOpacity  Number  0.2  Sets opacity of polygon's fill. (1 - Fully opaque, 0 - Fully ransparent)
 weight  Number  5  Weight of boundary.

Methods

 Method  Returns  Description
 addTo(map:Map)  this  Add polygon to map.
Comments