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.12.2/mapbox-gl.js'></script>
<link href='https://api.tiles.mapbox.com/mapbox-gl-js/v0.12.2/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 previously released versions. 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`

Writing Documentation

See docs/README.md.

Releasing

To prepare a release:

• Run git checkout master && git merge origin/mb-pages to merge mb-pages into master
• Update CHANGELOG.md with all changes since the last release. A list of commits is available on the GitHub Releases page through a link that says "X commits to master since this release"
• Update the version number in package.json, README.md, bench/fps/site.js, _config.yml, and _config.mb-pages.yml
• Run git commit -m "vX.Y.Z" to commit changes
• Run git tag vX.Y.Z to tag the release
• Run git push origin && git push origin --tags to push the new commit and tag to GitHub
• Create a GitHub release using the tag you just pushed and the text in CHANGELOG.md
• The CI server will automatically publish tagged builds to the Mapbox CDN. Wait for this build to finish successfully before proceeding.
• Run git checkout mb-pages && git merge master && git push origin mb-pages to merge master into mb-pages and publish documentation. Wait for the examples to publish successfully before proceeding (this can take a few minutes).
• Run git checkout master && npm publish to publish the release to npm.

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.12.2 (Dec 22 2015)

API Improvements

• Support LngLat.convert([w, s, e, n]) (#1812)
• Invalid GeoJSON is now handled better

Bugfixes

• Fixed Popup#addTo when the popup is already open (#1811)
• Fixed warping when rotating / zooming really fast
• Map#flyTo now flies across the antimeridan if shorter (#1853)