[kylebarron]

Note

This PR was written by Claude (Claude Code), not by @kylebarron.

Adds examples/experimental/pmtiles-terrain. It computes relief shading on the GPU from Mapterhorn's global terrain, read straight from one PMTiles archive by RasterTileLayer. The archive is planet.pmtiles: 356 GB covering zooms 0-12, as Terrarium-encoded 512 px lossless WebP.

It shows three things:

1. deck.gl-raster reads PMTiles too. Any tiled source works, not only COG and Zarr.
2. Hillshade is computed live on the GPU. The sun is a slider, and moving it fetches nothing.
3. Reads are merged. A clustered PMTiles archive keeps a view's tiles together in the file, so the range reader merges them into a few streamed requests. A "Merge requests" switch compares that with one request per tile.

This becomes the hillshade example. It ports and reviews #647's Horn kernel, halo and modes; #647 stays parked. Ref #647.

The design is in dev-docs/specs/2026-10-27-pmtiles-terrain-design.md and the example's README.

Built on the range reader

It reads PMTiles through @developmentseed/range-reader (#806) and uses #809's protected _abortUnwantedLoads hook, both on main. Outside the example, the PR changes only the spec, one docs entry, the card image and lockfile additions.

How it works

• No loaders.gl. The example uses the pmtiles library directly. @loaders.gl/pmtiles takes only a URL or a Blob, so its reads can't merge; it calls getZxy without a signal; and it pins pmtiles 3.x.
• RangeReaderSource implements pmtiles' Source on the range reader.
  • Tile-data reads use the data purpose; the header and directories use metadata.
  • Bytes are copied out, because the reader's are views into shared buffers.
  • A replaced archive is caught with pmtiles' own etag check.
• PMTilesSource extends RasterSource describes a 512 px WebMercatorQuad grid bounded to the archive.
  • The layer takes its tilesetDescriptor; question 10 of the Sources spec stays as it is.
  • If RasterTileLayer learns to take a source, this plugs in there.
• Halo. Each tile is a 514 x 514 r32float texture whose outer ring comes from its eight neighbors.
  • Nothing is fetched for a halo. A tile loads only itself and draws at once, its ring filled from the neighbors that have loaded.
  • A side whose neighbor hasn't loaded repeats the tile's own edge. That neighbor isn't in view, so neither is the side.
  • When a neighbor loads later, the tile rewrites only its ring, four strips one texel wide.
  • TileBorders keeps each loaded tile's border (8 KiB, not 1 MiB), so a tile still finds a neighbor's border after deck.gl has unloaded the neighbor.
• Ground cell size is computed per fragment from Mercator latitude. One value per tile would make the shading jump 7% between z6 tile rows near 46°N.
• Exact decoding. There's no premultiplied alpha or color conversion. Pixels are read back the way MapLibre reads DEM tiles: through a canvas, or through VideoFrame when canvas reads are altered. Where neither gives exact bytes, tiles fail with a message in the panel instead of drawing wrong elevations.
• PMTilesTerrainLayer exists only to turn on feat(deck.gl-geotiff): coalesce COG tile reads by default #809's protected _abortUnwantedLoads hook, because the example raises maxRequests. It can go once a public prop exists.

Measured

The opening view at the Matterhorn: 12 tiles.

• Each mode was measured cold, two or three times, from a toggle of the switch after the basemap had loaded, in headed Chrome 156.
• Times come from polling the readout, so they're +/- 0.25 s.

Connection	Mode	HTTP requests	Data	All tiles drawn
fast	per tile	14	1.9 MB	1.9 s
fast	merged	7	2.0 MB	1.2-1.9 s
150 ms round trips, 20 Mbit/s	per tile	14	1.9 MB	2.1-2.3 s
150 ms round trips, 20 Mbit/s	merged	7	2.0 MB	1.8-1.9 s

The merged opening view is seven requests:

• one 64 KiB header block;
• one 64 KiB block holding the leaf directory;
• five tile-data requests: 951 KB and 303 KB (one run of eight adjacent tiles, split by the reader's 1 MiB request cap), 305 KB (two tiles), 166 KB and 160 KB.

Mapterhorn serves over HTTP/2, so merging saves more requests than time. Decoding takes about 1.25 ms per tile on the main thread.

Halos without fetches. At first, each tile also fetched its eight neighbors for its halo. Kyle found the example slow, and filling halos only from neighbors that load anyway made it faster:

Measured	Fetching neighbors	Loaded neighbors only
Opening view, merged	4.8 MB	2.0 MB
Opening view, merged, 150 ms round trips	all drawn at 2.9 s	all drawn at 1.8-1.9 s
One-screen pan, fast	13 tiles fetched for 6 shown, 1.57 MB	6 tiles, 0.91 MB, all drawn at 0.6 s
One-screen pan, 150 ms round trips	last tile at 1.27 s	last tile at 0.93 s

Verified

• Tests: the example's 82 tests, typecheck, Biome and vite build. Before the halo change, deck.gl-raster (251) and range-reader (99) also passed on feat(deck.gl-geotiff): coalesce COG tile reads by default #809's head.
• Headed Chrome:
  • All four modes render.
  • Moving the sun or changing the mode fetches nothing.
  • There are no seams at tile edges or between tile rows at z5 (the Himalaya).
  • After the halo change, full-resolution crops across tile edges and a corner show no seams. Every opening view rewrote 29 rings: one per pair of adjacent tiles, counting diagonals, among its 4 x 3 tiles.
  • Tilted to 60° at z12.5 and 65° at z9.6, no seams were visible.
  • Across the antimeridian (Taveuni, Fiji, at z12), the rings read back from the GPU equal the neighbors' edge columns exactly. Hillshade still shows a faint line at 180°, and it comes from the data: there, the step between Mapterhorn's two edge columns is 20-60% of the steps beside it, while at other tile edges it matches them.
  • With canvas noise simulated, decoding switches to the VideoFrame path.
• Headed Firefox 155 with privacy.resistFingerprinting: canvas reads come back random and VideoFrame is undefined. Tiles fail with the panel message; before the fix they drew random stripes.

Review

A fresh reviewer found four Important issues, and I raised two minors to Important. All are fixed, each verified by a failing test or browser check first.

• A drawn tile's halo reads were never cancelled. Fixed then with a signal per halo, released when the tile unloaded. The halo change has since removed those reads.
• A replaced archive could leave pmtiles unable to read it until reload. Fixed by using pmtiles' own etag check.
• Each cached tile kept its 1 MiB halo array alive. luma.gl keeps createTexture's data prop, so the array is now uploaded with writeData. The COG layers do the same: render-pipeline.ts and multi-cog-layer.ts.
• The stats poll rebuilt every tile's sublayers about four times a second while tiles loaded. The readout now polls on its own; tileset setOptions calls during a pan load went from 4 to 0.
• Firefox with fingerprinting resistance drew random stripes as terrain. Tiles now fail, and the panel says why.

Also found in the browser: #647's shader takes atan(0, 0) on flat ground, and the resulting NaN drew lakes black. It's fixed here, but #647 still has it.

Open questions

• Should there be a WebAssembly WebP decoder as a fallback, so Firefox with fingerprinting resistance (and probably Safari private browsing) can draw tiles? It would be a new dependency.
• Should there be an issue for the COG layers keeping createTexture's data?
• pmtiles caches failed directory fetches, so a network blip blanks a region until reload. That's upstream behavior and isn't filed.

Calls made without asking

• Built on feat(deck.gl-geotiff): coalesce COG tile reads by default #809's newest head rather than the head named in the plan. Cost if wrong: one rebase --onto.
• Tests use hand-derived literal values.
• Borders are kept after their tiles unload, up to 2048 (16 MiB). Cost if wrong: memory, or seams where a forgotten neighbor's border is missing.
• Added tests beyond the plan: the counting FetchSource, getUniforms (proven by a mutation), a released tile's refine, and getZxy returning nothing.
• Two comment fixes in Kyle/elevation example #647's small modules: ASCII, and Terrarium units.
• Gave TerrainDerivative explicit uniform and binding types.
• loadTerrariumElevation lives in get-tile-data.ts.
• The experimental badge sits inline in the panel title, because ControlPanel has no experimental prop on this base.
• A refined halo repaints through map.triggerRepaint. Cost if wrong: a refined ring could show a frame late.
• Retuned the colormap ranges so valleys don't look like water: [500, 4500], [2000, 8850], [0, 2800] and [400, 3000].
• The layer allows null tiles, and renderTile draws nothing for them.
• Fixed atan(0, 0) on flat ground.
• Verified in my own headed Chrome over CDP, because the chrome-devtools profile was busy.
• Each opened archive gets its own range reader, so both sides of the switch start cold.
• Timed every pass from a toggle after the basemap loaded. An earlier run timed from page load was confounded by the basemap still loading, so it's excluded.
• Captured a fresh 1800 x 1013 docs card.
• Raised the stats-poll and canvas-fallback minors to Important.
• Superseded by review fixes:
  • warning once and falling back to a distorted canvas;
  • adopting a new validator after one mismatch;
  • simulating the Firefox check in Chrome.
• Left as is:
  • deck.gl's default tile cache size. Cost: hundreds of MiB of GPU memory on large high-DPR screens.
  • Blockiness past z12 wasn't checked. Cost: possibly blocky shading at zooms 13-14.
  • The colormap range follows the chosen place, not the current view. Cost: a poor range after panning far.
  • Borders can survive an archive swap. Cost: a stray seam right after a swap.
  • Safari is untested. Its private browsing would now get the error message.
  • StrictMode opens the archive twice in development.
  • A few unused deck.gl dependencies, copied from titiler-cog.
  • A ring is rewritten once per neighbor that loads after its tile, up to eight times. Cost: four small writeData calls each.
  • Where tiles of two zoom levels meet, the finer tile's neighbor at its own zoom may never load, so that side keeps a repeated edge. The tilted views above stayed at one tile zoom, so I didn't see it happen.
  • Decoding stays on the main thread. Cost: about 15 ms for the 12-tile opening view.

Deferred minors

• The center texel isn't clamped at the tile edge, which could draw a speck there. None was seen.
• performance.measure entries pile up over a session.

🤖 Written by Claude Code

[kylebarron]

don't include the information modal in the screenshot

[kylebarron]

Note

This reply was written by Claude (Claude Code), not by @kylebarron.

Recaptured without the panel in 6738ba1: the same Matterhorn view and size (1800 x 1013), with the panel hidden before the screenshot. The map's attribution stays in the corner, since Mapterhorn's terms ask for it.

🤖 Written by Claude Code

[kylebarron]

overall lgtm