maplibre-tilepackage-protocol 1.1.0 → 1.2.0

package/README.md

@@ -1,78 +1,143 @@
 # maplibre-tilepackage-protocol
 
-As an ES6 module: `npm add maplibre-tilepackage-protocol`
+Custom MapLibre GL JS protocol for reading Esri `TPKX` (raster) and `VTPK` (vector) TilePackage archives.
 
-```js
-import * as tilePackage from "maplibre-tilepackage-protocol";
-```
+Works with:
+
+- Local files selected via an `<input type="file">` (no server required)
+- Relative or absolute HTTP(S) URLs to remote TilePackages
+
+The protocol streams tiles, glyphs and sprites directly from the archive. For VTPK it synthesizes a ready-to-use MapLibre style (rewriting sources + sprite + glyphs).
 
-## MapLibre GL JS
+## Install
 
-Example of a TPKX/VTPK archive displayed in MapLibre GL JS:
+```bash
+npm add maplibre-tilepackage-protocol
+```
+
+## Import (ESM)
 
 ```js
-import * as tilePackage from "maplibre-tilepackage-protocol";
-let protocol = new tilePackage.Protocol();
-maplibregl.addProtocol("tilepackage",protocol.package);
-var style = {
-"version": 8,
-"sources": {
-    "example_source": {
-        "type": "raster",
-        "url": "tilepackage://https://example.com/example.tpkx",
-    ...
+import {
+  Protocol,
+  FileSource,
+  TilePackage,
+} from "maplibre-tilepackage-protocol";
 ```
 
-## TPKX
+## Quick Start (Remote Raster TPKX)
 
-A TPKX file containes a full tile pyramid and you just treat it as any other raster source.
+```js
+const protocol = new Protocol();
+maplibregl.addProtocol("tilepackage", protocol.package);
+
+const style = {
+  version: 8,
+  sources: {
+    raster: {
+      type: "raster",
+      url: "tilepackage://https://example.com/data/example.tpkx",
+    },
+  },
+  layers: [{ id: "raster", type: "raster", source: "raster" }],
+};
+
+new maplibregl.Map({ container: "map", style });
+```
 
-## VTPK
+Equivalent explicit tiles form:
 
-Primarily flat VTPK files are supported, see below for indexed VTPK files.
+```js
+tiles: ["tilepackage://https://example.com/data/example.tpkx/{z}/{x}/{y}"];
+```
 
-The file also contains everything you need for your map, such as a style with layers, glyphs, and spirits. You can get everything you need using the tilepackage.
+## Local File VTPK
 
 ```js
-async initMap(package){
-    const header = await package.getHeader();
-    if (header.spatialReference == 3857) {
-        const style = await package.getStyle();
-        new maplibregl.Map({
-            container: "map-element",
-            localIdeographFontFamily: false,
-            style: style,
-        });
-    }
+const protocol = new Protocol({ debug: true });
+maplibregl.addProtocol("tilepackage", protocol.package);
+
+async function initFromFile(file) {
+  const pkg = new TilePackage(new FileSource(file)); // coverageCheck defaults ON
+  protocol.add(pkg); // register so sprite/glyph URLs resolve
+  const style = await pkg.getStyle();
+  new maplibregl.Map({ container: "map", style });
 }
+```
+
+On HTTP(S) you can instead point a style source to a relative URL:
 
-const source = String || tilePackage.FileSource;
-const package = new tilePackage.TilePackage(
-        source,
-      );
-initMap(package)
+```js
+url: "tilepackage://./data/archive.vtpk";
 ```
 
