Skip to content

Commit 1b2fb42

Browse files
veitveit
committed
📝 Add protomaps section
1 parent 3f2424e commit 1b2fb42

File tree

10 files changed

+893
-0
lines changed

10 files changed

+893
-0
lines changed

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ repos:
1212
- id: end-of-file-fixer
1313
- id: check-yaml
1414
- id: check-added-large-files
15+
args: ['--maxkb=2048']
1516
- id: check-json
1617
types: [file] # override `types: [json]`
1718
files: \.(json|ipynb)$

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,3 +132,4 @@ All tutorials serve as seminar documents for our harmonised training courses:
132132
opengl/index
133133
d3js/index
134134
js/index
135+
protomaps/index

‎docs/protomaps/basemap.png‎

641 KB
Loading

‎docs/protomaps/berlin-pmtiles.png‎

1.43 MB
Loading

‎docs/protomaps/berlin.html‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<html>
2+
<head>
3+
<meta charset="utf-8"/>
4+
<meta
5+
http-equiv="Content-Security-Policy"
6+
content="default-src 'self' 'nonce-n0nce' 'nonce-n0nce1'; worker-src blob: ; child-src blob: ; img-src data: blob: ;" />
7+
<link rel="stylesheet" href="maplibre-gl.css">
8+
<script src="maplibre-gl.js"></script>
9+
<script src="pmtiles.js"></script>
10+
<script src="basemaps.js"></script>
11+
</head>
12+
<body>
13+
<div id="map" style="height: 100%; width: 100%"></div>
14+
<script type="text/javascript">
15+
let protocol = new pmtiles.Protocol();
16+
maplibregl.addProtocol("pmtiles", protocol.tile);
17+
maplibregl.setRTLTextPlugin(
18+
"mapbox-gl-rtl-text.min.js",
19+
true,
20+
);
21+
const map = new maplibregl.Map({
22+
container: "map",
23+
zoom: 12,
24+
center: [13.424233,52.534675],
25+
style: {
26+
glyphs: "fonts/{fontstack}/{range}.pbf",
27+
sprite: "sprites/v4/light",
28+
version: 8,
29+
sources: {
30+
protomaps: {
31+
type: "vector",
32+
url: "pmtiles://berlin.pmtiles",
33+
attribution: '© <a href="https://openstreetmap.org">OpenStreetMap</a>'
34+
},
35+
},
36+
layers: basemaps.layers("protomaps", basemaps.namedFlavor("light"), {lang: "en"})
37+
},
38+
});
39+
</script>
40+
</body>
41+
</html>

