Skip to content

Commit f974139

Browse files
PessimistressHarelMusefulthink
authored
Update base map developer guide (#8739)
Co-authored-by: Harel M <harel.mazor@gmail.com> Co-authored-by: Martin Schuhfuss <m.schuhfuss@gmail.com>
1 parent ff75666 commit f974139

File tree

15 files changed

+829
-285
lines changed

15 files changed

+829
-285
lines changed

‎docs/api-reference/google-maps/google-maps-overlay.md

Lines changed: 94 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -2,40 +2,104 @@
22

33
This class implements the [OverlayView](https://developers.google.com/maps/documentation/javascript/reference/overlay-view#OverlayView)/[WebGLOverlayView](https://developers.google.com/maps/documentation/javascript/reference/webgl#WebGLOverlayView) (depending on map rendering type) interface and can be used as any other Google Maps overlay.
44

5-
## Vector/Raster maps
6-
75
As detailed in the [overview](./overview.md), the overlay supports both Vector and Raster Google map rendering. Depending on the Google Map configuration, the correct deck.gl overlay rendering method will be chosen at runtime.
86

9-
## Usage
10-
11-
```js
12-
import {GoogleMapsOverlay as DeckOverlay} from '@deck.gl/google-maps';
13-
import {GeoJsonLayer} from '@deck.gl/layers';
14-
15-
// Create map
16-
const map = new google.maps.Map(document.getElementById('map'), {
17-
center: { lat: 40, lng: -100 },
18-
zoom: 5,
19-
mapId: GOOGLE_MAP_ID // Only required for Vector maps
20-
});
21-
22-
// Create overlay instance
23-
const overlay = new DeckOverlay({
24-
layers: [
25-
new GeoJsonLayer({
26-
...
27-
})
28-
]
29-
});
30-
// Add overlay to map
31-
overlay.setMap(map);
7+
## Example
8+
9+
import Tabs from '@theme/Tabs';
10+
import TabItem from '@theme/TabItem';
11+
12+
<Tabs groupId="language">
13+
<TabItem value="ts" label="TypeScript">
14+
15+
```ts
16+
import {Loader} from '@googlemaps/js-api-loader';
17+
import {GoogleMapsOverlay} from '@deck.gl/google-maps';
18+
import {ScatterplotLayer} from '@deck.gl/layers';
19+
20+
const loader = new Loader({apiKey: '<google_maps_api_key>'});
21+
const googlemaps = await loader.importLibrary('maps');
22+
23+
const map = new googlemaps.Map(document.getElementById('map'), {
24+
center: {lat: 51.47, lng: 0.45},
25+
zoom: 11,
26+
mapId: '<google_map_id>'
27+
});
28+
29+
const overlay = new GoogleMapsOverlay({
30+
layers: [
31+
new ScatterplotLayer({
32+
id: 'deckgl-circle',
33+
data: [
34+
{position: [0.45, 51.47]}
35+
],
36+
getPosition: d => d.position,
37+
getFillColor: [255, 0, 0, 100],
38+
getRadius: 1000
39+
})
40+
]
41+
});
42+
43+
overlay.setMap(map);
44+
```
45+
46+
</TabItem>
47+
<TabItem value="react" label="React">
48+
49+
```tsx
50+
import React, {useMemo, useEffect} from 'react';
51+
import {APIProvider, Map, useMap} from '@vis.gl/react-google-maps';
52+
import {DeckProps} from '@deck.gl/core';
53+
import {ScatterplotLayer} from '@deck.gl/layers';
54+
import {GoogleMapsOverlay} from '@deck.gl/google-maps';
55+
56+
function DeckGLOverlay(props: DeckProps) {
57+
const map = useMap();
58+
const overlay = useMemo(() => new GoogleMapsOverlay(props));
59+
60+
useEffect(() => {
61+
overlay.setMap(map);
62+
return () => overlay.setMap(null);
63+
}, [map])
64+
65+
overlay.setProps(props);
66+
return null;
67+
}
68+
69+
function App() {
70+
const layers = [
71+
new ScatterplotLayer({
72+
id: 'deckgl-circle',
73+
data: [
74+
{position: [0.45, 51.47]}
75+
],
76+
getPosition: d => d.position,
77+
getFillColor: [255, 0, 0, 100],
78+
getRadius: 1000
79+
})
80+
];
81+
82+
return <APIProvider apiKey="<google_maps_api_key>">
83+
<Map
84+
defaultCenter={{lat: 51.47, lng: 0.45}}
85+
defaultZoom={11}
86+
mapId="<google_maps_id>" >
87+
<DeckGLOverlay layers={layers} />
88+
</Map>
89+
</APIProvider>;
90+
}
3291
```
3392

93+
</TabItem>
94+
</Tabs>
3495

3596
## Constructor
3697

37-
```js
38-
const overlay = new GoogleMapsOverlay(props)
98+
```ts
99+
import {GoogleMapsOverlay} from '@deck.gl/google-maps';
100+
import type {GoogleMapsOverlayProps} from '@deck.gl/google-maps';
101+
102+
new GoogleMapsOverlay(props: GoogleMapsOverlayProps);
39103
```
40104

41105
`props` are forwarded to a `Deck` instance. The following [Deck](../core/deck.md) props are supported:
@@ -59,15 +123,15 @@ The constructor additionally accepts the following option:
59123

60124
#### `setMap` {#setmap}
61125

62-
```js
126+
```ts
63127
overlay.setMap(map);
64128
```
65129

66130
Add/remove the overlay from a map. An overlay can be temporarily hidden from a map by calling `setMap(null)`. Removing an overlay does not destroy the WebGL2 context; use `finalize()` if the overlay should be permanently removed.
67131

68132
#### `setProps` {#setprops}
69133

70-
```js
134+
```ts
71135
overlay.setProps(props);
72136
```
73137

@@ -87,12 +151,8 @@ Equivalent of [deck.pickMultipleObjects](../core/deck.md).
87151

88152
#### `finalize` {#finalize}
89153

90-
```js
91-
overlay.finalize();
92-
```
93-
94154
Remove the overlay and release all underlying resources.
95155

96156
##### getCanvas
97157

98-
See [Deck.getCanvas](../core/deck.md#getcanvas). When using `interleaved: true`, returns the base map's `canvas`.
158+
See [Deck.getCanvas](../core/deck.md#getcanvas). When using `interleaved: true`, returns the base map's `canvas`.

‎docs/api-reference/mapbox/mapbox-overlay.md

Lines changed: 65 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -4,130 +4,113 @@
44

55
## Example
66

7-
### Overlaid
7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
89

9-
```js
10-
import {MapboxOverlay} from '@deck.gl/mapbox';
11-
import {ScatterplotLayer} from '@deck.gl/layers';
10+
<Tabs groupId="language">
11+
<TabItem value="ts" label="TypeScript">
1212

13-
const map = new mapboxgl.Map({
14-
center: [-74.5, 40],
15-
zoom: 14,
16-
antialias: true // Improves the rendering quality
17-
});
18-
19-
const overlay = new MapboxOverlay({
20-
interleaved: false,
21-
layers: [
22-
new ScatterplotLayer({
23-
id: 'my-scatterplot',
24-
data: [
25-
{position: [-74.5, 40], size: 100}
26-
],
27-
getPosition: d => d.position,
28-
getRadius: d => d.size,
29-
getFillColor: [255, 0, 0]
30-
})
31-
]
32-
});
33-
34-
map.addControl(overlay);
35-
```
36-
37-
### Interleaved
38-
39-
```js
13+
```ts
4014
import {MapboxOverlay} from '@deck.gl/mapbox';
4115
import {ScatterplotLayer} from '@deck.gl/layers';
16+
import mapboxgl from 'mapbox-gl';
17+
import 'mapbox-gl/dist/mapbox-gl.css';
4218

4319
const map = new mapboxgl.Map({
44-
center: [-74.5, 40],
45-
zoom: 14,
46-
antialias: true // Improves the rendering quality
20+
container: 'map',
21+
style: 'mapbox://styles/mapbox/light-v9',
22+
accessToken: '<mapbox_access_token>',
23+
center: [0.45, 51.47],
24+
zoom: 11
4725
});
4826

49-
const overlay = new MapboxOverlay({
50-
interleaved: true,
51-
layers: [
52-
new ScatterplotLayer({
53-
id: 'my-scatterplot',
54-
data: [
55-
{position: [-74.5, 40], size: 100}
56-
],
57-
getPosition: d => d.position,
58-
getRadius: d => d.size,
59-
getFillColor: [255, 0, 0],
27+
map.once('load', () => {
28+
const deckOverlay = new MapboxOverlay({
29+
interleaved: true,
30+
layers: [
31+
new ScatterplotLayer({
32+
id: 'deckgl-circle',
33+
data: [
34+
{position: [0.45, 51.47]}
35+
],
36+
getPosition: d => d.position,
37+
getFillColor: [255, 0, 0, 100],
38+
getRadius: 1000,
39+
beforeId: 'waterway-label' // In interleaved mode render the layer under map labels
40+
})
41+
]
42+
});
6043

61-
beforeId: 'admin_labels' // Insert before this Mapbox layer
62-
})
63-
]
44+
map.addControl(deckOverlay);
6445
});
65-
66-
map.addControl(overlay);
6746
```
6847

69-
### Using with [react-map-gl](https://visgl.github.io/react-map-gl)
70-
71-
The following code demonstrates how to create a React component from `MapboxOverlay` with `react-map-gl@7.x` and Typescript:
48+
</TabItem>
49+
<TabItem value="react" label="React">
7250

7351
```tsx
52+
import React from 'react';
53+
import {Map, useControl} from 'react-map-gl';
54+
import {MapboxOverlay} from '@deck.gl/mapbox';
55+
import {DeckProps} from '@deck.gl/core';
7456
import {ScatterplotLayer} from '@deck.gl/layers';
75-
import {MapboxOverlay, MapboxOverlayProps} from '@deck.gl/mapbox';
76-
import {useControl} from 'react-map-gl';
57+
import 'mapbox-gl/dist/mapbox-gl.css';
7758

78-
import Map, {NavigationControl} from 'react-map-gl';
79-
80-
function DeckGLOverlay(props: MapboxOverlayProps & {
81-
interleaved?: boolean;
82-
}) {
59+
function DeckGLOverlay(props: DeckProps) {
8360
const overlay = useControl<MapboxOverlay>(() => new MapboxOverlay(props));
8461
overlay.setProps(props);
8562
return null;
8663
}
8764

88-
export default function App() {
89-
const scatterplotLayer = new ScatterplotLayer({
90-
id: 'my-scatterplot',
91-
data: [
92-
{position: [-74.5, 40], size: 100}
93-
],
94-
getPosition: d => d.position,
95-
getRadius: d => d.size,
96-
getFillColor: [255, 0, 0]
97-
});
65+
function App() {
66+
const layers: [
67+
new ScatterplotLayer({
68+
id: 'deckgl-circle',
69+
data: [
70+
{position: [0.45, 51.47]}
71+
],
72+
getPosition: d => d.position,
73+
getFillColor: [255, 0, 0, 100],
74+
getRadius: 1000,
75+
beforeId: 'waterway-label' // In interleaved mode render the layer under map labels
76+
})
77+
];
9878

9979
return (
10080
<Map
10181
initialViewState={{
102-
latitude: 40,
103-
longitude: -74.5,
104-
zoom: 12
82+
longitude: 0.45,
83+
latitude: 51.47,
84+
zoom: 11
10585
}}
10686
mapStyle="mapbox://styles/mapbox/light-v9"
107-
mapboxAccessToken=""
87+
mapboxAccessToken="<mapbox_access_token>"
10888
>
109-
<DeckGLOverlay layers={[scatterplotLayer]} />
110-
<NavigationControl />
89+
<DeckGLOverlay layers={layers} interleaved />
11190
</Map>
11291
);
11392
}
11493
```
11594

11695
See react-map-gl's [useControl](https://visgl.github.io/react-map-gl/docs/api-reference/use-control) hook.
117-
See [using deck.gl with Typescript](https://deck.gl/docs/get-started/using-with-typescript).
96+
97+
</TabItem>
98+
</Tabs>
11899

119100

120101
## Constructor
121102

122-
```js
103+
```ts
123104
import {MapboxOverlay} from '@deck.gl/mapbox';
124-
new MapboxOverlay(props);
105+
import type {MapboxOverlayProps} from '@deck.gl/mapbox';
106+
107+
new MapboxOverlay(props: MapboxOverlayProps);
125108
```
126109

127110
`MapboxOverlay` accepts the same props as the [Deck](../core/deck.md) class, with the following exceptions:
128111

129112
- `views` - multi-view support is limited. There is only one `MapView` that can synchronize with the base map. See the [using with multi-views](#multi-view-usage) section for details.
130-
- `parent` / `canvas` / `gl` - context creation is managed internally.
113+
- `parent` / `canvas` / `device` - context creation is managed internally.
131114
- `viewState` / `initialViewState` - camera state is managed internally.
132115
- `controller` - always disabled (to use Mapbox's interaction handlers).
133116

@@ -141,7 +124,7 @@ When using `interleaved: true`, you may optionally add a `beforeId` prop to a la
141124

142125
##### setProps
143126

144-
```js
127+
```ts
145128
const overlay = new MapboxOverlay({
146129
interleaved: true,
147130
layers: []
@@ -188,7 +171,7 @@ With that said, it is still possible to take advantage of deck's multi-view syst
188171
- To use multiple views, define a `MapView` with the id `“mapbox”`. This view will receive the state that matches the base map at each render.
189172
- If views are provided but the array does not contain this id, then a `MapView({id: 'mapbox'})` will be inserted at the bottom of the stack.
190173

191-
```js
174+
```ts
192175
import {MapboxOverlay} from '@deck.gl/mapbox';
193176
import {Deck, MapView, OrthographicView} from '@deck.gl/core';
194177
import {ScatterplotLayer} from '@deck.gl/layers';

‎docs/api-reference/mapbox/overview.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,6 @@ If you're using deck.gl in a React or Scripting environment, you just want the b
8181

8282
* When using deck.gl's multi-view system, only one of the views can match the base map and receive interaction. See [using MapboxOverlay with multi-views](./mapbox-overlay.md#multi-view-usage) for details.
8383
* When using deck.gl as Mapbox layers or controls, `Deck` only receives a subset of user inputs delegated by `Map`. Therefore, certain interactive callbacks like `onDrag`, `onInteractionStateChange` are not available.
84-
* Mapbox/Maplibre's terrain features are partially supported. When a terrain is used, the camera of deck.gl and the base map should synchronize, however the deck.gl data with z=0 are rendered at the sea level and not aligned with the terrain surface.
84+
* Mapbox/MapLibre's terrain features are partially supported. When a terrain is used, the camera of deck.gl and the base map should synchronize, however the deck.gl data with z=0 are rendered at the sea level and not aligned with the terrain surface.
8585
* Only Mercator projection is supported. Mapbox adaptive projection is not supported as their API doesn't expose the projection used.
8686
* The `position` property in `viewState` has no equivalent in mapbox-gl.

0 commit comments

Comments
 (0)