Skip to content

Commit cbb574e

Browse files
stevemunkstevemunk
committed
DRAFT of new how-to article: Add custom protocols.
1 parent 22aad42 commit cbb574e

File tree

3 files changed

+143
-0
lines changed

3 files changed

+143
-0
lines changed

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

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
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/15/2024
7+
ms.topic: how-to
8+
ms.service: azure-maps
9+
ms.subservice: web-sdk
10+
---
11+
12+
# Add custom protocols
13+
14+
The Azure Maps Web SDK supports custom protocols such as [PMTiles], a unique archive format designed to efficiently store and deliver tiled data. Eabling this protocol in the Azure Maps Web SDK alows the compression of an entire tile dataset into a single file, improving portability. This protocol is particularly suitable for cloud-based storage solutions.
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+
To start, 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+
Then, 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 protocal, hook the data source with specified protocol url schema. This sample leverages the [Overture] building dataset to enrich building data on top of 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 Map Source
55+
56+
PMTiles are added as a map source during the map event. Once added, the specified URL schema is supported and recognized by the Azure Maps Web SDK. In the following sample, the PMTiles URL is added as a `VectorTileSource`.
57+
58+
> [!NOTE]
59+
> Using the `pmtiles://` protocol automatically creates a `minzoom` and `maxzoom` property for the source.
60+
61+
```js
62+
//Add the source to the map.
63+
map.sources.add(
64+
new atlas.source.VectorTileSource("pmtiles", {
65+
type: "vector",
66+
url: `pmtiles://${PMTILES_URL}`,
67+
})
68+
);
69+
```
70+
71+
## Enrich Map with Overture data
72+
73+
Overture had been provided unified, comprehensive [data schema] with different themes. The following sample leverages the building theme's properties (e.g., building type, building height) to demonstrate building extrusion and differentiate building categories on the basemap, rather than just showing building footprints.
74+
75+
```js
76+
//Create a polygon extrusion layer.
77+
layer = new atlas.layer.PolygonExtrusionLayer(
78+
"pmtiles",
79+
"building",
80+
{
81+
sourceLayer: "building",
82+
height: ["get", "height"],
83+
fillOpacity: 0.5,
84+
fillColor: [
85+
"case",
86+
['==', ['get', 'subtype'], 'agricultural'],
87+
"wheat",
88+
['==', ['get', 'subtype'], 'civic'],
89+
"teal",
90+
['==', ['get', 'subtype'], 'commercial'],
91+
"blue",
92+
['==', ['get', 'subtype'], 'education'],
93+
"aqua",
94+
['==', ['get', 'subtype'], 'entertainment'],
95+
"pink",
96+
['==', ['get', 'subtype'], 'industrial'],
97+
"yellow",
98+
['==', ['get', 'subtype'], 'medical'],
99+
"red",
100+
['==', ['get', 'subtype'], 'military'],
101+
"darkgreen",
102+
['==', ['get', 'subtype'], 'outbuilding'],
103+
"white",
104+
['==', ['get', 'subtype'], 'religious'],
105+
"khaki",
106+
['==', ['get', 'subtype'], 'residential'],
107+
"green",
108+
['==', ['get', 'subtype'], 'service'],
109+
"gold",
110+
['==', ['get', 'subtype'], 'transportation'],
111+
"orange",
112+
"grey",
113+
],
114+
filter: ['any', ['==', ['geometry-type'], 'Polygon'], ['==', ['geometry-type'], 'MultiPolygon']]
115+
}
116+
);
117+
```
118+
119+
The following image shows a screenshot displaying the extrusion of buildings by different types near Central Park, New York City.
120+
121+
:::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.":::
122+
123+
For a fully functional sample with source code, see [Azure Maps Samples GitHub Repo].
124+
125+
For more PMTiles samples, see [Azure Maps Samples].
126+
127+
## Next Steps
128+
129+
The following articles are related to custom protocol PMTiles:
130+
131+
> [!div class="nextstepaction"]
132+
> [Create Data Source](create-data-source-web-sdk.md)
133+
134+
> [!div class="nextstepaction"]
135+
> [Data Driven Style Expressions](data-driven-style-expressions-web-sdk.md)
136+
137+
[PMTiles]: https://docs.protomaps.com/pmtiles
138+
[Azure Maps Samples]: https://samples.azuremaps.com/?search=pmtiles
139+
[Azure Maps Samples GitHub Repo]: https://github.com/Azure-Samples/AzureMapsCodeSamples/tree/main/Samples
140+
[data schema]: https://docs.overturemaps.org/schema
141+
[Overture]: https://overturemaps.org

‎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
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)