mapbox-gl

What is mapbox-gl?

The mapbox-gl npm package is a powerful library for interactive, customizable maps and geospatial data visualization. It leverages WebGL to render maps from vector tiles and allows for dynamic styling and interactivity.

What are mapbox-gl's main functionalities?

Display a Map

This code initializes a basic map using Mapbox GL JS. It sets the map container, style, center coordinates, and zoom level.

const mapboxgl = require('mapbox-gl');
mapboxgl.accessToken = 'your-access-token';
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v11',
  center: [-74.5, 40],
  zoom: 9
});

Add a Marker

This code adds a marker to the map at the specified longitude and latitude coordinates.

const marker = new mapboxgl.Marker()
  .setLngLat([-74.5, 40])
  .addTo(map);

Add a Popup

This code creates a popup with a text message and attaches it to a specific location on the map.

const popup = new mapboxgl.Popup({ offset: 25 })
  .setText('Hello, World!')
  .setLngLat([-74.5, 40])
  .addTo(map);

Draw a Polygon

This code draws a polygon on the map by defining its coordinates and adding it as a layer when the map loads.

const polygon = {
  'type': 'Feature',
  'geometry': {
    'type': 'Polygon',
    'coordinates': [
      [
        [-74.5, 40],
        [-74.5, 41],
        [-73.5, 41],
        [-73.5, 40],
        [-74.5, 40]
      ]
    ]
  }
};
map.on('load', function () {
  map.addLayer({
    'id': 'polygon',
    'type': 'fill',
    'source': {
      'type': 'geojson',
      'data': polygon
    },
    'layout': {},
    'paint': {
      'fill-color': '#088',
      'fill-opacity': 0.8
    }
  });
});

Other packages similar to mapbox-gl

leaflet

Leaflet is a widely used open-source JavaScript library for mobile-friendly interactive maps. It is lightweight and easy to use, but it does not support vector tiles and WebGL rendering natively like mapbox-gl.

openlayers

OpenLayers is a high-performance, feature-rich library for displaying map data in web browsers. It supports a wide range of map types and data sources, including vector tiles, but it can be more complex to set up compared to mapbox-gl.

cesium

Cesium is a JavaScript library for creating 3D globes and 2D maps. It is highly performant and supports WebGL, making it suitable for complex geospatial visualizations. However, it is more focused on 3D rendering compared to mapbox-gl.

README

A WebGL JavaScript interactive maps library that can render Mapbox Vector Tiles.

Using mapbox-gl-js

Include the source via HTML tags:

<script src='https://api.tiles.mapbox.com/mapbox-gl-js/v0.9.0/mapbox-gl.js'></script>
<link href='https://api.tiles.mapbox.com/mapbox-gl-js/v0.9.0/mapbox-gl.css' rel='stylesheet' />

For more information, see the API documentation and examples.

Alternatively, you can npm install mapbox-gl and use it as a bundled dependency with browserify.

Developing mapbox-gl-js

The following tools are required on any platform to develop mapbox-gl-js. Mac users are advised to use Homebrew unless they want to build these packages manually. APT install steps are relevant to Ubuntu Linux users.

• git
  • OSX: brew install git
  • APT: sudo apt-get install git
• node.js
• GNU Make
• imagemagick
  • OSX: brew install imagemagick
  • APT: sudo apt-get install imagemagick

On Linux, libglew-dev is required in order to run rendering tests:

$ sudo apt-get install libglew-dev

To install dependencies and build the source files:

$ npm install

To serve the debug page:

$ npm start &
$ open "http://localhost:9966/debug/?access_token="`echo $MapboxAccessToken`

This assumes you have the MapboxAccessToken environment variable set to a Mapbox API token from https://www.mapbox.com/account/apps/. This command uses mattdesl/budo to watch source files, rebuild the browserify bundle, and trigger LiveReload updates.

Running Tests

There are two test suites associated with Mapbox GL JS

• npm test runs quick unit tests
• npm run test-suite runs slower rendering tests from the mapbox-gl-test-suite repository

Running Benchmarks

The FPS benchmarking page compares the performance of your local copy of GL JS against v0.7.0. Benchmarking configuration is within bench/fps/site.js.

To serve the FPS benchmark page:

$ npm start &
$ open "http://localhost:9966/bench/fps/?access_token="`echo $MapboxAccessToken`

API Documentation

API documentation is written as JSDoc comments and processed with documentationjs. We aim to document all classes and methods, public and private. Mark private classes and methods with @private.

To generate the HTML documentation from JSDoc, run npm run docs. To view the result, run jekyll serve (requires Jekyll).

Releasing

To prepare a release:

• Update CHANGELOG.md
• Update the version number in package.json, README.md, _config.yml, and _config.mb-pages.yml
• Publish the build to the CDN (see below)
• Publish the build to npm (npm publish)
• Merge the mb-pages branch to master

The CI server publishes builds to the Mapbox CDN automatically, but it does not currently support building tags. Therefore, to release a new version, push a branch with a name of the form vX.Y.Z, with version matching package.json. Once the build is successful, delete the branch and replace it with a tag.

Style Reference

Recommended Reading

Learning WebGL

• Greggman's WebGL articles
• WebGL reference card

GL performance

• Debugging and Optimizing WebGL applications
• Graphics Pipeline Performance

Misc

• drawing antialiased lines
• drawing text with signed distance fields
• label placement
• distance fields

Changelog

0.9.0 (Jul 29 2015)

• glyphs URL now normalizes without the /v4/ prefix for mapbox:// urls. Legacy behavior for mapbox://fontstacks is still maintained (#1385)

• Expose geojson-vt options for GeoJSON sources (#1271)

• bearing snaps to "North" within a tolerance of 7 degrees (#1059)

• Now you can directly mutate the minzoom and maxzoom layer properties with map.setLayerZoomRange(layerId, minzoom, maxzoom)

• Exposed mapboxgl.Control, a base class used by all UI controls

• Refactored handlers to be individually included in Map options, or enable/disable them individually at runtime, e.g. map.scrollZoom.disable().

• New feature: Batch operations can now be done at once, improving performance for calling multiple style functions: (#1352)

  style.batch(function(s) {
      s.addLayer({ id: 'first', type: 'symbol', source: 'streets' });
      s.addLayer({ id: 'second', type: 'symbol', source: 'streets' });
      s.addLayer({ id: 'third', type: 'symbol', source: 'terrain' });
      s.setPaintProperty('first', 'text-color', 'black');
      s.setPaintProperty('first', 'text-halo-color', 'white');
  });
  

• Improved documentation

• featuresAt performance improvements by exposing includeGeometry option

• Better label placement along lines (#1283)

• Improvements to round linejoins on semi-transparent lines (mapbox/mapbox-gl-native#1771)

• Round zoom levels for raster tile loading (2a2aec)

• Source#reload cannot be called if source is not loaded (#1198)

• Events bubble to the canvas container for custom overlays (#1301)

• Move handlers are now bound on mousedown and touchstart events

• map.featuresAt() now works across the dateline