‎docs/protomaps/cli.rst‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
pmtiles-CLI-Referenz
2+
====================
3+
4+
``pmtiles show``
5+
----------------
6+
7+
:samp:`$ pmtiles show {FILE}.pmtiles`
8+
displays the header information and metadata of a local archive.
9+
:samp:`$ pmtiles show https://maps.cusy.io/map.pmtiles`
10+
displays the header information and metadata of a remote HTTPS archive.
11+
:samp:`$ pmtiles show {FILE}.pmtiles --bucket=s3://{BUCKET}`
12+
displays the header information and metadata of an archive that is located
13+
on an S3-compatible bucket.
14+
:samp:`$ pmtiles show {FILE}.pmtiles --header-json`
15+
outputs a JSON representation of the header.
16+
:samp:`$ pmtiles show {FILE}.pmtiles --metadata`
17+
outputs the JSON metadata.
18+
19+
.. note::
20+
URLs with characters such as ``?`` and ``&`` should be escaped with a
21+
backslash ``\``.
22+
23+
``pmtiles tile``
24+
----------------
25+
26+
:samp:`$ pmtiles tile {FILE}.pmtiles 0 0 0`
27+
outputs the content of a single tile.
28+
29+
``pmtiles verify``
30+
------------------
31+
32+
:samp:`$ pmtiles verify {FILE}.pmtiles`
33+
checks whether an archive is correctly organised and contains correct
34+
header information.
35+
36+
``pmtiles extract``
37+
-------------------
38+
39+
:samp:`$ pmtiles extract`
40+
creates a smaller archive from a larger one, whereby the source archive must
41+
be clustered:
42+
43+
:samp:`$ pmtiles extract {IN}.pmtiles {OUT}.pmtiles --bbox=MIN_LON,MIN_LAT,MAX_LON,MAX_LAT`
44+
You can determine the bounding box with ``MIN_LON``, ``MIN_LAT``,
45+
``AX_LON`` and ``MAX_LAT`` with `bboxfinder.com
46+
<https://bboxfinder.com/>`_, for example.
47+
48+
:samp:`$ pmtiles extract {IN}.pmtiles {OUT}.pmtiles --region={REGION}.geojson`
49+
A GeoJSON ``Polygon``, ``Multipolygon``, ``Feature`` or a
50+
``FeatureCollection`` object can be specified with ``--region``.
51+
52+
:samp:`$ pmtiles extract https://{EXAMPLE.COM}/{IN}.pmtiles {OUT}.pmtiles --maxzoom={MAXZOOM} --download-threads=4`
53+
``--maxzoom`` extracts only a subset of the zoom levels.
54+
55+
``--download-threads`` specifies the number of parallel requests to
56+
speed up the downloads.
57+
58+
:samp:`$ pmtiles extract {IN}.pmtiles {OUT}.pmtiles --maxzoom=MAXZOOM --bucket=s3://{BUCKET}`
59+
60+
Further options are:
61+
62+
``--minzoom``
63+
extracts only part of the pyramid, but this may require many more
64+
requests than the default ``--minzoom=0``. As this removes the overview
65+
zoom levels, it should only be used in certain situations.
66+
67+
``--overfetch``
68+
downloads additional data to bundle small requests: ``0.05`` corresponds
69+
to 5 %.
70+
71+
``pmtiles serve``
72+
-----------------
73+
74+
:samp:`$ pmtiles serve`
75+
is an easy way to serve PMTiles together with `pmtiles.js
76+
<https://www.npmjs.com/package/pmtiles>`_ on the web:
77+
78+
:samp:`$ pmtiles serve {PATH}`
79+
serves a :samp:`{TILESET}.pmtiles` file from the :samp:`{PATH}`
80+
directory at the
81+
:samp:`http://localhost:8080/{TILESET}/{Z}/{X}/{Y}.mvt|png|jpg|webp|avif`,
82+
where the suffix must match the tile type in the archive.
83+
84+
:samp:`$ pmtiles serve . --public-url=localhost`
85+
allows the output of `TileJSON
86+
<https://github.com/mapbox/tilejson-spec/tree/master/3.0.0>`_ under the
87+
URL :samp:`http://localhost:8080/{TILESET}.json`.
88+
89+
``pmtiles convert``
90+
-------------------
91+
92+
:samp:`$ pmtiles convert`
93+
converts an `MBTiles <https://docs.mapbox.com/help/glossary/mbtiles/>`_
94+
archive into PMTiles:
95+
96+
:samp:`$ pmtiles convert {IN}.mbtiles {OUT}.pmtiles`
97+
98+
:samp:`--no-deduplication`
99+
Tile contents should usually be de-duplicated. Use this only if you know
100+
that the input contains only unique tiles and you want to speed up the
101+
conversion.
102+
:samp:`--tmpdir`
103+
allows you to specify the temporary directory.
104+
105+
``pmtiles cluster``
106+
-------------------
107+
108+
:samp:`pmtiles cluster {IN}.pmtiles`
109+
clusters an existing archive, optimising the size and layout. Archives
110+
created with `tippecanoe <https://github.com/felt/tippecanoe>`_, `planetiler
111+
<https://github.com/onthegomap/planetiler>`_ and pmtiles CLI are already
112+
clustered.
113+
114+
:samp:`--no-deduplication`
115+
Tile contents should usually be de-duplicated. Use this only if you know
116+
that the input contains only unique tiles and you want to speed up the
117+
conversion.
118+
119+
``pmtiles upload``
120+
------------------
121+
122+
:samp:`pmtiles upload {IN}.pmtiles {REMOTE}.pmtiles --bucket=s3://{BUCKET}`
123+
uploads an archive to the cloud storage.
124+
125+
``pmtiles edit``
126+
----------------
127+
128+
:samp:`pmtiles edit NAME.pmtiles --header-json={HEADER}.json --metadata={METADATA}.json`
129+
changes parts of the archive header, or replaces the JSON metadata of the
130+
archive. If you only edit the header, the file will be changed in place;
131+
however, writing the JSON metadata requires writing a new copy of the
132+
archive, which then replaces :samp:`NAME.pmtiles`.
133+
134+
.. hint::
135+
You can write the existing header information and metadata to the
136+
:samp:`{HEADER}.json` and :samp:`{METADATA}.json` files with:
137+
138+
:samp:`pmtiles show {NAME}.pmtiles --header-json > {HEADER}.json`
139+
140+
or
141+
142+
:samp:`pmtiles show {NAME}.pmtiles --metadata > {METADATA}.json`
143+
144+
.. hint::
145+
The fields ``tile_type``, ``tile_compresssion``, ``minzoom``,
146+
``maxzoom``, ``bounds`` and ``centre`` of the header can be edited;
147+
however, other fields cannot be edited.
148+
149+
``pmtiles version``
150+
-------------------
151+
152+
:samp:`pmtiles version`
153+
outputs the version from pmtiles.

0 commit comments

Comments
 (0)