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.

Setup

To install dependencies and build the source files:

$ npm install

To serve the debug page:

$ npm start &
$ open http://localhost:3000/debug/?access_token=$MapboxAccessToken

This assumes you have the MapboxAccessToken environment variable set to a Mapbox API token from https://www.mapbox.com/account/apps/. It will watch the source files and automatically rebuild the browserify bundle whenever a change is detected.

Tests are written in tape. Most tests run within nodejs, but a few require a browser environment.

• npm test: local tests run in nodejs - excludes browser tests
• npm run cov: generate test coverage report - excludes browser tests
• npm run test-browser: run all tests locally in a browser

API Documentation

npm run docs: generate API docs

Style Reference

Sprite Generation

./bin/build-sprite.js [outname] [inputdirs]: generate an image sprite by running this script on one or more directories of PNG images.

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.6.0 (Feb 9 2015)

Bugfixes

• Add wrapped padding to sprite for repeating images (#972)
• Clear color buffers before rendering (#966)
• Make line-opacity work with line-image (#970)
• event.toElement fallback for Firefox (#932)
• skip duplicate vertices at ends of lines (#776)
• allow characters outside \w to be used in token
• Clear old tiles when new GeoJSON is loaded (#905)

Improvements

• Added map.setPaintProperty(), map.getPaintProperty(), map.setLayoutProperty(), and map.getLayoutProperty().
• Switch to ESLint and more strict code rules (#957)
• Grab 2x raster tiles if retina (#754)
• Support for mapbox:// style URLs (#875)

Breaking

• Updated to mapbox-gl-style-spec v7.0.0 (Changelog). Styles are now expected to be version 7. You can use the gl-style-migrate utility to update existing styles.
• HTTP_URL and HTTPS_URL config options must no longer include a /v4 path prefix.
• addClass, removeClass, setClasses, hasClass, and getClasses are now methods on Map.
• Style#cascade is now private, pending a public style mutation API (#755).
• The format for featuresAt results changed. Instead of result-per-geometry-cross-layer, each result has a layers array with all layers that contain the feature. This avoids duplication of geometry and properties in the result set.