GlobeletJS

Globelet

Lightweight vector maps on a globe

Inspired by Leaflet: a simple, light-weight mapping library, without the distortion of flat maps. Show your GIS data in 3D, as it would appear from space.

See a simple example with geojson data displayed over the Basic Style from OpenMapTiles.

Like Leaflet, we design for simplicity, performance, and usability.

Need lots of features, like 3D buildings? Try CesiumJS. Globelet will only do a few things, but it will do them well.

tests

How to add GlobeletJS code to your webpage

GlobeletJS is provided as an ESM import. Define your script tag as type="module", then import the module:

<script type="module">
  import * as globeletjs from "https://unpkg.com/globeletjs@<VERSION>/dist/globelet.js";

  // Add code to initialize a globe here...
  // ...
</script>

Or if you prefer, you can use the older-style IIFE bundle:

<script src="https://unpkg.com/globeletjs@<VERSION>/dist/globelet-iife.js">

Either bundle will give you a global variable globeletjs, which has an initGlobe method. See the next section for how to use this method.

Make sure to also link to the stylesheet (/dist/globelet.css) in the <head> of your HTML file.

<link 
  rel="stylesheet" 
  type="text/css" 
  href="https://unpkg.com/globeletjs@<VERSION>/dist/globelet.css">

How to initialize a globe

The globeletjs object has an initGlobe method that can initialize a new globe as follows:

const params = {
  container: 'globe',
  style: "./klokantech-basic-style-geojson.json",
  center: [-100, 38.5],
  altitude: 6280,
};

const globePromise = globeletjs.initGlobe(params);

The params object supplied to initGlobe can have the following properties:

The returned Promise resolves to an API handle, which you can use to interact with the globe, as described in the next section.

How to interact with the globe API

The Promise returned by initGlobe resolves to an API object, which you can use to control the globe.

globePromise.then(globeAPI => {
  globeAPI.startAnimation();

  // ...etc. Do more things with globeAPI here...
});

globeAPI exposes the following properties and methods:

How to add and remove markers

A marker can be added to the globe as follows:

const marker = globeAPI.addMarker(options);

where options is an object with the following properties:

The returned marker object has the following properties:

At each animation frame (or each call to globeAPI.update()), GlobeletJS will automatically update screenPos, and use it to set the element’s displayed position via style.left and style.top.

A marker can be removed from the globe as follows:

globeAPI.removeMarker(marker);

Supported map styles

Many features described in the style specification are not yet supported. This is partly by design–GlobeletJS is intended to be an 80/20 map solution, implementing 80% of the specification with 20% as much code as other software. But we are adding support for more features over time.

The map rendering is delegated to the tile-setter module, which is limited by some of its dependencies. See the “un-supported features” list for tile-stencil and the tile-gl TODO list for an (incomplete) list of what is not supported.

We welcome your feedback on what additional features you would like to see supported. Or better yet, try adding them yourself! See the contributing guidelines for how to get started.