-A VTPK file may contain an indexed tile pyramid where some tiles are missing, because of this you should always initialze a vtpk file with:
+## Vector Style Rewriting
+
+`TilePackage#getStyle()` for VTPK replaces any `url` with a `tiles` array (`tilepackage://<key>/{z}/{x}/{y}`), and sets `sprite` & `glyphs` to protocol endpoints. This avoids extra TileJSON requests that fail under `file://`.
+
+## Indexed Pyramids & Overzoom Fallback
+
+Some VTPK archives have variable depth (gaps). Missing higher-zoom tiles are automatically synthesized from a parent using an internal subdivision algorithm when a coverage map (`tilemap/root.json`) is present.
+
+Behavior:
+
+- Parent search ascends until a node with value `1` in the coverage map.
+- The parent vector tile is decoded, features clipped/scaled, and re-encoded to PBF.
+- Generated tiles are cached (`SharedPromiseCache.subdivided`) to avoid repeat work.
+
+Disable subdivision by constructing the package with `coverageCheck:false`:
 
 ```js
-let protocol = new tilePackage.Protocol({
-  errorOnMissingTile: true,
-});
+const pkg = new TilePackage(new FileSource(file), { coverageCheck: false });
 ```
 
-This will make tiles from lower zoom levels remain in view when you zoom into the map. Unfortunatly it is not possible to get the tiles to over scale in the same way as in ArcGIS Pro without modifying the source cache code in Maplibre. https://github.com/maplibre/maplibre-gl-js/issues/5618
+If you prefer MapLibre's default empty tile behavior (no lower-zoom retention) you can set protocol option `errorOnMissingTile:true` to raise errors for missing PBF tiles.
+
+### Caching
+
+Overzoomed tiles are stored in-memory for the session. A simple size-based prune removes half of entries when exceeding `maxCacheEntries * 2`. (Future: LRU + byte-size thresholds.) Subdivision will be skipped entirely if the zoom delta exceeds the hard cap `maxDz` (default `8`).
+
+### Performance Notes
+
+- Large zoom jumps (high `dz`) cost more CPU; consider constraining user zoom range.
+- Subdivision adds latency only on first request; subsequent hits are served from cache.
+- Disable with `coverageCheck:false` for pure flat packages when you do not want synthesis.
+- Tune with `maxDz` (e.g. set `maxDz:4`) to limit deep subdivision while allowing shallow overzoom.
+
+## API Summary
 
-# Acknowledgement
+- `new TilePackage(source, { coverageCheck, maxDz })` – `source` is URL string or `FileSource`. `coverageCheck` defaults to `true` enabling coverage map + overzoom; `maxDz` (default `8`) hard‑caps subdivision depth.
+- `TilePackage#getHeader()` – name, zooms, bounds, tile type.
+- `TilePackage#getStyle()` – raster style (TPKX) or rewritten vector style (VTPK).
+- `TilePackage#getZxy(z,x,y)` – raw tile bytes (PBF or raster image ArrayBuffer).
+- `Protocol.add(pkg)` – register local file-backed packages for glyph/sprite resolution.
+- `Protocol` options: `metadata`, `errorOnMissingTile`, `debug`.
 
-The code for this protocol was based on the PMTiles protocol by Protomaps LLC.
+## Debug Logging
 
-# Sample data
+Enable `debug:true` in `Protocol` for tile fetch + instance events. Coverage ascent & subdivision messages use `[tilepackage coverage]` and `[tilepackage subdivide]` prefixes.
 
-A sample dataset covering Austria can be downloaded from the following link. Note that this file is an indexed VTPK and won't display all tiles correctly without modifying Maplibre.
+## Demo
 
+The `example/` directory demonstrates local file selection, remote/relative URL input, auto-load of a demo archive, and overzoom fallback.
+
+## TPKX Notes
+
+TPKX contains a full raster pyramid; no style synthesis beyond setting a raster source.
+
+## VTPK Notes
+
+Flat and indexed VTPK archives are supported. Indexed packages rely on the overzoom fallback described above for visual continuity.
+
+## Sample Data
+
+Austria indexed VTPK sample:
 https://www.data.gv.at/katalog/de/dataset/basemap-at-verwaltungsgrundkarte-vektor-offline-osterreich#resources
 
-# Supporting my work
+## Acknowledgement
+
+Inspired by concepts from PMTiles protocol (Protomaps LLC).
+
+## Support
 
-If you like my work and would like to support it, please use https://buymeacoffee.com/spatialillusion
+If this project helps you, consider supporting: https://buymeacoffee.com/spatialillusion