Upstream requests
Feature requests to the libraries and services Terrain Viewer builds on, drafted here before they are posted, with their status and our workaround meanwhile
What we need from projects we depend on, written once, kept here, and linked when posted. Each entry says what we do in the meantime. The community posts and venues are on Advocacy.
Drafted
| Request | To | Status | Our workaround |
|---|---|---|---|
| A browser OAuth client | Planet, the community forum (Data Access and Management APIs) or developer support; no tracker. Checked 2026-10-13: the docs still say interactive client registration is not released, but the Account page's OAuth Clients panel has an SPA option, try it before posting | Dropped 2026-11-13: not to be posted. Drafted 2026-10-07; the self-service route checked 2026-10-15: no OAuth section on the personal account, and a workspace's Access tab says "OAuth client limit reached. Creating OAuth clients is not available for your account", so the post stands | Paste the CLI's access token in Settings |
Withdrawn
- Fumadocs, the page actions under a Next basePath (drafted 2026-10-13): not a Fumadocs bug any more.
withBasePathreadsimport.meta.env.BASE_URL, which Next's Turbopack derives frombasePathsince Next 16.3 (vercel/next.js#96225, merged 2026-07-28, released 2026-08-03). Checked on 2026-10-14 by clicking the stock buttons on a static export built with fumadocs-ui 16.17.3 and Next 16.3.7, in headless Chrome: Copy Markdown fetched/docs/llms.mdx/..., View as Markdown linked it with the base path, the assistant links used the page's full URL. The popover's content is not server-rendered, so theusePathnamepoint never showed either. Our own copy of the popover, written on 2026-08-20 against Next 16.3.0, had become the bug: its pre-prefixed URL doubled to/docs/docs/llms.mdx/...on the Copy Markdown fetch; dropped the same day.
Posted
| Request | To | Status |
|---|---|---|
| A sweep of national sources finer than what is ingested, with the National Datasets comparison as the reference and a licence column | Mapterhorn, a comment on issue 27 | Posted 2026-10-29 |
The protocol registry and useClientDemUpstream (every derived mode on every source type, custom protocols included) as the case for derived modes reading a raster-dem source in core | MapLibre style spec, a comment on issue 1374 (ours, terrain coloured by slope, aspect, curvature) | Posted 2026-11-15. HarelM answered the same day (importScriptInWorkers, the terrain API for custom layers); our reply of 2026-11-19 reports what that gave |
Custom-protocol fetch through the main thread: a DemSource taking a fetch function, the worker optional, linking the 1374 comment | maplibre-contour, a comment on issue 434 (ours) | Posted 2026-11-15. No answer, and no longer needed: contours run in MapLibre's workers since 2026-11-16 |
A screen-space mask (a per-layer clip in viewport units) and difference and exclusion blends, after layer blending shipped in 6.18 | MapLibre GL JS, a reply on issue 48 | Posted 2026-11-15. CommanderStorm answered the same day: clipping is a separate style-spec proposal, more blend modes are welcome as a PR. Our reply of 2026-11-18 offers both PRs; waiting for the answer before opening them |
Plain images (a URL or an ImageBitmap, no info.json) as a resource for the renderer, so the Image Georeferencer's bending fits draw exactly | Allmaps, a comment on issue 643 (level-0 services without tiles; Bert Spaan suggests one tiles entry per size) | Posted 2026-11-15. No separate feature request: Allmaps is built around IIIF, so a synthetic level-0 IIIF service served from memory is our route; nothing more is posted unless the maintainers show interest. Bert Spaan confirmed on 2026-11-16 that Allmaps stays with tiled IIIF images |
https://terrain-viewer.iconem.com as an allowed origin on the Almond Blossom PMTiles host, so the library's impasto entries work without a local proxy | Lars Maxfield (impasto.dev) | Not to be sent yet |
| Sparse tiles and the Esri placeholder tile; 3D Tiles | MapLibre, PR 8335, PR 8567 | Commented |
| MapLibre 6 support and label placement | geogrid-maplibre-gl, issue 18 | Posted |
| A browser option for remote DEMs | geospatial-skills, issue 7 | Posted |
A lightbox and a gallery for prose images (loop, captions, video; a hero plus filmstrip gallery), ours in lightbox.tsx and gallery.tsx (Fumadocs integration) | Fumadocs, issue 3697 | Shipped 2026-10-14 in 16.17.3: a <Lightbox> wrapper over ImageZoom images (arrow keys, swipe, side buttons, counter, caption from title or a caption prop), no loop, no video, no gallery component |
A sidebar title apart from the page title (sidebarTitle, as Docusaurus, Mintlify, Nextra and Starlight have), ours a loader plugin in source.ts | Fumadocs, discussion 307 | Commented 2026-10-13, no separate issue |
WarpedMapLayer with pitch, then terrain and globe (the view step from projected geo to screen is a 2D affine transform; MapLibre's modelViewProjectionMatrix in its place; 8588 for terrain once stable; globe last), with a comment on issue 622 showing the app | Allmaps, issue 666 | Posted 2026-10-14 |
| The launcher's command line handed to the main process (Windows 2.0.2 confirmed, the ntdll workaround, 554 as the Linux twin) | Electrobun, a comment on issue 483 | Commented 2026-10-14 |
A per-variant update feed name, so the full and light builds share one release and release.baseUrl | Electrobun, issue 577 | Posted 2026-10-14 |
| renderToTerrainTile: the plan past experimental (our Phong, Matcap and building-shadow custom layers, the Allmaps draping on 666, three API questions) | MapLibre, a comment on PR 8588 | Commented 2026-10-14 |
Bilinear upsampling past the finest overview level (two pictures, a hosted reproduction); resolved by declaring the source by url with no explicit maxzoom, so the protocol's TileJSON ends the pyramid at the finest level and MapLibre overzooms the last tile (Oscar Fonts' answer) | geomatico/maplibre-cog-protocol, issue 56 | Posted 2026-10-14, answered 2026-10-20 |
A configurable no-data height in the terrain encoder (a value or the tile minimum instead of 0 m); ours is a floor and fill in lib/nodata.ts through our own protocol | geomatico/maplibre-cog-protocol, issue 57 | Posted 2026-10-14 |
| Georeferenced raster input and GeoJSON export, and before/after pair tasks for change detection; ours is TiTiler chips, a frame-name shim and a converter in Change detection frameworks | CVAT, issue 11296 and issue 11297 | Posted 2026-10-13 |
| Georeference fields on the task plus a GeoJSON converter, and synced pan and zoom across images with swipe and flicker | Label Studio, issue 9985 and issue 9986 | Posted 2026-10-15 |
| GeoJSON export applying the GeoTIFF geotransform; tiled rendering of large COGs with a compare image | labelme, a comment on issue 2209 and discussion 2763 | Posted 2026-10-13 and 2026-10-15 |
| A generic change detection mode: pair table, second COG layer with flicker and swipe, configurable classes | GeoLabel, deadtrees-frontend issue 158 | Posted 2026-10-16 |
MapLibre GL JS: a reply on issue 48
Posted 2026-11-15 under birkskyum's mask example on issue 48, after layer blending shipped in 6.18. The draft:
Thanks, the fill sandwich is a neat trick, and thank you @CommanderStorm for landing this. Two notes from Terrain Viewer (terrain-viewer.iconem.com), which compares two imagery dates or two elevation models with a swipe and a blend.
World-space mask vs screen-space mask. The fill gives a mask fixed to the ground. A swipe needs one fixed to the screen: the left half of the viewport, whatever the camera does. It can be approximated by rebuilding the fill's polygon on every
movefromunproject()of the screen rectangle, which holds from about zoom 3 up on a flat map, but breaks once the map is pitched towards the horizon or on the globe, where the screen rectangle does not map to a ground polygon. Since the layer already draws into its own framebuffer, would a screen-space clip be in scope: a per-layer scissor or stencil rectangle in viewport pixels (something likeraster-layer-clip: [x0, y0, x1, y1]in normalized screen units)? It would also make side-by-side and lens comparisons possible inside one map, without a second canvas.A
differencemode. For change detection the useful blend isdifference(andexclusion): what did not change between two dates turns black and what did stands out. With the backdrop already sampled in the composite pass, |backdrop − layer| looks like one more case next tomultiplyandscreen. Would a PR addingdifferenceandexclusion(both W3C separable modes) be welcome?Today we keep two map canvases with CSS
clip-pathandmix-blend-mode, which works but leaves the blend out of the map canvas, so exports have to rebuild it by hand.
The answer and our reply
CommanderStorm, 2026-11-15: clipping needs a style-spec proposal of its own, separate from blending, to be presented at the monthly TSC; more blend modes are welcome as a PR, since only the modes people asked for were stabilised.
Thanks for getting back as always! Agreed that clipping is a separate question from blending. I'll try to wrap up a style-spec proposal for it (screen-space mask or clip region per layer, with the overlay/split-view comparison as the context).
On the extra blend modes, noted that a PR is welcome, to style-spec then gl-js. I have both ready locally with the ten CSS mix-blend modes still missing, split in two commits sorted by usefulness on our side. Would you want me to PR them all?
difference,exclusion,soft-light,hard-light, very usefuldarken,lighten,color-dodge,color-burn,hue,saturationnice to have
Two things follow from it, neither done yet:
- The blend-mode pull requests. Both are written and kept local until CommanderStorm answers: the style-spec one first (the ten values and their documentation), then GL JS (the composite shader and a render test per mode on fill and raster layers).
- A style-spec proposal for clipping: a screen-space mask or clip region per layer, with the overlay split as the case.
Allmaps: plain images as a resource
Answer (2026-11-16): Bert Spaan sees the use and says it would not be hard, but wants Allmaps to keep working with tiled IIIF images only (manifest metadata, image quality, long-lived hosting).
Decision (2026-11-16): Allmaps is built around IIIF, so the route is a synthetic level-0 IIIF service served from memory through the renderer's fetchFn (one tiles entry covering the whole image, as Bert Spaan suggests on 643). No separate feature request; nothing more is posted unless the maintainers show interest in a non-IIIF resource.
Posted 2026-11-15 as a comment on issue 643 (Allmaps rejects a level-0 IIIF service without tiles; Bert Spaan answered that the renderer wants tiles and suggested one tiles entry per size), the closest existing thread: no issue asked for a resource with no IIIF at all (searched 2026-11-15). The comment:
Chiming in with a related use case, from the other end: no IIIF server at all.
Historical-Imagery Image Georeferencer lets user set pair control points to estimate transform of a plain image (jpg, png etc), via @allmaps/transform - thanks for that utility in addition to all the great allmaps work!
MapLibre's image source draws from four corners only, so the bending fits (polynomial 2, thin-plate spline) cannot be shown correctly. On the contrary, Allmaps' renderer already triangulates and warps on the GPU. The renderer accepts a
fetchFn, so a synthetic level-0 IIIF service served from memory is a possible workaround today (with a singletilesentry covering the whole image, as suggested above).A first-class resource type for a single image would avoid the above workaround. This image could be a URL or an
ImageBitmap, width and height known, no tiles, noinfo.json. It would let us hand our control points and transformation toWarpedMapLayer.addGeoreferencedMapand get every fit drawn exactly.
Planet: a browser OAuth client
Insights Platform STAC (api.planet.com/x/data): a way for a browser app to get an access token
The STAC API takes only an OpenID access token; a PLAK API key answers 401 there (it works on the Data API v1 and the tile service). The documentation says the Planet CLI and SDK are the only interactive OAuth clients for now, and that machine-to-machine tokens for api.planet.com are in progress. A web app can therefore only ask users to run planet auth print-access-token and paste the result, every two hours or so. Proposal, either: self-service registration of a public OAuth client (authorization code with PKCE, the app's own redirect URI), or accepting the API key on /x/data as the Data API v1 does. CORS on /x/data is already open, so nothing else is missing. The self-service path is closed for us today: the personal account page has no OAuth section, and a workspace's Access tab shows "OAuth client limit reached. Creating OAuth clients is not available for your account" (checked 2026-10-15).
maplibre-contour: a follow-up on issue 434
Posted 2026-11-15 in two parts: the description of the registry and useClientDemUpstream went to style-spec issue 1374, where it argues for derived modes in core, and the small ask to issue 434, linking it. The combined draft:
Following up with what we ended up doing, in case it helps shape an API.
The problem, recap. Terrain Viewer (terrain-viewer.iconem.com) reads elevation from many kinds of sources, most of them through custom protocols:
cog://,vrt://(a mosaic of national LiDAR tiles),lerc://,demdiff://(the difference of two DEMs),quantized-mesh://, alongside plain Terrain-RGB and Terrarium URLs. A protocol handler registered withaddProtocollives on the main thread, so the contour worker cannot fetch those URLs.What we built: two pieces.
- One registry for every protocol,
lib/protocol-registry.ts:
registerProtocol(scheme, handler)registers the handler with MapLibre and keeps it in a map.fetchTileBitmap(url)dispatches any URL, custom scheme or plain https, to the right handler and returns anImageBitmap.- So anything outside a MapLibre source (contours, export, elevation picker, profiles) can fetch a tile the same way MapLibre does.
- One resolver from any source to a tile template,
useClientDemUpstream(MapSources.tsx):
- It turns any terrain source (built-in, custom URL, COG, VRT, LERC, TileJSON, a difference of two sources) into one template with its encoding and zoom range:
vrt://…,lerc://…,demdiff://…, or the TileJSON's resolved tiles.- Every derived mode (hillshade variants, slope, curvature, sky-view factor, contours) reads that template, so each works on every source type with no per-source code.
How contours use it. The DEM tile is fetched on the main thread through the registry, decoded, and the elevation grid is handed to the contour generation.
What would help from maplibre-contour. The piece needed is small:
- a
DemSourceoption taking a function(z, x, y, abort) => Promise<DemTile>(or a rawFloat32Arraygrid) in place of a URL template;- the worker optional, since the fetch function lives on the main thread.
Happy to send a PR along those lines if that shape works for you.
Follow-up for issue 434 (drafted 2026-11-18, not posted)
HarelM's answer on style-spec 1374 (importScriptInWorkers) made the request above unnecessary. The substance went into the reply on 1374 on 2026-11-19; this shorter reply on issue 434, to say so and leave the recipe for the next reader, is still unposted:
A follow-up, since this turned out not to need anything from maplibre-contour. Following @HarelM's suggestion on maplibre-style-spec#1374, we now run maplibre-contour inside MapLibre's own workers:
importScriptInWorkersloads the UMD build (dist/index.min.js) plus a few lines of our own into the workers, where they register a protocol withself.addProtocol. MapLibre loads vector tiles in its workers, so the isolines and the vector-tile encoding run there.- The protocol handler builds a
LocalDemManagerwith a customgetTile: a plain http(s) tile is fetched in the worker; any custom scheme (vrt://,lerc://, a DEM difference) is asked of the main thread withself.worker.actor.sendAsyncand comes back as a transferredImageBitmap. One gotcha: the message needstargetMapId: "global-dispatcher", or every map's actor answers it.setWorkerCount(4)then traces several tiles at once (MapLibre defaults to one worker on Chrome): ten contour tiles went from 560 to 440 ms, and from 1.5 to 0.9 s over a computed DEM.Code:
contour-worker-client.tsandcontour-worker-body.js. The one thing that would make this lighter is exposingdist/index.min.js(or a worker-ready entry) in the packageexportsmap; we import it by itsnode_modulespath today. Feel free to close our part of this request.
MapLibre style spec: the reply on issue 1374
HarelM, 2026-11-15, on our registry comment: maplibre-contour can reach custom protocols by loading code into the worker and using GL JS's internal makeRequest; importScriptInWorkers helps in some cases; worth trying both with the new terrain API for custom layers, then saying what API is still missing.
Thanks @HarelM, very useful and totally relevant! Some notes after implementing your suggestions over the past few days in Terrain Viewer with Fable:
- Contours in MapLibre's own workers. maplibre-contour now runs inside the worker pool, loaded with
importScriptInWorkers: its UMD build plus a small script that registers a protocol in the workers. DEM tiles from a custom protocol are answered by the main thread. With the pool raised from one worker to up to four, a screenful of contour tiles lands about 30% sooner.- Heavy raster modes in a worker pool. Our heavy raster compute modes, like Sky View Factor, Openness, Local Dominance and Hard Shadows, run in a shared pool of up to four workers. A screenful lands 3 to 4 times sooner and user interactions stay responsive.
- The terrain API for custom layers. Live Phong and Matcap are now drawn through
renderToTerrainTile, removing the need to replicate how MapLibre builds its terrain mesh. Very useful, and also more performant (drawn only when something changes rather than every frame).A potentially easier plugin ergonomics could be a public way for a worker to fetch through the protocols registered with
addProtocol. Inside MapLibre's workers,makeRequestalready falls back to the main thread's handlers, which is what maplibre-contour relies on, but it is internal, and a plugin's own worker pool has no equivalent.Details and measurements: https://terrain-viewer.iconem.com/docs/dev/performance/
The reply ends with a folded note on vector and raster workers, checked against the GL JS source (main, 2026-11-16):
- MapLibre loads vector tiles inside its workers, but requests raster and raster-dem tiles from the main thread (
raster_tile_source.tsandraster_dem_tile_source.tscallImageRequestthere; only the decoded DEM pixels go to a worker). A worker-side protocol therefore only helps vector sources, contours among them. - Raster compute runs in our own pool, which cannot call the internal
makeRequest: the main thread reads and decodes the DEM, then hands the grid to the pool. - Our contour script does not go through
makeRequesteither: it fetches http(s) tiles itself and sends any other scheme to the main thread as a message. In a MapLibre worker,makeRequestwould do that relay by itself (src/util/ajax.ts).
See Performance and Custom protocols.
Mapterhorn: a comment on issue 27
A comment on issue 27 (possible data sources; Wallonia and the Dutch orthophoto WMS were the last two suggestions):
We keep a surveyed list of national elevation endpoints for Terrain Viewer, with the Mapterhorn resolution next to each: https://terrain-viewer.iconem.com/docs/features/national-datasets/. Three countries publish a finer national grid than the one ingested today, all as open services: Czechia (CUZK DMR 5G, 2 m against 5 m), the Netherlands (AHN DTM, 0.5 m against 5 m) and Norway (Kartverket NDH, 0.25 m against 1 m). The page also lists what a browser cannot consume but a pipeline might (Portugal and Sweden have open STAC indexes with the rasters behind auth), the regional sources finer than their national grid (Queensland's 0.5 to 1 m LiDAR mosaic among them), and the licence of each. Every row is a reproduced request, not a catalog entry. Mexico INEGI's 5 m MDE from my earlier comment is still download-only.
Before proposing a source there, check the project's EXCLUDED.md and its licence rule (attribution-only, no change-the-terms-at-will clause, wipfli's note). Already declined and not to be asked again: Lithuania's 5 m DTM (non-commercial), the Azores (non-commercial) and Hong Kong (DATA.GOV.HK terms revocable at any time, which also rules out CEDD's 0.5 m 2020 LiDAR even though it is a free bulk download). The ❌ rows on National Datasets fail the same test: Mexico INEGI, Indonesia DEMNAS, Haiti CNIGS, Klaipėda, Hawaii, South Australia's Murray and the Kīlauea 2018 survey.