diff --git a/.vitepress/config.mts b/.vitepress/config.mts index f90e729..ffc5fef 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -63,7 +63,7 @@ export default defineConfig({ items: [ { text: "Downloads", link: "/basemaps/downloads" }, { text: "Basemap Layers", link: "/basemaps/layers" }, - { text: "Basemap Styles", link: "/basemaps/styles" }, + { text: "Basemap Themes", link: "/basemaps/themes" }, { text: "MapLibre GL", link: "/basemaps/maplibre" }, { text: "Leaflet", link: "/basemaps/leaflet" }, { text: "OpenLayers", link: "/basemaps/openlayers" }, diff --git a/basemaps/maplibre.md b/basemaps/maplibre.md index cf5823a..f99d74b 100644 --- a/basemaps/maplibre.md +++ b/basemaps/maplibre.md @@ -5,20 +5,58 @@ outline: deep # Basemaps for MapLibre +## Assets -The `protomaps-themes-base` NPM module contains basemap layer definitions compatible with OpenStreetMap downloads from Protomaps. +To render a full basemap, you'll need not only a style and a tileset, but also MapLibre [fontstack](https://maplibre.org/maplibre-style-spec/glyphs/) and [spritesheet](https://maplibre.org/maplibre-style-spec/sprite/) assets. + +The assets referenced by the `glyphs` and `sprite` style properties can be downloaded as ZIP files at the [basemaps-assets](http://github.com/protomaps/basemaps-assets) repository, if you need to host them yourself or offline. + +### Fonts + +The `glyphs` key references a URL hosting pre-compiled fontstacks, required for displaying text labels in MapLibre. Fontstacks can be created with the [font-maker](https://github.com/maplibre/font-maker) tool. + +```js +glyphs:'https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf' +``` + +When a style layer defines a `text-font` like `Noto Sans Regular`, this will create requests for a URL like `https://protomaps.github.io/basemaps-assets/fonts/Noto%20Sans%20Regular/0-255.pbf`. + + +You can view a list of available fonts [in the GitHub repository](https://github.com/protomaps/basemaps-assets/tree/main/fonts). + +### Sprites + +The `sprite` key references a URL specific to one of [the default themes](/basemaps/themes): + +```js +sprite: "https://protomaps.github.io/basemaps-assets/sprites/v3/light" +``` + +These are required for townspots, highway shields and point of interest icons. + +## Loading styles as JSON + +Because [MapLibre styles](https://maplibre.org/maplibre-style-spec/) are JSON documents, the simplest way to define a style in your application is with static JSON. You can use the `Get style JSON` feature of [maps.protomaps.com](maps.protomaps.com) to generate static JSON for a specific theme and style package version. + +## Creating styles programatically + +For more control and less code, you can add use the [`protomaps-themes-base`](https://www.npmjs.com/package/protomaps-themes-base) NPM package as a dependency. + +### Using the npm package ```bash npm install protomaps-themes-base ``` + ```js import layers from 'protomaps-themes-base'; ``` ```js style: { - version:8, + version: 8, glyphs:'https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf', + sprite: "https://protomaps.github.io/basemaps-assets/sprites/v3/light", sources: { "protomaps": { type: "vector", @@ -33,15 +71,18 @@ style: { the default export from `protomaps-themes-base` is a function that takes 2 arguments: -* the source name of the basemap. +* the source name of the basemap, like `protomaps` in the `sources` example above. -* the theme, one of `light`, `dark`, `white`, `black`, `grayscale` or `debug`. +* the [theme](/basemaps/themes), one of `light`, `dark`, `white`, `black`, `grayscale`. -## Fonts +### Using a CDN -The fonts referenced by the `glyphs` style key can be downloaded as a ZIP at the [basemaps-assets](http://github.com/protomaps/basemaps-assets) GitHub repository. +Loading the `protomaps-themes-base` package from NPM will define the `protomaps_themes_base` global variable. -Valid font names are: `Noto Sans Regular`, `Noto Sans Medium`, `Noto Sans Italic` - -Prior to version 2.0.0-alpha.3, the Glyphs URL was `https://cdn.protomaps.com/fonts/pbf/{fontstack}/{range}.pbf`. +```html + +``` +```js +layers: protomaps_themes_base.default("protomaps","light") +```` diff --git a/basemaps/styles.md b/basemaps/styles.md deleted file mode 100644 index ba5263a..0000000 --- a/basemaps/styles.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Basemap Styles -outline: deep ---- - -# Basemap Styles - -::: warning -This section is under construction. -::: \ No newline at end of file diff --git a/basemaps/themes.md b/basemaps/themes.md new file mode 100644 index 0000000..729fad3 --- /dev/null +++ b/basemaps/themes.md @@ -0,0 +1,44 @@ +--- +title: Basemap Themes +outline: deep +--- + + + +# Basemap Themes + +These examples use the preferred [MapLibre GL JS](/basemaps/maplibre) library. + +## Default Styles + +### light + +A general-purpose basemap style. + + + +### dark + +A general-purpose basemap style. + + + +### white + +A style for data visualization. + + + +### grayscale + +A style for data visualization. + + + +### black + +A style for data visualization. + + \ No newline at end of file diff --git a/components/MaplibreMap.vue b/components/MaplibreMap.vue index b155efb..a76ac01 100644 --- a/components/MaplibreMap.vue +++ b/components/MaplibreMap.vue @@ -9,10 +9,13 @@ const { isDark } = useData(); const mapRef = ref(null); var map; -const style = () => { +const style = (passedTheme: string) => { + const theme = passedTheme || (isDark.value ? "dark" : "light"); return { version: 8, - glyphs: "https://cdn.protomaps.com/fonts/pbf/{fontstack}/{range}.pbf", + glyphs: + "https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf", + sprite: `https://protomaps.github.io/basemaps-assets/sprites/v3/${theme}`, sources: { protomaps: { type: "vector", @@ -25,14 +28,18 @@ const style = () => { transition: { duration: 0, }, - layers: layers("protomaps", isDark.value ? "dark" : "light"), + layers: layers("protomaps", theme), }; }; +const props = defineProps<{ + theme: string; +}>(); + onMounted(() => { map = new maplibregl.Map({ container: mapRef.value, - style: style(), + style: style(props.theme), cooperativeGestures: true, }); }); diff --git a/guide/getting-started.md b/guide/getting-started.md index e7e605d..9dca09f 100644 --- a/guide/getting-started.md +++ b/guide/getting-started.md @@ -59,5 +59,5 @@ pmtiles extract https://build.protomaps.com/{{ dateNoDashes }}.pmtiles my_area.p ## Next Steps * Upload your tiles to cloud storage: [Cloud Storage](/pmtiles/cloud-storage) -* Change the appearance or theme of the basemap: [Basemap Styles](/basemaps/styles) +* Change the appearance or theme of the basemap: [Basemap Styles](/basemaps/themes) * Bring your own datasets: [Creating PMTiles](/pmtiles/create) diff --git a/package-lock.json b/package-lock.json index 5008d61..f40507a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -7,7 +7,7 @@ "dependencies": { "maplibre-gl": "^3.4.1", "pmtiles": "^2.10.0", - "protomaps-themes-base": "^2.0.0-alpha.0", + "protomaps-themes-base": "3.0.1", "vitepress": "^1.0.0-rc.15" }, "devDependencies": { @@ -1393,9 +1393,10 @@ "integrity": "sha512-TdDRD+/QNdrCGCE7v8340QyuXd4kIWIgapsE2+n/SaGiSSbomYl4TjHlvIoCWRpE7wFt02EpB35VVA2ImcBVqw==" }, "node_modules/protomaps-themes-base": { - "version": "2.0.0-alpha.0", - "resolved": "https://registry.npmjs.org/protomaps-themes-base/-/protomaps-themes-base-2.0.0-alpha.0.tgz", - "integrity": "sha512-/Hqtwu2fVEcyrbimfo0eV6zb1QE+BeOnOBvKlrWRSWM0f745qJ7sBfqFVVoeMu7aFjDSkeW+j+g+spDhPvdGdQ==" + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/protomaps-themes-base/-/protomaps-themes-base-3.0.1.tgz", + "integrity": "sha512-itF0zqLYzEc/fxKdxZyc6D9GFxSnFQi53Hp+vIguuMCrHSveH9ixeRqh8Wv02woM7dRNbbbfOCeHbSWxlCdcxw==", + "license": "BSD-3-Clause" }, "node_modules/quickselect": { "version": "2.0.0", diff --git a/package.json b/package.json index 9821068..8cb3ca5 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,7 @@ "dependencies": { "maplibre-gl": "^3.4.1", "pmtiles": "^2.10.0", - "protomaps-themes-base": "^2.0.0-alpha.0", + "protomaps-themes-base": "3.0.1", "vitepress": "^1.0.0-rc.15" }, "devDependencies": {