pmtiles-swarm 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@
 ### ✨ Features and improvements
 - _...Add new stuff here..._
 
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.63.0
+### ✨ Features and improvements
+- **A terrain archive previews as terrain.** An archive whose `encoding` is `terrarium`,
+  `mapbox`, or `custom` with all four factors present now opens as hillshade with 3D relief
+  rather than as the raster it literally is — a terrain-RGB image drawn as colour says nothing
+  about the ground. The pitch ceiling goes to 85°, since MapLibre's default of 60 is not enough
+  to look across a landscape, and terrain itself is a control rather than a setting, because
+  flat hillshade is easier to compare against a map than a perspective is.
+
+  No server change was needed. The TileJSON has carried `encoding` and the four custom factors
+  for a while, and the preview already fetches it — so this is the page reading what was
+  already there. Stacks preview through the same file, which means a terrain stack gets the
+  view from its own declared output encoding.
+
+  `mlt` is not terrain. It travels in the same field and is a vector format, so the check names
+  the three encodings it can draw rather than testing that an encoding is set.
+
+  The raw tiles stay one click away and the map position survives the switch, because a missing
+  DEM tile hillshades as flat ground rather than as missing — the only way to see a hole is to
+  look at the pixels. A `custom` archive carrying none of its factors is drawn as an ordinary
+  raster with a note saying why.
+
+
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 

package/docs/serving-tiles.md

@@ -748,6 +748,35 @@ first tile can be seconds away.
 **Raster archives get the raster.** There is nothing to inspect in an image, so
 the panel says so and the map is for checking coverage.
 
+**Terrain archives get hillshade and 3D relief**, and open in it. An archive
+whose [`encoding`](tilejson.md#encoding) is `terrarium`, `mapbox`, or `custom`
+with all four factors present is drawn as a `raster-dem` source: a hillshade
+layer over sea-coloured background, terrain switchable from the control beside
+the compass, and the pitch ceiling raised to 85° — MapLibre's default of 60 is
+not enough to see relief, and looking across a landscape rather than down at it
+is the point of the view.
+
+`mlt` is not terrain. It travels in the same `encoding` field and is a vector
+format, which is why the check names the three it can draw rather than testing
+that an encoding is set at all.
+
+Terrain and hillshade get a source each over the same URL, which is what
+MapLibre's own terrain example does and what tileserver-gl ships. The two ask a
+DEM source for different things — one is sampled for height across the whole
+viewport, the other is shaded per tile — and sharing one between them has a
+history of rendering artefacts. The tiles are requested once either way, since
+the HTTP cache answers the second source.
+
+**The raw tiles stay one click away**, from the link in the header, and the map
+position survives the switch. That view is not decorative: a missing DEM tile
+hillshades as flat ground rather than as missing, so the only way to see a hole
+is to look at the pixels. A `custom` archive carrying none of its four factors
+is drawn as an ordinary raster with a note saying why — pixels whose meaning is
+not stated cannot honestly be rendered as heights.
+
+Stacks preview through the same page, so a terrain stack gets the terrain view
+from its own declared output encoding. See [tile stacks](tile-stacks.md).
+
 **What it has actually served** is on the archive's detail, as `served`, and
 across the node at `GET /api/stats` — requests, bytes, a breakdown by zoom and
 status, and which client addresses asked. Worth reading beside `reading`: an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "description": "BitTorrent distribution for PMTiles map archives: create torrents, watch folders, publish and subscribe to RSS feeds, and seed through qBittorrent or an embedded client",
   "type": "module",
   "main": "src/index.js",

package/src/web/preview.html

@@ -36,7 +36,8 @@
       header h1 { font-size: 1rem; margin: 0; }
       header .sub { color: var(--muted); font-size: 0.8rem; }
       header code { font-size: 0.75rem; color: var(--muted); }
-      header a { color: var(--accent); font-size: 0.8rem; margin-left: auto; }
+      header .links { margin-left: auto; display: flex; gap: 0.9rem; }
+      header a { color: var(--accent); font-size: 0.8rem; }
       #map { flex: 1; min-height: 0; }
       .banner {
         margin: auto;
@@ -66,7 +67,10 @@
       <h1 id="name">Loading…</h1>
       <span class="sub" id="summary"></span>
       <code id="endpoint"></code>
-      <a href="/">← console</a>
+      <span class="links">
+        <a id="mode" href="#" hidden></a>
+        <a href="/">← console</a>
+      </span>
     </header>
     <div id="note" hidden></div>
     <div id="map"></div>
@@ -113,6 +117,26 @@
       const vector =
         vectorLayers.length > 0 || /\.(pbf|mvt)(\?|$)/.test(tilejson.tiles?.[0] ?? '');
 
+      // The encodings MapLibre can read as a raster-dem source. Named rather
+      // than tested as "encoding is set", because `mlt` travels in the same
+      // field and is a vector format -- treating it as terrain would render a
+      // hillshade of nothing.
+      const TERRAIN = ['terrarium', 'mapbox', 'custom'];
+      const FACTORS = ['redFactor', 'greenFactor', 'blueFactor', 'baseShift'];
+      // `custom` is unreadable without all four, so an archive that declares it
+      // and carries none is not terrain this page can draw.
+      const terrainReady =
+        !vector &&
+        TERRAIN.includes(tilejson.encoding) &&
+        (tilejson.encoding !== 'custom' ||
+          FACTORS.every((name) => Number.isFinite(tilejson[name])));
+      // Terrain by default where there is terrain: a terrain-RGB archive drawn
+      // as an ordinary raster is a psychedelic mess that says nothing about the
+      // ground. The raw tiles stay one click away, because they are what shows
+      // a hole in the data -- a missing tile reads as flat, not as missing.
+      const raw = new URLSearchParams(location.search).has('raw');
+      const terrain = terrainReady && !raw;
+
       $('name').textContent = tilejson.name ?? tileJsonUrl;
       $('summary').textContent =
         `${vector ? 'vector' : 'raster'} · z${tilejson.minzoom ?? 0}–${tilejson.maxzoom ?? 14}` +
@@ -120,24 +144,104 @@
           ? vectorLayers.length > 0
             ? ` · ${vectorLayers.length} layers`
             : ' · no layer list yet'
-          : '');
+          : terrainReady
+            ? ` · ${tilejson.encoding} terrain`
+            : '');
       $('endpoint').textContent = tilejson.tiles?.[0] ?? '';
 
       // One source, described entirely by the archive's own TileJSON. That
       // endpoint is already a complete, valid source description, so there is
       // nothing to reconstruct here — which is most of the reason it is worth
       // having.
