@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/terrain/drape/shared.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The shared parts of the analytic drape
+ *
+ * There are two passes that draw the ground (`renderer.ts`, which paints the polygons and
+ * lines of features, and `quad.ts`, which pastes textured quads). Both are completely
+ * identical up to "drawing a terrain mesh with the same rules as MapLibre, with the same DEM
+ * and the same projection"; the only difference is what they solve in the fragment. The common
+ * part is placed here, which structurally guarantees that the two passes sit on the same
+ * ground.
+ */
+import type { ProjectionData } from 'maplibre-gl';
+/**
+ * The GLSL that samples the DEM (used in both the vertex and the fragment stage)
+ *
+ * It does what the #ifdef TERRAIN3D section of MapLibre's vertex prelude does (the prelude
+ * handed to a CustomLayer contains only the projection part and not this section). The layout
+ * of the DEM texture is maplibre's and is copied once, in `upstream-terrain.ts`. Since the
+ * elevation is looked up the same way, with the same DEM and the same grid, our own mesh
+ * agrees with MapLibre's terrain surface.
+ */
+export declare const TERRAIN_SAMPLE_GLSL: string;
+/**
+ * The GLSL of the terrain shading (an aid to reading the map)
+ *
+ * It builds the gradient from differences between neighboring DEM samples and hands it to the
+ * shared formula (`TERRAIN_SHADE_CORE_GLSL` in `terrain/shade.ts`). All this takes charge of
+ * is how the samples are taken. The vertex displacement path
+ * (`shaders/terrain-shade.ts`) hands samples taken from the atlas to the same formula.
+ *
+ * The caller must declare `u_light_dir` (east, north and up in the map coordinate system),
+ * `u_shade_strength` and `u_tile_meters` (the ground size of that tile). It goes after
+ * TERRAIN_SAMPLE_GLSL.
+ */
+export declare const TERRAIN_SHADE_GLSL: string;
+/**
+ * The width of the samples taken for the shading gradient (in tile coordinates)
+ *
+ * The authority for the implementation is TERRAIN_SHADE_GLSL, but the formula itself is also
+ * placed here as a pure function so that it can be verified. The DEM texels exist only in
+ * [0, demLastTexel(dim)] of coord space (the border texels at both ends are copied from the
+ * neighboring tiles, `upstream-terrain.ts`), so a width that goes outside that cannot be used.
+ *
+ * @param coord The coord of the current position (in texel space)
+ * @param coordPerUnit The advance of coord per 1 tile coordinate
+ * @param want The width one wants to use (in tile coordinates)
+ * @param dim The dimension of the DEM
+ */
+export declare function drapeShadeWindow(coord: number, coordPerUnit: number, want: number, dim: number): {
+    back: number;
+    forward: number;
+};
+/** The names of the projection uniforms (declared by the prelude) */
+export declare const DRAPE_PROJECTION_UNIFORMS: readonly ["u_projection_matrix", "u_projection_tile_mercator_coords", "u_projection_clipping_plane", "u_projection_transition", "u_projection_fallback_matrix"];
+/** The names of the DEM uniforms (declared by TERRAIN_SAMPLE_GLSL) */
+export declare const DRAPE_TERRAIN_UNIFORMS: readonly ["u_terrain", "u_terrain_dim", "u_terrain_matrix", "u_terrain_unpack", "u_terrain_exaggeration"];
+/** The index of uniform locations */
+export type UniformSet = Record<string, WebGLUniformLocation | null>;
+/**
+ * Writes that tile's ProjectionData into the uniforms
+ */
+export declare function applyDrapeProjectionUniforms(gl: WebGL2RenderingContext, set: UniformSet, projectionData: ProjectionData): void;
+/** The parts of a DEM texture set that are needed */
+export interface DrapeTerrainTexture {
+    texture: WebGLTexture;
+    matrix: ArrayLike<number>;
+    unpack: ArrayLike<number>;
+    dim: number;
+    /** The vertical exaggeration of the terrain (the same factor MapLibre's mesh uses) */
+    exaggeration: number;
+}
+/**
+ * Binds the DEM and writes it into the uniforms (bound the same way as MapLibre's terrain
+ * prelude)
+ *
+ * The exaggeration is the one MapLibre applies to its own terrain mesh, so the drape surface
+ * stays on the map's ground surface (`getTerrainExaggeration` in `detect.ts`).
+ */
+export declare function applyDrapeTerrainUniforms(gl: WebGL2RenderingContext, set: UniformSet, terrain: DrapeTerrainTexture, unit: number): void;
+/** ArrayLike into a 4x4 Float32Array */
+export declare function toFloat32Matrix(source: ArrayLike<number>): Float32Array;

