feat(stac): add PMTiles assets to the map

Author: clintonlunn

apps/geolibre-desktop/src/i18n/locales/en.json

@@ -3424,7 +3424,7 @@
     "download": "Download",
     "adding": "Adding {{asset}}…",
     "added": "Added {{asset}} to the map.",
-    "addUnsupported": "Only GeoTIFF/COG and GeoJSON assets can be added to the map",
+    "addUnsupported": "Only GeoTIFF/COG, GeoJSON, and PMTiles assets can be added to the map",
     "addFailed": "Could not add asset",
     "cogUnsupported": "This GeoLibre host cannot visualize remote GeoTIFF assets"
   },

packages/plugins/src/index.ts

@@ -476,6 +476,7 @@ export {
   type StacLabels,
 } from "./plugins/maplibre-stac";
 export {
+  assetFormat,
   connectStac,
   isVisualizableAsset,
   itemBbox,
@@ -492,6 +493,7 @@ export {
   type StacIndexCatalog,
   type StacItem,
   type StacNextPage,
+  type StacAssetFormat,
   type StacSearchOptions,
   type StacSearchResult,
 } from "./plugins/stac-api";

packages/plugins/src/plugins/maplibre-stac.ts

@@ -3,7 +3,9 @@ import { fillLayerId, lineLayerId } from "@geolibre/map";
 import type { FeatureCollection, Geometry } from "geojson";
 import type { GeoJSONSource, MapMouseEvent, Map as MapLibreMap } from "maplibre-gl";
 import type { GeoLibreAppAPI, GeoLibreCogLayerOptions, GeoLibrePlugin } from "../types";
+import { addPMTilesLayerFromUrl } from "./maplibre-components";
 import {
+  assetFormat,
   connectStac,
   horizontalBbox,
   isVisualizableAsset,
@@ -209,7 +211,7 @@ let labels: StacLabels = {
   zoom: "Zoom",
   add: "Add",
   download: "Download",
-  addUnsupported: "Only GeoTIFF/COG and GeoJSON assets can be added to the map",
+  addUnsupported: "Only GeoTIFF/COG, GeoJSON, and PMTiles assets can be added to the map",
   addFailed: "Could not add asset",
   cogUnsupported: "This GeoLibre host cannot visualize remote GeoTIFF assets",
   showing: (count) => `Showing ${count} items.`,
@@ -505,19 +507,36 @@ async function visualizeAsset(
   signal?: AbortSignal,
 ): Promise<void> {
   const name = `${item.id} — ${assetLabel(key, asset)}`;
-  const value = `${asset.type ?? ""} ${asset.href}`.toLowerCase();
-  if (value.includes("geo+json") || /\.geojson($|\?)/i.test(asset.href)) {
-    const response = await fetch(asset.href, {
-      headers: { Accept: "application/geo+json, application/json" },
-      signal,
-    });
-    if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
-    const data = (await response.json()) as FeatureCollection;
-    appRef?.addGeoJsonLayer(name, data, asset.href);
-  } else if (appRef?.addCogLayer) {
-    await appRef.addCogLayer(name, asset.href, cogOptions);
-  } else {
-    throw new Error(labels.cogUnsupported);
+  const format = assetFormat(asset);
+  switch (format) {
+    case "pmtiles": {
+      // The same door the Source Cooperative browser uses, so an archive reaches the map one way.
+      if (appRef) await addPMTilesLayerFromUrl(appRef, asset.href, { fit: false, name });
+      return;
+    }
+    case "geojson": {
+      const response = await fetch(asset.href, {
+        headers: { Accept: "application/geo+json, application/json" },
+        signal,
+      });
+      if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
+      const data = (await response.json()) as FeatureCollection;
+      appRef?.addGeoJsonLayer(name, data, asset.href);
+      return;
+    }
+    case "cog": {
+      if (!appRef?.addCogLayer) throw new Error(labels.cogUnsupported);
+      await appRef.addCogLayer(name, asset.href, cogOptions);
+      return;
+    }
+    case null:
+      throw new Error(labels.addUnsupported);
+    default: {
+      // A format added to VISUALIZABLE_FORMATS with no branch here fails to compile, rather than
+      // falling through to a renderer that cannot read it.
+      const unhandled: never = format;
+      throw new Error(`Unhandled asset format: ${String(unhandled)}`);
+    }
   }
 }
 

packages/plugins/src/plugins/stac-api.ts

@@ -549,12 +549,35 @@ export function itemBbox(item: StacItem): [number, number, number, number] | und
   return horizontalBbox(item.bbox);
 }
 
+/**
+ * The formats the panel can put on the map: a marker within the asset's media type, and the
+ * extension to fall back on when a catalog leaves the type off or writes it as octet-stream.
+ * Tested in order, so a format whose extension another could claim comes first.
+ */
+const VISUALIZABLE_FORMATS = {
+  pmtiles: { mediaType: "pmtiles", extension: /\.pmtiles($|\?)/i },
+  geojson: { mediaType: "geo+json", extension: /\.geojson($|\?)/i },
+  cog: { mediaType: "geotiff", extension: /\.tiff?($|\?)/i },
+} as const;
+
+/** A format {@link assetFormat} recognizes, and {@link visualizeAsset} knows how to add. */
+export type StacAssetFormat = keyof typeof VISUALIZABLE_FORMATS;
+
+/**
+ * Which format an asset is, or null when the panel cannot draw it. The single answer both the
+ * enabled state of Add and the routing behind it read, so the button and the click cannot
+ * disagree about what a catalog is offering.
+ */
+export function assetFormat(asset: StacAsset): StacAssetFormat | null {
+  const mediaType = (asset.type ?? "").toLowerCase();
+  for (const [format, match] of Object.entries(VISUALIZABLE_FORMATS)) {
+    if (mediaType.includes(match.mediaType) || match.extension.test(asset.href)) {
+      return format as StacAssetFormat;
+    }
+  }
+  return null;
+}
+
 export function isVisualizableAsset(asset: StacAsset): boolean {
-  const value = `${asset.type ?? ""} ${asset.href}`.toLowerCase();
-  return (
-    value.includes("geotiff") ||
-    /\.tiff?($|\?)/i.test(asset.href) ||
-    value.includes("geo+json") ||
-    /\.geojson($|\?)/i.test(asset.href)
-  );
+  return assetFormat(asset) !== null;
 }

tests/stac-api.test.ts

@@ -3,6 +3,7 @@ import test from "node:test";
 import {
   browserAssetHref,
   connectStac,
+  assetFormat,
   isVisualizableAsset,
   itemBbox,
   openCatalogNode,
@@ -1139,6 +1140,34 @@ test("a document that never reads leaves the search without a total", async () =
   assert.equal(result.matched, undefined);
 });
 
+test("an asset's format comes from its media type, or its extension when there is none", async () => {
+  // The registered type is what a catalog following the spec sends; the extension covers the
+  // ones that send nothing useful.
+  assert.equal(
+    assetFormat({ href: "https://example.com/a.pmtiles", type: "application/vnd.pmtiles" }),
+    "pmtiles",
+  );
+  assert.equal(assetFormat({ href: "https://example.com/a.PMTILES" }), "pmtiles");
+  assert.equal(assetFormat({ href: "https://example.com/a.pmtiles?token=1" }), "pmtiles");
+  assert.equal(assetFormat({ href: "https://example.com/tiles?id=7&f=pmtiles" }), null);
+  assert.equal(assetFormat({ href: "https://example.com/a.tif", type: "image/tiff" }), "cog");
+  assert.equal(
+    assetFormat({ href: "https://example.com/a.json", type: "application/geo+json" }),
+    "geojson",
+  );
+  assert.equal(assetFormat({ href: "https://example.com/data.bin" }), null);
+
+  // A catalog that stores its archives under a directory named for another format is read by
+  // what the asset is, not by what the path says.
+  assert.equal(assetFormat({ href: "https://example.com/geotiff/a.pmtiles" }), "pmtiles");
+
+  // Which is the same answer that decides whether Add is enabled.
+  assert.equal(
+    isVisualizableAsset({ href: "https://example.com/a.pmtiles", type: "application/vnd.pmtiles" }),
+    true,
+  );
+});
+
 test("asset and bbox helpers recognize common STAC data", () => {
   assert.equal(isVisualizableAsset({ href: "https://example.com/a.TIF?download=1" }), true);
   assert.equal(isVisualizableAsset({ href: "https://example.com/data.bin" }), false);