Add basemaps JS examples (#358)

* add basemaps JS usage examples with OpenStreetMap and Overture Maps datasets
protomaps · Jan 14, 2025 · a7190fa · a7190fa
1 parent 02cd8aa
commit a7190fa
Show file tree

Hide file tree

Showing 5 changed files with 180 additions and 1 deletion.
diff --git a/.github/workflows/app.yml b/.github/workflows/app.yml
@@ -28,6 +28,7 @@ jobs:
         run: npx typedoc src/index.ts --out ../app/dist/typedoc
         working-directory: styles
       - run: python .github/check_examples.py
+      - run: mkdir app/dist/examples && cp examples/*.html app/dist/examples/
       - uses: peaceiris/actions-gh-pages@v3
         if: ${{ github.ref == 'refs/heads/main' }}
         with:

diff --git a/README.md b/README.md
@@ -1,7 +1,16 @@
 # Protomaps Basemaps
 
-This repository has two core parts:
+Build a cartographic "basemap" PMTiles from OpenStreetMap + other datasources, plus MapLibre styles for displaying them in a browser.
 
+To get started, check out some basic examples:
+
+* [display markers on a map](https://maps.protomaps.com/examples/basic.html)
+* [change the map theme and language](https://maps.protomaps.com/examples/theme_language.html)
+* [sandwich data between map layers](https://maps.protomaps.com/examples/data_sandwich.html)
+
+This repository is organized into parts:
+
+* `app`: A single-page app, [maps.protomaps.com](maps.protomaps.com) for viewing and downloading basemap builds.
 * `tiles/`: A [Planetiler](https://github.com/onthegomap/planetiler) build profile that generates `planet.pmtiles` from OpenStreetMap and Natural Earth in 2-3 hours on a modest computer.
 * `styles/`: A TypeScript package that generates [MapLibre GL](http://github.com/maplibre) styles, in multiple color themes, that can be used via `npm` or exported as JSON.
 

diff --git a/examples/basic.html b/examples/basic.html
@@ -0,0 +1,49 @@
+<html>
+    <head>
+        <title>Protomaps Basemaps Example</title>
+        <meta charset="utf-8"/>
+        <link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/maplibre-gl.css" crossorigin="anonymous">
+        <script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js" crossorigin="anonymous"></script>
+        <script src="https://unpkg.com/[email protected]/dist/pmtiles.js"></script>
+        <script src="https://unpkg.com/[email protected]/dist/protomaps-themes-base.js"></script>
+        <style>
+            body {
+                margin: 0;
+            }
+            #map {
+                height:100%; width:100%;
+            }
+        </style>
+    </head>
+    <body>
+        <div id="map"></div>
+        <script type="text/javascript">
+            let protocol = new pmtiles.Protocol();
+            maplibregl.addProtocol("pmtiles", protocol.tile);
+
+            const map = new maplibregl.Map({
+              container: "map",
+              zoom: 13,
+              center: [-0.12,51.5],
+              style: {
+                version: 8,
+                glyphs: "https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf",
+                sprite: `https://protomaps.github.io/basemaps-assets/sprites/v4/light`,
+                sources: {
+                  example_source: {
+                    type: "vector",
+                    url: "pmtiles://https://demo-bucket.protomaps.com/v4.pmtiles",
+                    attribution: "<a href='https://openstreetmap.org/copyright'>© OpenStreetMap Contributors</a>"
+                  },
+                },
+                layers: protomaps_themes_base.default("example_source", "light", "en")
+              },
+            });
+
+            let marker = new maplibregl.Marker()
+            .setLngLat([-0.12,51.5])
+            .setPopup(new maplibregl.Popup().setHTML("<h1>Hello World!</h1>"))
+            .addTo(map);
+        </script>
+    </body>
+</html>
diff --git a/examples/data_sandwich.html b/examples/data_sandwich.html
@@ -0,0 +1,76 @@
+<html>
+    <head>
+        <title>Protomaps Basemaps Example</title>
+        <meta charset="utf-8"/>
+        <link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/maplibre-gl.css" crossorigin="anonymous">
+        <script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js" crossorigin="anonymous"></script>
+        <script src="https://unpkg.com/[email protected]/dist/pmtiles.js"></script>
+        <script src="https://unpkg.com/[email protected]/dist/protomaps-themes-base.js"></script>
+        <style>
+            body {
+                margin: 0;
+            }
+            #map {
+                height:100%; width:100%;
+            }
+        </style>
+    </head>
+    <body>
+        <div id="map"></div>
+        <script type="text/javascript">
+            let protocol = new pmtiles.Protocol();
+            maplibregl.addProtocol("pmtiles", protocol.tile);
+
+            const map = new maplibregl.Map({
+              container: "map",
+              zoom: 13,
+              center: [-0.12,51.5],
+              style: {
+                version: 8,
+                glyphs: "https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf",
+                sprite: `https://protomaps.github.io/basemaps-assets/sprites/v4/light`,
+                sources: {
+                  example_source: {
+                    type: "vector",
+                    url: "pmtiles://https://demo-bucket.protomaps.com/v4.pmtiles",
+                    attribution: "<a href='https://openstreetmap.org/copyright'>© OpenStreetMap Contributors</a>"
+                  },
+                  overture_places: {
+                    type: "vector",
+                    url: "pmtiles://https://overturemaps-tiles-us-west-2-beta.s3.amazonaws.com/2024-12-18/places.pmtiles",
+                    attribution: "<a href='https://overturemaps.org'>Overture Maps Foundation</a>"
+                  }
+                },
+                layers: [
+                  ...protomaps_themes_base.noLabels("example_source", "grayscale"),
+                  {
+                    "id": "overture_places",
+                    "source": "overture_places",
+                    "source-layer": "place",
+                    "type": "circle",
+                    "paint": {
+                      "circle-color": "#2525A4",
+                      "circle-opacity": 0.2,
+                      "circle-radius": [
+                        "step",
+                        ["zoom"],
+                        1,
+                        13, 2,
+                        14, 3,
+                        15, 6,
+                        16, 8
+                      ]
+                    }
+                  },
+                  ...protomaps_themes_base.labels("example_source", "grayscale", "en")
+                ]
+              },
+            });
+
+            let marker = new maplibregl.Marker()
+            .setLngLat([-0.12,51.5])
+            .setPopup(new maplibregl.Popup().setHTML("<h1>Hello World!</h1>"))
+            .addTo(map);
+        </script>
+    </body>
+</html>
diff --git a/examples/theme_language.html b/examples/theme_language.html
@@ -0,0 +1,44 @@
+<html>
+    <head>
+        <title>Protomaps Basemaps Example</title>
+        <meta charset="utf-8"/>
+        <link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/maplibre-gl.css" crossorigin="anonymous">
+        <script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js" crossorigin="anonymous"></script>
+        <script src="https://unpkg.com/[email protected]/dist/pmtiles.js"></script>
+        <script src="https://unpkg.com/[email protected]/dist/protomaps-themes-base.js"></script>
+        <style>
+            body {
+                margin: 0;
+            }
+            #map {
+                height:100%; width:100%;
+            }
+        </style>
+    </head>
+    <body>
+        <div id="map"></div>
+        <script type="text/javascript">
+            let protocol = new pmtiles.Protocol();
+            maplibregl.addProtocol("pmtiles", protocol.tile);
+
+            const map = new maplibregl.Map({
+              container: "map",
+              zoom: 13,
+              center: [-0.12,51.5],
+              style: {
+                version: 8,
+                glyphs: "https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf",
+                sprite: `https://protomaps.github.io/basemaps-assets/sprites/v4/light`,
+                sources: {
+                  example_source: {
+                    type: "vector",
+                    url: "pmtiles://https://demo-bucket.protomaps.com/v4.pmtiles",
+                    attribution: "<a href='https://openstreetmap.org/copyright'>© OpenStreetMap Contributors</a>"
+                  },
+                },
+                layers: protomaps_themes_base.default("example_source", "black", "zh-Hant")
+              },
+            });
+        </script>
+    </body>
+</html>