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.8.0/mapbox-gl.js'></script>
<link href='https://api.tiles.mapbox.com/mapbox-gl-js/v0.8.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: apt-get install git
• node.js
• GNU Make
• imagemagick
  • OSX: brew install imagemagick
  • APT: apt-get install imagemagik

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).

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.8.1 (Jun 16 2015)

• No code changes; released only to correct a build issue in 0.8.0.