package/dist/view/terrain/drape/shared.js

@@ -0,0 +1,173 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only AND BSD-3-Clause
+import { TERRAIN_SHADE_CORE_GLSL } from '../shade.js';
+import { demLastTexel, UPSTREAM_DEM_GLSL } from '../upstream-terrain.js';
+import { TILE_EXTENT } from './mesh.js';
+/**
+ * The GLSL that samples the DEM (used in both the vertex and the fragment stage)
+ *
+ * It does what the #ifdef TERRAIN3D section of MapLibre's vertex prelude does (the prelude
+ * handed to a CustomLayer contains only the projection part and not this section). The layout
+ * of the DEM texture is maplibre's and is copied once, in `upstream-terrain.ts`. Since the
+ * elevation is looked up the same way, with the same DEM and the same grid, our own mesh
+ * agrees with MapLibre's terrain surface.
+ */
+export const TERRAIN_SAMPLE_GLSL = `
+uniform sampler2D u_terrain;
+uniform float u_terrain_dim;
+uniform mat4 u_terrain_matrix;
+uniform vec4 u_terrain_unpack;
+uniform float u_terrain_exaggeration;
+${UPSTREAM_DEM_GLSL}
+// The texel coordinate of a tile position in this tile's DEM
+vec2 drape_dem_coord(vec2 pos) {
+    return upstream_dem_coord((u_terrain_matrix * vec4(pos, 0.0, 1.0)).xy, u_terrain_dim);
+}
+
+float drape_get_elevation(vec2 pos) {
+    return upstream_dem_bilinear(u_terrain, u_terrain_unpack, drape_dem_coord(pos)) *
+        u_terrain_exaggeration;
+}
+`;
+/**
+ * The GLSL of the terrain shading (an aid to reading the map)
+ *
+ * It builds the gradient from differences between neighboring DEM samples and hands it to the
+ * shared formula (`TERRAIN_SHADE_CORE_GLSL` in `terrain/shade.ts`). All this takes charge of
+ * is how the samples are taken. The vertex displacement path
+ * (`shaders/terrain-shade.ts`) hands samples taken from the atlas to the same formula.
+ *
+ * The caller must declare `u_light_dir` (east, north and up in the map coordinate system),
+ * `u_shade_strength` and `u_tile_meters` (the ground size of that tile). It goes after
+ * TERRAIN_SAMPLE_GLSL.
+ */
+export const TERRAIN_SHADE_GLSL = TERRAIN_SHADE_CORE_GLSL +
+    `
+float terrainShade(vec2 tilePos) {
+    if (u_shade_strength <= 0.0) return 1.0;
+    float texel = ${TILE_EXTENT}.0 / max(u_terrain_dim, 1.0);
+    vec2 pos = tilePos * ${TILE_EXTENT}.0;
+
+    // The samples for the gradient are kept within the range where DEM texels exist.
+    //
+    // A render tile reads only a part of its DEM tile (deltaZoom = 1), and at the far end of
+    // the DEM texture the forward sample may run past the last texel. Reading outside the
+    // range makes the clamp in upstream_dem_bilinear return the border value, the sample
+    // freezes and the gradient becomes too small. The band where it shrinks fails to receive
+    // its shading, floats brightly and shows up as a streak of 1 to 2 pixels along the tile
+    // boundary.
+    //
+    // What is kept in is only the place where the texels really run out. Everywhere else real
+    // data continues both forward and backward, so the width stays at its full value.
+    vec2 coord = drape_dem_coord(pos);
+    // The advance of coord per 1 tile coordinate (the diagonal of the DEM matrix x the DEM
+    // dimension)
+    vec2 perUnit = max(
+        vec2(u_terrain_matrix[0].x, u_terrain_matrix[1].y) * u_terrain_dim,
+        vec2(1e-9));
+    vec2 forward = clamp(
+        (vec2(upstream_dem_last_texel(u_terrain_dim)) - coord) / perUnit, vec2(0.0), vec2(texel));
+    vec2 backward = clamp(coord / perUnit, vec2(0.0), vec2(texel));
+
+    float ex1 = drape_get_elevation(vec2(pos.x + forward.x, pos.y));
+    float ex0 = drape_get_elevation(vec2(pos.x - backward.x, pos.y));
+    float ey1 = drape_get_elevation(vec2(pos.x, pos.y + forward.y));
+    float ey0 = drape_get_elevation(vec2(pos.x, pos.y - backward.y));
+    // 1.0 in within-tile coordinates corresponds to u_tile_meters. y points south, so north is
+    // flipped. What it is divided by is "the width actually used" (dividing by anything other
+    // than the shrunk width makes the gradient too thin)
+    vec2 span =
+        max(forward + backward, vec2(1e-4)) / ${TILE_EXTENT}.0 * max(u_tile_meters, 1.0);
+    float dzdEast = (ex1 - ex0) / span.x;
+    float dzdNorth = -(ey1 - ey0) / span.y;
+    return terrainShadeFromGradient(dzdEast, dzdNorth);
+}
+`;
+/**
+ * The width of the samples taken for the shading gradient (in tile coordinates)
+ *
+ * The authority for the implementation is TERRAIN_SHADE_GLSL, but the formula itself is also
+ * placed here as a pure function so that it can be verified. The DEM texels exist only in
+ * [0, demLastTexel(dim)] of coord space (the border texels at both ends are copied from the
+ * neighboring tiles, `upstream-terrain.ts`), so a width that goes outside that cannot be used.
+ *
+ * @param coord The coord of the current position (in texel space)
+ * @param coordPerUnit The advance of coord per 1 tile coordinate
+ * @param want The width one wants to use (in tile coordinates)
+ * @param dim The dimension of the DEM
+ */
+export function drapeShadeWindow(coord, coordPerUnit, want, dim) {
+    const perUnit = Math.max(coordPerUnit, 1e-9);
+    const clampWidth = (value) => Math.min(Math.max(value, 0), want);
+    return {
+        back: clampWidth(coord / perUnit),
+        forward: clampWidth((demLastTexel(dim) - coord) / perUnit),
+    };
+}
+/** The names of the projection uniforms (declared by the prelude) */
+export const DRAPE_PROJECTION_UNIFORMS = [
+    'u_projection_matrix',
+    'u_projection_tile_mercator_coords',
+    'u_projection_clipping_plane',
+    'u_projection_transition',
+    'u_projection_fallback_matrix',
+];
+/** The names of the DEM uniforms (declared by TERRAIN_SAMPLE_GLSL) */
+export const DRAPE_TERRAIN_UNIFORMS = [
+    'u_terrain',
+    'u_terrain_dim',
+    'u_terrain_matrix',
+    'u_terrain_unpack',
+    'u_terrain_exaggeration',
+];
+/**
+ * Writes that tile's ProjectionData into the uniforms
+ */
+export function applyDrapeProjectionUniforms(gl, set, projectionData) {
+    if (set.u_projection_matrix) {
+        gl.uniformMatrix4fv(set.u_projection_matrix, false, projectionData.mainMatrix);
+    }
+    if (set.u_projection_tile_mercator_coords && projectionData.tileMercatorCoords) {
+        gl.uniform4fv(set.u_projection_tile_mercator_coords, projectionData.tileMercatorCoords);
+    }
+    if (set.u_projection_clipping_plane && projectionData.clippingPlane) {
+        gl.uniform4fv(set.u_projection_clipping_plane, projectionData.clippingPlane);
+    }
+    if (set.u_projection_transition) {
+        gl.uniform1f(set.u_projection_transition, projectionData.projectionTransition ?? 0);
+    }
+    if (set.u_projection_fallback_matrix && projectionData.fallbackMatrix) {
+        gl.uniformMatrix4fv(set.u_projection_fallback_matrix, false, projectionData.fallbackMatrix);
+    }
+}
+/**
+ * Binds the DEM and writes it into the uniforms (bound the same way as MapLibre's terrain
+ * prelude)
+ *
+ * The exaggeration is the one MapLibre applies to its own terrain mesh, so the drape surface
+ * stays on the map's ground surface (`getTerrainExaggeration` in `detect.ts`).
+ */
+export function applyDrapeTerrainUniforms(gl, set, terrain, unit) {
+    gl.activeTexture(gl.TEXTURE0 + unit);
+    gl.bindTexture(gl.TEXTURE_2D, terrain.texture);
+    if (set.u_terrain)
+        gl.uniform1i(set.u_terrain, unit);
+    if (set.u_terrain_dim)
+        gl.uniform1f(set.u_terrain_dim, terrain.dim);
+    if (set.u_terrain_matrix) {
+        gl.uniformMatrix4fv(set.u_terrain_matrix, false, toFloat32Matrix(terrain.matrix));
+    }
+    if (set.u_terrain_unpack) {
+        const u = terrain.unpack;
+        gl.uniform4f(set.u_terrain_unpack, u[0], u[1], u[2], u[3]);
+    }
+    if (set.u_terrain_exaggeration)
+        gl.uniform1f(set.u_terrain_exaggeration, terrain.exaggeration);
+}
+/** ArrayLike into a 4x4 Float32Array */
+export function toFloat32Matrix(source) {
+    const out = new Float32Array(16);
+    for (let i = 0; i < 16; i++)
+        out[i] = source[i];
+    return out;
+}

