diff --git a/docs/developer-guide/base-maps/using-with-mapbox.md b/docs/developer-guide/base-maps/using-with-mapbox.md index 6e49c28cfe8..46a38102505 100644 --- a/docs/developer-guide/base-maps/using-with-mapbox.md +++ b/docs/developer-guide/base-maps/using-with-mapbox.md @@ -2,14 +2,14 @@ | Pure JS | React | Overlaid | Interleaved | | ----- | ----- | ----- | ----- | -| ✓ | ✓ | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/mapbox) | [example](https://deck.gl/gallery/mapbox-layer) | +| ✓ | ✓ | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/maplibre) | [example](https://deck.gl/gallery/mapbox-layer) | [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) is a powerful open-source map renderer from [Mapbox](https://mapbox.com). deck.gl's `MapView` is designed to sync perfectly with the camera of Mapbox, at every zoom level and rotation angle. When using deck.gl and Mapbox, there are three options you can choose from: - Using the Deck canvas as a overlay on top of the Mapbox map, and Deck as the root element. In this option, deck.gl handles all user input, and holds the source of truth of the camera state. The [React get-started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/react/mapbox/) illustrates the basic pattern. This is the most tested and robust use case, as you can find in all the [examples on this website](https://deck.gl/examples/website). It supports all the features of Deck. -- Using the Deck canvas as a overlay on top of the Mapbox map, and Mapbox as the root element. In this option, mapbox-gl handles all user input, and holds the source of truth of the camera state. The [vanilla JS get-started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/mapbox/) illustrates this pattern. The `MapboxOverlay` class in [@deck.gl/mapbox](../../api-reference/mapbox/overview.md) implements the mapbox-gl control interface to insert deck into the map container. This is favorable if you need to use other mapbox-gl controls and plugins in addition to deck.gl. +- Using the Deck canvas as a overlay on top of the Mapbox map, and Mapbox as the root element. In this option, mapbox-gl handles all user input, and holds the source of truth of the camera state. The [vanilla JS get-started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/maplibre/) illustrates this pattern. The `MapboxOverlay` class in [@deck.gl/mapbox](../../api-reference/mapbox/overview.md) implements the mapbox-gl control interface to insert deck into the map container. This is favorable if you need to use other mapbox-gl controls and plugins in addition to deck.gl. - Using deck.gl layers interleaved with Mapbox layers in the same WebGL2 context, using either the `MapboxOverlay` or `MapboxLayer` from the [@deck.gl/mapbox](../../api-reference/mapbox/overview.md) module. This allows you to mix deck.gl layers with base map layers, e.g. below text labels or occlude each other correctly in 3D. Be cautious that this feature subjects to bugs and limitations of mapbox-gl's custom layer interface. ![deck.gl interleaved with Mapbox layers](https://raw.github.com/visgl/deck.gl-data/master/images/whats-new/mapbox-layers.jpg) diff --git a/docs/get-started/using-with-map.md b/docs/get-started/using-with-map.md index 19cbace7afe..56714586274 100644 --- a/docs/get-started/using-with-map.md +++ b/docs/get-started/using-with-map.md @@ -23,8 +23,8 @@ There are two types of integration between deck.gl and a base map renderer: | [Google Maps JavaScript API](https://developers.google.com/maps/documentation/javascript/deckgl-overlay-view) | ✓ | ✓ | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/google-maps) | [example](https://developers.google.com/maps/documentation/javascript/examples/deckgl-tripslayer) | [link](../developer-guide/base-maps/using-with-google-maps.md) | | [harp.gl](https://www.harp.gl/) | ✓ | | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/harp.gl) | | | | [Leaflet](https://leafletjs.com/) | ✓ | | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/leaflet) | | | -| [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/api/) | ✓ | ✓ | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/mapbox) | [example](https://deck.gl/gallery/mapbox-layer) | [link](../developer-guide/base-maps/using-with-mapbox.md) | -| [MapLibre GL JS](https://maplibre.org/maplibre-gl-js-docs/api/) | ✓ | ✓ | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/mapbox) | [example](https://deck.gl/gallery/mapbox-layer) | [link](../developer-guide/base-maps/using-with-mapbox.md#compatibility-with-mapbox-gl-js-forks) | +| [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/api/) | ✓ | ✓ | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/maplibre) | [example](https://deck.gl/gallery/mapbox-layer) | [link](../developer-guide/base-maps/using-with-mapbox.md) | +| [MapLibre GL JS](https://maplibre.org/maplibre-gl-js-docs/api/) | ✓ | ✓ | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/maplibre) | [example](https://deck.gl/gallery/mapbox-layer) | [link](../developer-guide/base-maps/using-with-mapbox.md#compatibility-with-mapbox-gl-js-forks) | | [OpenLayers](https://openlayers.org/) | ✓ | | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/openlayers) | | | It is also important to understand the difference between the JS library that renders the map and the map data provider. For example, you can use Mapbox GL JS with the Mapbox service, but also with any other service that hosts Mapbox Vector Tiles. When using a base map, be sure to follow the terms and conditions, as well as the attribution requirements of both the JS library and the data provider. diff --git a/docs/whats-new.md b/docs/whats-new.md index 432b2443b19..f9790e5d4f4 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -109,7 +109,7 @@ Due to this generalization, there is a breaking change affecting indexing proper ### MapboxOverlay -The `@deck.gl/mapbox` module now exports a new class [MapboxOverlay](./api-reference/mapbox/mapbox-overlay.md). The class implements Mapbox GL JS's [IControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#icontrol) API. When adding a `MapboxOverlay` control to an mapbox map, deck.gl layers are rendered in synchronization with the base map layers. This control supports both [overlaid and interleaved](./get-started/using-with-map.md) rendering modes. See the new [get started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/mapbox/). +The `@deck.gl/mapbox` module now exports a new class [MapboxOverlay](./api-reference/mapbox/mapbox-overlay.md). The class implements Mapbox GL JS's [IControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#icontrol) API. When adding a `MapboxOverlay` control to an mapbox map, deck.gl layers are rendered in synchronization with the base map layers. This control supports both [overlaid and interleaved](./get-started/using-with-map.md) rendering modes. See the new [get started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/maplibre/). If you are using react-map-gl v7, this is the only solution to use deck.gl with React map control components (`Navigationcontrol`, `GeolocateControl`, etc.). See [example](https://github.com/visgl/react-map-gl/blob/master/examples/deckgl-overlay/src/app.tsx). diff --git a/examples/get-started/pure-js/mapbox/README.md b/examples/get-started/pure-js/maplibre/README.md similarity index 93% rename from examples/get-started/pure-js/mapbox/README.md rename to examples/get-started/pure-js/maplibre/README.md index b4db3a98bd2..9c366dae8c4 100644 --- a/examples/get-started/pure-js/mapbox/README.md +++ b/examples/get-started/pure-js/maplibre/README.md @@ -1,4 +1,4 @@ -## Example: Use deck.gl with Mapbox +## Example: Use deck.gl with Maplibre Uses [Vite](https://vitejs.dev/) to bundle and serve files. diff --git a/examples/get-started/pure-js/mapbox/app.js b/examples/get-started/pure-js/maplibre/app.js similarity index 89% rename from examples/get-started/pure-js/mapbox/app.js rename to examples/get-started/pure-js/maplibre/app.js index 743c6b296b4..57cebd027f9 100644 --- a/examples/get-started/pure-js/mapbox/app.js +++ b/examples/get-started/pure-js/maplibre/app.js @@ -1,12 +1,13 @@ import {MapboxOverlay as DeckOverlay} from '@deck.gl/mapbox'; import {GeoJsonLayer, ArcLayer} from '@deck.gl/layers'; -import mapboxgl from 'mapbox-gl'; +import maplibregl from 'maplibre-gl'; +import 'maplibre-gl/dist/maplibre-gl.css'; // source: Natural Earth http://www.naturalearthdata.com/ via geojson.xyz const AIR_PORTS = 'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_10m_airports.geojson'; -const map = new mapboxgl.Map({ +const map = new maplibregl.Map({ container: 'map', style: 'https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json', center: [0.45, 51.47], @@ -48,4 +49,4 @@ const deckOverlay = new DeckOverlay({ }); map.addControl(deckOverlay); -map.addControl(new mapboxgl.NavigationControl()); +map.addControl(new maplibregl.NavigationControl()); diff --git a/examples/get-started/pure-js/mapbox/index.html b/examples/get-started/pure-js/maplibre/index.html similarity index 100% rename from examples/get-started/pure-js/mapbox/index.html rename to examples/get-started/pure-js/maplibre/index.html diff --git a/examples/get-started/pure-js/mapbox/package.json b/examples/get-started/pure-js/maplibre/package.json similarity index 59% rename from examples/get-started/pure-js/mapbox/package.json rename to examples/get-started/pure-js/maplibre/package.json index b67f112f426..0f052842142 100644 --- a/examples/get-started/pure-js/mapbox/package.json +++ b/examples/get-started/pure-js/maplibre/package.json @@ -1,5 +1,5 @@ { - "name": "deckgl-example-pure-js-mapbox", + "name": "deckgl-example-pure-js-maplibre", "version": "0.0.0", "private": true, "license": "MIT", @@ -9,10 +9,10 @@ "build": "vite build" }, "dependencies": { - "@deck.gl/core": "^9.0.0-beta.2", - "@deck.gl/layers": "^9.0.0-beta.2", - "@deck.gl/mapbox": "^9.0.0-beta.2", - "mapbox-gl": "^1.13.0" + "@deck.gl/core": "^9.0.0-beta", + "@deck.gl/layers": "^9.0.0-beta", + "@deck.gl/mapbox": "^9.0.0-beta", + "maplibre-gl": "^3.0.0" }, "devDependencies": { "vite": "^4.0.0"