voncannon
commented
7 months ago Naming is hard. So adding more terminology to the docket...
I think traditionally the thicker contour lines are called index contours:
- page 9 https://pubs.usgs.gov/circ/1955/0368/report.pdf
- https://www3.nd.edu/~cneal/planetearth/Lab-SurfaceHydrology/TopoMaps.html
Following the example below, one advantage here is both intervals and indexIntervals track the same unit as specified .. rather than one being a unit and one a interval/multiplier/skip/etc, respectively.
N/multiplier/skip can be computed per zoom level under the covers: multiplier = index_interval / interval
sources: {
dem: {
type: "raster-dem",
encoding: "terrarium",
tiles: ["https://elevation-tiles-prod.s3.amazonaws.com/terrarium/{z}/{x}/{y}.png"],
maxzoom: 13,
tileSize: 256,
},
contours: {
type: "contour",
source: "dem",
unit: "feet" | "meters" | number, // default=meters
// similar syntax to ["step", ["zoom"], ...] style expression
// to define contour interval by zoom level
intervals: [
200, // 200m interval <=z11
12, 100, // 100m interval at z12 and z13
14, 50, // 50m interval at z14
15, 20 // 20m interval >= z15
},
indexIntervals: [
5, // every 1000m at < z14
14, 200, every 200m at z14
15, 100 // every 100m for >= z15
],
minzoom: 11,
// overzoom z13 DEM tiles up to z16 to generate smooth high-zoom contour lines:
maxzoom: 16,
// overzoom z10 tiles to generate z11 contour lines, z11 to make z12, etc...
overzoom: 1,
},
},
HarelM
msbarry
zstadler
Design Proposal: Contour Line Source from Raster DEM Tiles
Motivation
Give users a built-in way to render contour lines in maplibre from the same DEM tiles that are already used for terrain and hillshading, like this:
Proposed Change
Create a new
contoursource type in maplibre style spec that takes a raster-dem source as input and generates contour isolines as output that can be styled using line layers, for example:The generated isolines will have these attributes:
eleelevation above sea level in the unit specifiedintervalthe fixed interval between isolines at this zoom level in the unit specifiedmajortrue if this is a major isoline based on majorMultiplier at this zoom level, false otherwiseLayers can refer to the contours with
source: contoursbut they can omitsourceLayer.This offloads details about how to retrieve and parse DEM tiles to the DEM source definition, and gives style layers the flexibility to render any number of visible lines derived from that contour source.
I've already prototyped this in the maplibre-contour plugin which I'm using for contour lines on onthegomap.com. Here are some of the issues I had to work through to get these contours to look nice:
DEM "overzooming" (smoothing)
The contour lines look blocky when you zoom in much further past the maximum zoom for a DEM source, but they can look nice and smooth if you "overzoom" the DEM tiles by applying iterative bilinear interpolation before generating isolines. For example for onthegomap I use 512px z11 tiles, but overzoom the z11 tiles up to z15 so that the contour lines look smooth even at high zooms. This is why the proposal lets you specify a
maxzoomthat is higher than themaxzoomof the raster-dem source.Also to generate smooth contour lines at the border between tiles, the algorithm needs to look at adjacent tiles. This means you need 9 DEM tiles to render a single contour tile. To mitigate this, the
overzoomparameter lets you use overzoomed DEM tiles from a lower zoom level to generate contours at the current zoom level, for exampleoverzoom=1means use the top-left, top-right, botom-left, or bottom-right z10 tile to render a z11 contour line tile. This means you only need 4 DEM tiles to render a single contour tile:Contour levels and units
The user needs to be able to choose what elevations to draw contour lines at, which changes by zoom level (rendering every contour would get too expensive at low zooms in hilly areas). They may also designate "major" and "minor" levels, for example generate thin contour lines every 200m but bold every 1000m. For now we will push this to layers that use the style, but in the future we can either add a major/minor designation to ticks, or pass-through the level and interval so styles can highlight every 5th or 10th line or something.
The
unitattribute multiplies raw meter values by a certain amount to change the unit, for exampleunit=feetchanges from meters to feet. When you click the distance indicator on onthegomap, it toggles betweenunit=metersandunit=feet. You could also set unit to a custom value for less common units likeunit=1.8288for fathoms.Performance and Bundle Size
I've already implemented the smoothing logic and isoline generation in the maplibre-contour plugin so we would just need to bring that into maplibre-gl-js and port into the native projects. The overall plugin is 33kb (11kb gzipped) but most of that is replicating the web worker communication, cancelable message passing, and vector tile encoding that maplibre-gl-js already has. The actual smoothing+isoline business logic is only 3.7kb (1.6kb gzipped).
The isoline generation algorithm was derived from d3-contour but is much more efficient because it generates isolines in a single pass through the DEM tile instead of using a pass per contour level. For onthegomap users on a range of devices (mostly mobile phones) overzooming a 512px dem tile and generating isolines takes:
API Modifications
This should only change the style spec, but shouldn't require any js or native API changes, unless we wanted to expose the default contour layer, elevation or level key as constants?
Migration Plan and Compatibility
This is new functionality, so no migration is necessary.
Rejected Alternatives
Build a plugin for this
I maintain the maplibre-contour plugin which already lets you do this by using the
addProtocolintegration, but it has a few downsides:Pre-render contour lines
You can render contour line vector tiles ahead of time and serve those for the planet, this will save some browser CPU cycles but rendering them on the fly from DEM tiles has a few advantages:
Implement as a new layer type
We could implement this as a new layer type instead of a source type, but that would tightly couple the display parameters to the logic for how contour lines are generated, and potentially require us to generate the contours in multiple passes over the source DEM data. It seems cleaner to generate contour lines so you can generate as many layers as you want from them afterwards.
Take a DEM tile source URL as input
A contour layer could take as input
tiles: ["server.com/{z}/{x}/{y}.png"],but there are a lot of different knobs to tune for how these are interpreted, so by depending on a DEM source we re-use the DEM source control all of those parameters.