Skip to content

Commit 919c1de

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #288141 from stevemunk/add-custom-protocol-pmtiles
New Web SDK article: Add custom protocol PMTiles
2 parents 644a949 + 32a3f51 commit 919c1de

File tree

3 files changed

+147
-0
lines changed

3 files changed

+147
-0
lines changed

‎articles/azure-maps/add-custom-protocol-pmtiles.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
title: Add custom protocol PMTiles in the Web SDK | Microsoft Azure Maps
3+
description: Learn how to add custom protocol PMTiles using the Web SDK.
4+
author: sinnypan
5+
ms.author: sipa
6+
ms.date: 10/13/2024
7+
ms.topic: how-to
8+
ms.service: azure-maps
9+
ms.subservice: web-sdk
10+
---
11+
12+
# Add custom protocol PMTiles
13+
14+
The Azure Maps Web SDK supports custom protocols such as [PMTiles]. The `pmtiles://` protocol is used to reference PMTiles archives, which are single-file formats for storing tiled data such as vector and raster maps. This protocol allows Azure Maps to access specific tiles within a PMTiles archive using an HTTP request, fetching only the necessary data on demand.
15+
16+
## Add custom protocol
17+
18+
By using the `addProtocol` function, which registers a callback triggered before any AJAX request made by the library, you can intercept, modify, and return the request for further processing and rendering. This enables the implementation of a custom callback function to load resources when a URL starts with the designated custom schema.
19+
20+
The first step is to add a reference to the protocol. The following example references the `pmtiles` library:
21+
22+
```html
23+
<script src="https://unpkg.com/[email protected]/dist/pmtiles.js"></script>
24+
```
25+
26+
Next, initialize the MapLibre PMTiles protocol.
27+
28+
```js
29+
//Initialize the plugin.
30+
const protocol = new pmtiles.Protocol();
31+
atlas.addProtocol("pmtiles", (request) => {
32+
return new Promise((resolve, reject) => {
33+
const callback = (err, data) => {
34+
if (err) {
35+
reject(err);
36+
} else {
37+
resolve({ data });
38+
}
39+
};
40+
protocol.tile(request, callback);
41+
});
42+
});
43+
```
44+
45+
## Add PMTiles protocol
46+
47+
To add the PMTiles protocol, hook the data source with the specified protocol URL schema. The following sample uses the [Overture] building dataset to add building data over the basemap.
48+
49+
```js
50+
const PMTILES_URL = "https://overturemaps-tiles-us-west-2-beta.s3.amazonaws.com/2024-07-22/buildings.pmtiles";
51+
protocol.add(new pmtiles.PMTiles(PMTILES_URL));
52+
```
53+
54+
## Add PMTiles as a map source
55+
56+
PMTiles are added as a map source during the map event. Once added, the specified URL schema is available to the Azure Maps Web SDK. In the following sample, the PMTiles URL is added as a `VectorTileSource`.
57+
58+
```js
59+
//Add the source to the map.
60+
map.sources.add(
61+
new atlas.source.VectorTileSource("pmtiles", {
62+
type: "vector",
63+
url: `pmtiles://${PMTILES_URL}`,
64+
})
65+
);
66+
```
67+
68+
> [!NOTE]
69+
> Using the `pmtiles://` protocol automatically creates the `minzoom` and `maxzoom` properties for the source.
70+
71+
## Enhance map with Overture data
72+
73+
Overture provides a unified and comprehensive [data schema] designed to organize and structure geospatial data effectively. This schema is divided into different themes, each representing a specific type of geospatial information.
74+
75+
The following sample uses the building theme's properties (for example, building type and height) to demonstrate building extrusion and differentiate between building categories on the basemap, rather than just showing building footprints.
76+
77+
```js
78+
//Create a polygon extrusion layer.
79+
layer = new atlas.layer.PolygonExtrusionLayer(
80+
"pmtiles",
81+
"building",
82+
{
83+
sourceLayer: "building",
84+
height: ["get", "height"],
85+
fillOpacity: 0.5,
86+
fillColor: [
87+
"case",
88+
['==', ['get', 'subtype'], 'agricultural'],
89+
"wheat",
90+
['==', ['get', 'subtype'], 'civic'],
91+
"teal",
92+
['==', ['get', 'subtype'], 'commercial'],
93+
"blue",
94+
['==', ['get', 'subtype'], 'education'],
95+
"aqua",
96+
['==', ['get', 'subtype'], 'entertainment'],
97+
"pink",
98+
['==', ['get', 'subtype'], 'industrial'],
99+
"yellow",
100+
['==', ['get', 'subtype'], 'medical'],
101+
"red",
102+
['==', ['get', 'subtype'], 'military'],
103+
"darkgreen",
104+
['==', ['get', 'subtype'], 'outbuilding'],
105+
"white",
106+
['==', ['get', 'subtype'], 'religious'],
107+
"khaki",
108+
['==', ['get', 'subtype'], 'residential'],
109+
"green",
110+
['==', ['get', 'subtype'], 'service'],
111+
"gold",
112+
['==', ['get', 'subtype'], 'transportation'],
113+
"orange",
114+
"grey",
115+
],
116+
filter: ['any', ['==', ['geometry-type'], 'Polygon'], ['==', ['geometry-type'], 'MultiPolygon']]
117+
}
118+
);
119+
```
120+
121+
The following image shows a screenshot displaying the extrusion of buildings of different types near Central Park in New York City.
122+
123+
:::image type="content" source="media/add-custom-protocol-pmtiles/pmtiles-building.png" lightbox="media/add-custom-protocol-pmtiles/pmtiles-building.png" alt-text="A screenshot demonstrating the custom protocol pmtiles.":::
124+
125+
For a fully functional sample with source code, see [Azure Maps Samples GitHub Repo].
126+
127+
<!--
128+
For more PMTiles samples, see [Azure Maps Samples].
129+
[Azure Maps Samples]: https://samples.azuremaps.com/?search=pmtiles
130+
-->
131+
132+
## Next Steps
133+
134+
The following articles are related to custom protocol PMTiles:
135+
136+
> [!div class="nextstepaction"]
137+
> [Create Data Source](create-data-source-web-sdk.md)
138+
139+
> [!div class="nextstepaction"]
140+
> [Data Driven Style Expressions](data-driven-style-expressions-web-sdk.md)
141+
142+
[Azure Maps Samples GitHub Repo]: https://github.com/Azure-Samples/AzureMapsCodeSamples/blob/main/Samples/PMTiles/Overture%20Building%20Theme/Buildings.html
143+
[data schema]: https://docs.overturemaps.org/schema
144+
[Overture]: https://overturemaps.org
145+
[PMTiles]: https://docs.protomaps.com/pmtiles

‎articles/azure-maps/media/add-custom-protocol-pmtiles/pmtiles-building.png

1.61 MB
Loading

‎articles/azure-maps/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,8 @@ items:
257257
href: clustering-point-data-web-sdk.md
258258
- name: Use data-driven style expressions
259259
href: data-driven-style-expressions-web-sdk.md
260+
- name: Add custom protocol PMTiles
261+
href: add-custom-protocol-pmtiles.md
260262
- name: How to use image templates
261263
href: how-to-use-image-templates-web-sdk.md
262264
- name: Reacting to events

0 commit comments

Comments
 (0)