-      const style = {
-        version: 8,
-        sources: { archive: { type: vector ? 'vector' : 'raster', url: tileJsonUrl } },
-        layers: [
-          { id: 'bg', type: 'background', paint: { 'background-color': '#12141a' } },
-        ],
-      };
-      if (!vector) {
+      /**
+       * The archive as a DEM source, described by its own TileJSON.
+       * @returns {object} - A raster-dem source.
+       */
+      const demSource = () => ({
+        type: 'raster-dem',
+        url: tileJsonUrl,
+        encoding: tilejson.encoding,
+        ...(tilejson.encoding === 'custom'
+          ? Object.fromEntries(FACTORS.map((name) => [name, tilejson[name]]))
+          : {}),
+      });
+
+      const style = terrain
+        ? {
+            version: 8,
+            // Two sources over one URL, which is what MapLibre's own terrain
+            // example does and what tileserver-gl ships. Terrain and hillshade
+            // ask a DEM source for different things -- one is sampled for
+            // height across the whole viewport, the other is shaded per tile --
+            // and sharing one source between them has a history of rendering
+            // artefacts. The tiles are requested once either way: the HTTP
+            // cache answers the second source.
+            sources: { terrain: demSource(), hillshade: demSource() },
+            terrain: { source: 'terrain' },
+            layers: [
+              {
+                id: 'bg',
+                type: 'background',
+                // Sea, not page furniture. Where a terrain archive has no data
+                // it is usually because there is water there.
+                paint: { 'background-color': '#16323f' },
+              },
+              {
+                id: 'hillshade',
+                type: 'hillshade',
+                source: 'hillshade',
+                paint: {
+                  'hillshade-shadow-color': 'hsl(39, 21%, 33%)',
+                  'hillshade-illumination-direction': 315,
+                  'hillshade-exaggeration': 0.8,
+                },
+              },
+            ],
+          }
+        : {
+            version: 8,
+            sources: {
+              archive: { type: vector ? 'vector' : 'raster', url: tileJsonUrl },
+            },
+            layers: [
+              {
+                id: 'bg',
+                type: 'background',
+                paint: { 'background-color': '#12141a' },
+              },
+            ],
+          };
+      if (!vector && !terrain) {
         style.layers.push({ id: 'archive', type: 'raster', source: 'archive' });
       }
 
+      // Offered rather than assumed, both ways round. Reading heights off the
+      // raw pixels is the only way to see that a tile is present but wrong.
+      if (terrainReady) {
+        const toggle = $('mode');
+        toggle.hidden = false;
+        toggle.textContent = terrain ? 'raw tiles →' : 'terrain →';
+        toggle.addEventListener('click', (event) => {
+          event.preventDefault();
+          // Assembled at click time so the hash, which is where the map keeps
+          // the position it is currently showing, survives the reload.
+          location.href =
+            location.pathname + (terrain ? '?raw=1' : '') + location.hash;
+        });
+      }
+
+      // An archive that says `custom` and carries none of the four factors
+      // cannot be read as heights by anything, this page included.
+      if (!vector && tilejson.encoding === 'custom' && !terrainReady) {
+        $('note').hidden = false;
+        $('note').textContent =
+          'This archive declares the custom terrain encoding but not the four ' +
+          'factors it is unreadable without — redFactor, greenFactor, ' +
+          'blueFactor and baseShift. It is drawn as an ordinary raster, which ' +
+          'is the only honest thing to do with pixels whose meaning is not ' +
+          'stated.';
+      }
+
       // An archive whose metadata has not been read yet cannot be drawn: a
       // vector style needs `source-layer` names, and nothing in a tile request
       // supplies them. Say so, rather than presenting a black rectangle.
@@ -157,11 +261,28 @@
         center: tilejson.center?.slice(0, 2) ?? [0, 0],
         zoom: tilejson.center?.[2] ?? 2,
         maxZoom: (tilejson.maxzoom ?? 14) + 2,
+        // 60 is the default and it is not enough to see relief: the whole
+        // point of the terrain view is looking across a landscape rather than
+        // down at it.
+        ...(terrain ? { maxPitch: 85 } : {}),
         hash: true,
       });
-      map.addControl(new maplibregl.NavigationControl(), 'top-left');
+      map.addControl(
+        new maplibregl.NavigationControl({ visualizePitch: terrain }),
+        'top-left',
+      );
       map.addControl(new maplibregl.ScaleControl(), 'bottom-left');
 
+      if (terrain) {
+        // Terrain off is a useful view of a DEM in its own right -- hillshade
+        // flat on the screen is easier to compare against a map than a
+        // perspective is -- so this stays a switch rather than being set once.
+        map.addControl(
+          new maplibregl.TerrainControl({ source: 'terrain' }),
+          'top-left',
+        );
+      }
+
       if (vector) {
         // MapLibre's own inspect control, rather than something equivalent
         // written here: it is maintained alongside the renderer, so it keeps