docs: add example for interleaved deck.gl overlays (#7)

visgl · Sep 26, 2023 · 42a78b8 · 42a78b8
1 parent 335e704
commit 42a78b8
Show file tree

Hide file tree

Showing 7 changed files with 220 additions and 0 deletions.
diff --git a/examples/deckgl-overlay/README.md b/examples/deckgl-overlay/README.md
@@ -0,0 +1,32 @@
+# deck.gl Interleaved Overlay Example
+
+An example demonstrating how an interleaved deck.gl overlay can be added
+to a `<Map>` component. (using the `GoogleMapsOverlay` from [@deck.gl/google-maps][]).
+
+[@deck.gl/google-maps]: https://deck.gl/docs/api-reference/google-maps/overview
+
+## Instructions
+
+Go into the example-directory and run
+
+```shell
+npm install
+```
+
+Then start the example with
+
+```shell
+npm start
+```
+
+Running the examples locally requires a valid API key for the Google Maps Platform.
+See [the official documentation][get-api-key] on how to create and configure your own key.
+
+The API key has to be provided via an environment variable `GOOGLE_MAPS_API_KEY`. This can be done by creating a
+file named `.env` in the example directory with the following content:
+
+```shell title=".env"
+GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
+```
+
+[get-api-key]: https://developers.google.com/maps/documentation/javascript/get-api-key
diff --git a/examples/deckgl-overlay/index.html b/examples/deckgl-overlay/index.html
@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, user-scalable=no" />
+    <title>Example: deck.gl Interleaved Overlay</title>
+
+    <style>
+      body {
+        margin: 0;
+      }
+      #app {
+        width: 100vw;
+        height: 100vh;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module">
+      import {renderToDom} from './src/app';
+      renderToDom(document.querySelector('#app'));
+    </script>
+  </body>
+</html>
diff --git a/examples/deckgl-overlay/package.json b/examples/deckgl-overlay/package.json
@@ -0,0 +1,14 @@
+{
+  "dependencies": {
+    "@vis.gl/react-google-maps": "*",
+    "@deck.gl/google-maps": "^8.9.30",
+    "@deck.gl/layers": "^8.9.30",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "vite": "^4.3.9"
+  },
+  "scripts": {
+    "start": "vite",
+    "build": "vite build"
+  }
+}
diff --git a/examples/deckgl-overlay/src/app.tsx b/examples/deckgl-overlay/src/app.tsx
@@ -0,0 +1,77 @@
+import React, {useEffect, useState} from 'react';
+import {createRoot} from 'react-dom/client';
+
+import {APIProvider, Map} from '@vis.gl/react-google-maps';
+
+import {GeoJsonLayer} from '@deck.gl/layers/typed';
+import {DeckGlOverlay} from './deckgl-overlay';
+
+const DATA_URL =
+  'https://raw.githubusercontent.com/visgl/deck.gl-data/master/website/bart.geo.json';
+
+import type {Feature, GeoJSON} from 'geojson';
+
+const API_KEY = process.env.GOOGLE_MAPS_API_KEY as string;
+
+const App = () => {
+  const [data, setData] = useState<GeoJSON | null>(null);
+
+  useEffect(() => {
+    fetch(DATA_URL)
+      .then(res => res.json())
+      .then(data => setData(data as GeoJSON));
+  }, []);
+
+  return (
+    <APIProvider apiKey={API_KEY}>
+      <Map
+        center={{lat: 37.74, lng: -122.4}}
+        zoom={11}
+        mapId={'4f6dde3310be51d7'}
+        gestureHandling={'greedy'}
+        disableDefaultUI={true}>
+        <DeckGlOverlay layers={getDeckGlLayers(data)} />
+      </Map>
+    </APIProvider>
+  );
+};
+
+function getDeckGlLayers(data: GeoJSON | null) {
+  if (!data) return [];
+
+  return [
+    new GeoJsonLayer({
+      id: 'geojson-layer',
+      data,
+      stroked: false,
+      filled: true,
+      extruded: true,
+      pointType: 'circle',
+      lineWidthScale: 20,
+      lineWidthMinPixels: 4,
+      getFillColor: [160, 160, 180, 200],
+      getLineColor: (f: Feature) => {
+        const hex = f?.properties?.color;
+
+        if (!hex) return [0, 0, 0];
+
+        return hex.match(/[0-9a-f]{2}/g)!.map((x: string) => parseInt(x, 16));
+      },
+      getPointRadius: 200,
+      getLineWidth: 1,
+      getElevation: 30
+    })
+  ];
+}
+
+export default App;
+
+export function renderToDom(container: HTMLElement) {
+  const root = createRoot(container);
+
+  root.render(
+    <React.StrictMode>
+      <App />
+    </React.StrictMode>
+  );
+}
diff --git a/examples/deckgl-overlay/src/control-panel.tsx b/examples/deckgl-overlay/src/control-panel.tsx
@@ -0,0 +1,27 @@
+import * as React from 'react';
+
+function ControlPanel() {
+  return (
+    <div className="control-panel">
+      <h3>deck.gl Interleaved Overlay Example</h3>
+      <p>
+        An example demonstrating how an interleaved deck.gl overlay can be added
+        to a <code>{'<Map>'}</code> component. (using the{' '}
+        <code>GoogleMapsOverlay</code> from{' '}
+        <a href={'https://deck.gl/docs/api-reference/google-maps/overview'}>
+          @deck.gl/google-maps
+        </a>
+        ).
+      </p>
+      <div className="source-link">
+        <a
+          href="https://github.com/visgl/react-google-maps/tree/main/examples/deckgl-overlay"
+          target="_new">
+          View Code ↗
+        </a>
+      </div>
+    </div>
+  );
+}
+
+export default React.memo(ControlPanel);
diff --git a/examples/deckgl-overlay/src/deckgl-overlay.ts b/examples/deckgl-overlay/src/deckgl-overlay.ts
@@ -0,0 +1,31 @@
+import {useMap} from '@vis.gl/react-google-maps';
+import {useEffect, useMemo} from 'react';
+
+import {GoogleMapsOverlay} from '@deck.gl/google-maps/typed';
+
+import type {LayersList} from '@deck.gl/core/typed';
+
+export type DeckglOverlayProps = {layers?: LayersList};
+
+/**
+ * A very simple implementation of a component that renders a list of deck.gl layers
+ * via the GoogleMapsOverlay into the <Map> component containing it.
+ */
+export const DeckGlOverlay = ({layers}: DeckglOverlayProps) => {
+  // the GoogleMapsOverlay can persist throughout the lifetime of the DeckGlOverlay
+  const deck = useMemo(() => new GoogleMapsOverlay({interleaved: true}), []);
+
+  // add the overlay to the map once the map is available
+  const map = useMap();
+  useEffect(() => {
+    deck.setMap(map);
+  }, [map]);
+
+  // whenever the rendered data changes, the layers will be updated
+  useEffect(() => {
+    deck.setProps({layers});
+  }, [layers]);
+
+  // no dom rendered by this component
+  return null;
+};
diff --git a/examples/deckgl-overlay/vite.config.js b/examples/deckgl-overlay/vite.config.js
@@ -0,0 +1,12 @@
+/* @ts-check */
+import {defineConfig, loadEnv} from 'vite';
+
+export default defineConfig(({mode}) => {
+  const {GOOGLE_MAPS_API_KEY} = loadEnv(mode, process.cwd(), '');
+
+  return {
+    define: {
+      'process.env.GOOGLE_MAPS_API_KEY': JSON.stringify(GOOGLE_MAPS_API_KEY)
+    }
+  };
+});