package/dist/view/terrain/drape/stitch.d.ts

@@ -0,0 +1,155 @@
+/** Tile identity (the minimum) */
+export interface StitchTile {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/**
+ * The constraint step per edge (tile coordinates)
+ *
+ * 0 means no constraint (the neighbor is at the same zoom, or finer, or is not
+ * drawn). top = the edge at y 0, bottom = the edge at y EXTENT, left = the edge
+ * at x 0, right = the edge at x EXTENT.
+ */
+export interface TileEdgeSteps {
+    readonly top: number;
+    readonly bottom: number;
+    readonly left: number;
+    readonly right: number;
+}
+/** The stitching of a single edge */
+export interface EdgeStitch {
+    /** The constraint step (tile coordinates). 0 means no constraint */
+    readonly step: number;
+    /**
+     * The neighboring tile on the coarser side (null when not constraining)
+     *
+     * x is expressed "in the same wrap as this tile" (a neighbor reached by
+     * wrapping the world in the longitude direction becomes a negative value or
+     * 2^z or more). This is so that the coordinate transform can be built from
+     * this value just as it is.
+     */
+    readonly tile: StitchTile | null;
+}
+/** The stitching of the four edges of a tile */
+export interface TileEdgeStitch {
+    readonly top: EdgeStitch;
+    readonly bottom: EdgeStitch;
+    readonly left: EdgeStitch;
+    readonly right: EdgeStitch;
+}
+/** No constraint */
+export declare const NO_EDGE_STEPS: TileEdgeSteps;
+/** Four edges with no constraint */
+export declare const NO_EDGE_STITCH: TileEdgeStitch;
+/**
+ * The key of a tile (folding the wrap in the longitude direction)
+ *
+ * `computeEdgeStitch` returns the neighbor in the frame before wrapping so that
+ * the coordinate transform can be built, so fold it here when looking up the
+ * set.
+ */
+export declare function wrappedTileKey(tile: StitchTile): string;
+/**
+ * Build the set of keys from the set of tiles in view
+ *
+ * What is passed is "the tiles actually drawn in this frame". Putting in tiles
+ * that are not drawn would mean constraining onto the polyline of a counterpart
+ * that is not drawn.
+ */
+export declare function buildTileKeySet(tiles: readonly StitchTile[]): Set<string>;
+/**
+ * Obtain the stitching of the four edges of this tile
+ *
+ * @param meshSize The subdivision count of the terrain mesh (MapLibre default is 128)
+ */
+export declare function computeEdgeStitch(keys: ReadonlySet<string>, tile: StitchTile, meshSize: number): TileEdgeStitch;
+/** Take only the steps out of the stitching */
+export declare function edgeStepsOf(stitch: TileEdgeStitch): TileEdgeSteps;
+/**
+ * Obtain the constraint steps of the four edges of this tile
+ *
+ * @param meshSize The subdivision count of the terrain mesh (MapLibre default is 128)
+ */
+export declare function computeEdgeSteps(keys: ReadonlySet<string>, tile: StitchTile, meshSize: number): TileEdgeSteps;
+/** The similarity transform mapping one own tile coordinates to the neighbor tile coordinates */
+export interface NeighborTileTransform {
+    /** The scale factor (a power of 2; less than 1 because the neighbor is coarser) */
+    readonly scale: number;
+    readonly offsetX: number;
+    readonly offsetY: number;
+}
+/**
+ * One own tile coordinates -> the tile coordinates of the neighbor (the coarser
+ * side)
+ *
+ * It is `q = p * scale + offset`. The scale factor is a power of 2 and the
+ * translation is an integer multiple of one mesh cell, so the mapping is exact
+ * even in float. That is, the nodes of the step land exactly on the mesh nodes
+ * of the coarser side, and read the same DEM texels with the same weights as the
+ * coarser side reads at its own vertices. This is the ground for "the edge
+ * vertices of the finer side lying exactly on the line segments of the coarser
+ * side".
+ */
+export declare function neighborTileTransform(fine: StitchTile, coarse: StitchTile, extent?: number): NeighborTileTransform;
+/**
+ * The constraint for a single edge (holding the step, the coordinate transform
+ * and the DEM of the constraint target as one set)
+ *
+ * The point is that the three are gathered into a single value. It is a shape
+ * that makes a state where only the step is new and the DEM is old (or the
+ * other way around) impossible to create, so that applying the constraint and
+ * holding the constraint target become one and the same fact.
+ */
+export interface ResolvedEdge<T> {
+    /** The constraint step (tile coordinates). It never becomes 0 */
+    readonly step: number;
+    /** The tile on the coarser side (x in the frame before wrapping) */
+    readonly tile: StitchTile;
+    /** One own tile coordinates -> the tile coordinates of the coarser side */
+    readonly transform: NeighborTileTransform;
+    /** The DEM of the coarser side (looked up at the same point in time as the step) */
+    readonly terrain: T;
+}
+/** The constraints of the four edges of a tile (an edge that is not constrained is null) */
+export interface ResolvedTileEdges<T> {
+    readonly top: ResolvedEdge<T> | null;
+    readonly bottom: ResolvedEdge<T> | null;
+    readonly left: ResolvedEdge<T> | null;
+    readonly right: ResolvedEdge<T> | null;
+}
+/** No edge is constrained */
+export declare const NO_RESOLVED_EDGES: ResolvedTileEdges<never>;
+/**
+ * Derive the constraints of the four edges of this tile wholly from the current
+ * tile state
+ *
+ * The level difference (Δz), the coordinate transform, the step and the DEM of
+ * the constraint target are all brought together in a single call. The step is
+ * not baked into the vertex data (the mesh is a single one independent of the
+ * tile, and the step can only be passed as a uniform), so merely passing through
+ * here again every frame structurally prevents the mismatch "the DEM is new but
+ * the level difference is old".
+ *
+ * An edge for which `resolve` returns null is not constrained. Leaving only the
+ * step when the DEM of the constraint target cannot be held would mean
+ * constraining onto a polyline that steps one own DEM coarsely, and the crack
+ * that was supposed to be fixed would come back just there.
+ *
+ * @param keys The set of keys of the tiles actually drawn in this frame
+ * @param resolve Look up the DEM from the tile on the coarser side (null if it
+ *   cannot be looked up)
+ */
+export declare function resolveTileEdges<T>(keys: ReadonlySet<string>, tile: StitchTile, meshSize: number, resolve: (neighbor: StitchTile) => T | null): ResolvedTileEdges<T>;
+/**
+ * The elevation after constraining (the same expression as drape_constrain in
+ * the vertex shader)
+ *
+ * The shader is the authority for the implementation, but the expression itself
+ * is placed here as a pure function so that it can be verified. `sample` returns
+ * the elevation of a node of the polyline on the coarser side.
+ *
+ * @param along The position along the edge (in this tile coordinates)
+ * @param step The node spacing of the coarser side (in this tile coordinates)
+ */
+export declare function constrainEdgeElevation(along: number, step: number, sample: (at: number) => number, extent?: number): number;

package/dist/view/terrain/drape/stitch.js

@@ -0,0 +1,228 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Stitching tile boundaries (resolving T-junctions)
+ *
+ * MapLibre chooses the zoom of terrain tiles by distance, so tiles of different
+ * zooms coexist within a single screen (in a pitched view z6 and z9 sit side by
+ * side). The difference is not necessarily a single level.
+ *
+ * When tiles of different zooms are adjacent, nodes that the coarser side does
+ * not have are lined up along the boundary of the finer side. The finer side
+ * takes the elevation of its own DEM at those nodes, but the coarser side joins
+ * node to node with a straight line, so the two surfaces separate in between (a
+ * T-junction). The basemap below shows through the gap that opens, and it looks
+ * like a dotted gap running along the tile boundary.
+ *
+ * The way to fix it is to "constrain the elevation of the finer side boundary
+ * onto the polyline of the coarser side". The boundary itself is a straight line
+ * in tile coordinates, so only the elevation has to be moved. Taking the node
+ * spacing of the coarser side (`delta * 2^Δz` in this tile coordinates) as the
+ * step, and using the value obtained by linearly interpolating the elevations at
+ * both ends of that step, the gap becomes structurally zero whatever the level
+ * difference Δz is.
+ *
+ * However, "the polyline of the coarser side" is decided by the DEM of the
+ * coarser side. MapLibre reads the DEM one level coarser than the render tile
+ * (`deltaZoom = 1`), so adjacent tiles of different zooms always read DEMs of
+ * different resolutions. Taking the node elevations from one own DEM yields not
+ * the polyline of the coarser side but "a polyline that steps one own DEM
+ * coarsely", and the two stay apart by the difference in DEM resolution. This is
+ * the true identity of the thin line that remains at tile boundaries.
+ *
+ * Therefore the constraint uses the DEM of the coarser side itself. Here, for
+ * each edge, we obtain the "step" and the "tile on the coarser side", and
+ * further produce the transform that maps one own tile coordinates to the tile
+ * coordinates of the coarser side. The actual constraining is done by the vertex
+ * shader (drape_constrain in renderer.ts).
+ */
+import { TILE_EXTENT } from './mesh.js';
+/** No constraint */
+export const NO_EDGE_STEPS = { top: 0, bottom: 0, left: 0, right: 0 };
+/** Four edges with no constraint */
+export const NO_EDGE_STITCH = {
+    top: { step: 0, tile: null },
+    bottom: { step: 0, tile: null },
+    left: { step: 0, tile: null },
+    right: { step: 0, tile: null },
+};
+/**
+ * The key of a tile (folding the wrap in the longitude direction)
+ *
+ * `computeEdgeStitch` returns the neighbor in the frame before wrapping so that
+ * the coordinate transform can be built, so fold it here when looking up the
+ * set.
+ */
+export function wrappedTileKey(tile) {
+    const span = 2 ** tile.z;
+    return `${tile.z}/${((tile.x % span) + span) % span}/${tile.y}`;
+}
+/**
+ * Build the set of keys from the set of tiles in view
+ *
+ * What is passed is "the tiles actually drawn in this frame". Putting in tiles
+ * that are not drawn would mean constraining onto the polyline of a counterpart
+ * that is not drawn.
+ */
+export function buildTileKeySet(tiles) {
+    const set = new Set();
+    for (const tile of tiles)
+        set.add(wrappedTileKey(tile));
+    return set;
+}
+/** Floor division that holds even for negative values (x goes negative with the wrap) */
+function floorShift(value, shift) {
+    return Math.floor(value / 2 ** shift);
+}
+/**
+ * Look up the neighboring tile
+ *
+ * Walking up the ancestors in order starting from the same zoom, the first one
+ * found is the neighbor (drawn tiles do not overlap, so at most one is found).
+ *
+ * The lookup uses the key wrapped in the longitude direction, but the x that is
+ * returned is expressed in the frame before wrapping. Doing so lets the caller
+ * build the transform "one own tile coordinates -> the neighbor tile
+ * coordinates" out of a difference and a ratio alone (`neighborTileTransform`).
+ *
+ * @returns The neighboring tile. null if it is not found
+ */
+function neighborTile(keys, z, x, y) {
+    const span = 2 ** z;
+    if (y < 0 || y >= span)
+        return null;
+    // The longitude direction wraps around the world
+    const wrapped = ((x % span) + span) % span;
+    for (let nz = z; nz >= 0; nz--) {
+        const shift = z - nz;
+        if (keys.has(`${nz}/${wrapped >> shift}/${y >> shift}`)) {
+            return { z: nz, x: floorShift(x, shift), y: y >> shift };
+        }
+    }
+    return null;
+}
+/**
+ * Obtain the stitching of the four edges of this tile
+ *
+ * @param meshSize The subdivision count of the terrain mesh (MapLibre default is 128)
+ */
+export function computeEdgeStitch(keys, tile, meshSize) {
+    const delta = TILE_EXTENT / meshSize;
+    const edgeFor = (nx, ny) => {
+        const neighbor = neighborTile(keys, tile.z, nx, ny);
+        if (!neighbor || neighbor.z >= tile.z)
+            return { step: 0, tile: null };
+        return { step: delta * 2 ** (tile.z - neighbor.z), tile: neighbor };
+    };
+    return {
+        top: edgeFor(tile.x, tile.y - 1),
+        bottom: edgeFor(tile.x, tile.y + 1),
+        left: edgeFor(tile.x - 1, tile.y),
+        right: edgeFor(tile.x + 1, tile.y),
+    };
+}
+/** Take only the steps out of the stitching */
+export function edgeStepsOf(stitch) {
+    return {
+        top: stitch.top.step,
+        bottom: stitch.bottom.step,
+        left: stitch.left.step,
+        right: stitch.right.step,
+    };
+}
+/**
+ * Obtain the constraint steps of the four edges of this tile
+ *
+ * @param meshSize The subdivision count of the terrain mesh (MapLibre default is 128)
+ */
+export function computeEdgeSteps(keys, tile, meshSize) {
+    return edgeStepsOf(computeEdgeStitch(keys, tile, meshSize));
+}
+/**
+ * One own tile coordinates -> the tile coordinates of the neighbor (the coarser
+ * side)
+ *
+ * It is `q = p * scale + offset`. The scale factor is a power of 2 and the
+ * translation is an integer multiple of one mesh cell, so the mapping is exact
+ * even in float. That is, the nodes of the step land exactly on the mesh nodes
+ * of the coarser side, and read the same DEM texels with the same weights as the
+ * coarser side reads at its own vertices. This is the ground for "the edge
+ * vertices of the finer side lying exactly on the line segments of the coarser
+ * side".
+ */
+export function neighborTileTransform(fine, coarse, extent = TILE_EXTENT) {
+    const scale = 2 ** (coarse.z - fine.z);
+    return {
+        scale,
+        offsetX: (fine.x * scale - coarse.x) * extent,
+        offsetY: (fine.y * scale - coarse.y) * extent,
+    };
+}
+/** No edge is constrained */
+export const NO_RESOLVED_EDGES = {
+    top: null,
+    bottom: null,
+    left: null,
+    right: null,
+};
+/**
+ * Derive the constraints of the four edges of this tile wholly from the current
+ * tile state
+ *
+ * The level difference (Δz), the coordinate transform, the step and the DEM of
+ * the constraint target are all brought together in a single call. The step is
+ * not baked into the vertex data (the mesh is a single one independent of the
+ * tile, and the step can only be passed as a uniform), so merely passing through
+ * here again every frame structurally prevents the mismatch "the DEM is new but
+ * the level difference is old".
+ *
+ * An edge for which `resolve` returns null is not constrained. Leaving only the
+ * step when the DEM of the constraint target cannot be held would mean
+ * constraining onto a polyline that steps one own DEM coarsely, and the crack
+ * that was supposed to be fixed would come back just there.
+ *
+ * @param keys The set of keys of the tiles actually drawn in this frame
+ * @param resolve Look up the DEM from the tile on the coarser side (null if it
+ *   cannot be looked up)
+ */
+export function resolveTileEdges(keys, tile, meshSize, resolve) {
+    const stitch = computeEdgeStitch(keys, tile, meshSize);
+    const resolveEdge = (edge) => {
+        if (!edge.tile || edge.step <= 0)
+            return null;
+        const terrain = resolve(edge.tile);
+        if (terrain === null)
+            return null;
+        return {
+            step: edge.step,
+            tile: edge.tile,
+            transform: neighborTileTransform(tile, edge.tile),
+            terrain,
+        };
+    };
+    return {
+        top: resolveEdge(stitch.top),
+        bottom: resolveEdge(stitch.bottom),
+        left: resolveEdge(stitch.left),
+        right: resolveEdge(stitch.right),
+    };
+}
+/**
+ * The elevation after constraining (the same expression as drape_constrain in
+ * the vertex shader)
+ *
+ * The shader is the authority for the implementation, but the expression itself
+ * is placed here as a pure function so that it can be verified. `sample` returns
+ * the elevation of a node of the polyline on the coarser side.
+ *
+ * @param along The position along the edge (in this tile coordinates)
+ * @param step The node spacing of the coarser side (in this tile coordinates)
+ */
+export function constrainEdgeElevation(along, step, sample, extent = TILE_EXTENT) {
+    const t0 = Math.floor(along / step) * step;
+    const t1 = Math.min(t0 + step, extent);
+    const e0 = sample(t0);
+    const e1 = sample(t1);
+    const w = t1 > t0 ? (along - t0) / (t1 - t0) : 0;
+    return e0 + (e1 - e0) * w;
+}