@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/terrain/occlusion.js

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Deciding whether a symbol is occluded by the terrain (whether to ghost it)
+ *
+ * Points, icons and billboard labels are drawn without a depth test. A billboard's front/back
+ * order is decided by the depth of its single center point, so enabling depth makes the whole
+ * thing disappear as soon as it sinks a few meters into the ground (confirmed by measurement).
+ * On the other hand, a symbol behind a mountain stays clearly visible, which is misread as
+ * "being in front". So what is occluded is drawn faintly (a CesiumJS-style ghost).
+ *
+ * The test runs on the CPU. The segment drawn from the camera to the anchor is sampled, and if
+ * the ground elevation along the way rises above the segment it is occluded. Fetching a single
+ * elevation takes about 0.4us, so 24 samples along the segment cost about 10us per anchor,
+ * which is enough. Solving it on the GPU would mean ray marching in the fragment shader, whose
+ * cost per symbol is far larger.
+ *
+ * Reading the depth buffer (MapLibre's `terrain.depthAtPoint`) is not an option: `readPixels`
+ * runs for every single point, which inserts a synchronous wait and stalls rendering once per
+ * symbol.
+ */
+import { drawnLongitude } from './anchor.js';
+import { groundElevationMeters } from './ground.js';
+import { mercatorX, mercatorY } from './tessellation.js';
+/**
+ * Opacity of an occluded symbol
+ *
+ * @internal
+ */
+export const TERRAIN_GHOST_OPACITY = 0.35;
+/** Upper bound on the number of samples along the segment */
+const MAX_SAMPLES = 24;
+/** Lower bound on the number of samples along the segment */
+const MIN_SAMPLES = 6;
+/**
+ * Margin discarded on the camera side
+ *
+ * The ground directly below the camera almost always rises above the segment (the camera is
+ * above the ground, but the line of sight points downward, so it grazes the ground just past
+ * the starting point). Looking there would make everything occluded, so the first few percent
+ * on the start side are skipped.
+ */
+const NEAR_SKIP = 0.08;
+/**
+ * Margin discarded on the anchor side (counted in terrain mesh nodes)
+ *
+ * The anchor sits on top of the ground, so the ground just in front of it is necessarily at
+ * the same height. To keep it from hiding itself, two nodes' worth is skipped.
+ */
+const SELF_SKIP_NODES = 2;
+/**
+ * Converts a Mercator y back into a latitude
+ */
+function inverseMercatorY(y) {
+    return (Math.atan(Math.sinh(Math.PI * (1 - 2 * y))) * 180) / Math.PI;
+}
+/**
+ * Whether an anchor is occluded by the terrain
+ *
+ * Always false (not occluded) when the terrain is disabled or the camera position cannot be
+ * obtained. This matches the appearance before the terrain was introduced exactly.
+ *
+ * @internal
+ */
+export function isAnchorOccluded(context, lng, lat) {
+    const frame = context.anchorFrame;
+    const terrain = frame.terrain;
+    const camera = frame.cameraMercator;
+    if (!terrain || !camera)
+        return false;
+    const scale = frame.elevationScale;
+    if (!(scale > 0))
+        return false;
+    const cached = context.occlusionCache.get(`${lng},${lat}`);
+    if (cached !== undefined)
+        return cached;
+    const result = computeOccluded(lng, lat, scale, camera, terrain, context);
+    context.occlusionCache.set(`${lng},${lat}`, result);
+    return result;
+}
+/**
+ * Returns the opacity for a symbol at a point: 0.35 when the terrain hides it from the camera,
+ * 1 otherwise.
+ *
+ * @param context The terrain state of the draw instance
+ * @param lng The longitude in degrees
+ * @param lat The latitude in degrees
+ * @returns 0.35 or 1. Always 1 when the terrain is disabled
+ */
+export function anchorGhostOpacity(context, lng, lat) {
+    return isAnchorOccluded(context, lng, lat) ? TERRAIN_GHOST_OPACITY : 1;
+}
+function computeOccluded(lng, lat, scale, camera, terrain, context) {
+    const frame = context.anchorFrame;
+    // The elevation of the ground maplibre draws (ground.ts), on the copy of the world the
+    // anchor is drawn on
+    const elevationAt = (sampleLng, sampleLat) => groundElevationMeters(frame.elevationQuery, terrain, context.coverage, drawnLongitude(context, sampleLng), sampleLat, frame.tileZoom);
+    const ax = mercatorX(lng);
+    const ay = mercatorY(lat);
+    const az = elevationAt(lng, lat) * scale;
+    const [cx, cy, cz] = camera;
+    const dx = ax - cx;
+    const dy = ay - cy;
+    const dz = az - cz;
+    const horizontal = Math.hypot(dx, dy);
+    if (!(horizontal > 0))
+        return false;
+    // The sample spacing matches the node spacing of the terrain mesh (sampling any finer only
+    // goes beyond the resolution of the bilinear interpolation and adds no information)
+    const node = context.renderState.stepGrid > 0 ? context.renderState.stepGrid : horizontal / 16;
+    const samples = Math.min(MAX_SAMPLES, Math.max(MIN_SAMPLES, Math.ceil(horizontal / node)));
+    // The ground just in front of the anchor is the anchor's own ground, so it is skipped
+    const selfSkip = Math.min(0.5, (SELF_SKIP_NODES * node) / horizontal);
+    const tEnd = 1 - selfSkip;
+    if (!(tEnd > NEAR_SKIP))
+        return false;
+    for (let i = 0; i < samples; i++) {
+        const t = NEAR_SKIP + ((tEnd - NEAR_SKIP) * (i + 0.5)) / samples;
+        const px = cx + dx * t;
+        const py = cy + dy * t;
+        const pz = cz + dz * t;
+        const sampleLng = px * 360 - 180;
+        const sampleLat = inverseMercatorY(py);
+        const surface = elevationAt(sampleLng, sampleLat) * scale;
+        if (surface > pz)
+            return true;
+    }
+    return false;
+}

package/dist/view/terrain/polygon.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The injection point for terrain subdivision of polygons
+ *
+ * Called from the polygon renderers (polygon/sdf-polygon.ts and polygon/batch.ts). When the
+ * terrain is disabled, `getTerrainTessellationStep(context)` returns null and the caller does
+ * nothing. Rendering without terrain therefore does not change by a single byte.
+ */
+import type { Coordinate } from '../../store/types.js';
+import type { TerrainContext } from './context.js';
+import { type MercatorRect, type TessellationStep } from './tessellation.js';
+/**
+ * Returns the subdivision step of the terrain mesh for the current frame.
+ *
+ * @param context The terrain state of the draw instance
+ * @returns The step, or `null` when the terrain is disabled
+ */
+export declare function getTerrainTessellationStep(context: TerrainContext): TessellationStep | null;
+/**
+ * Decides the effective step for a single feature
+ *
+ * The step is decided by the screen (the zoom), but for a large feature the grid can reach
+ * hundreds of thousands of cells. Cutting off once the upper bound is reached produces the
+ * distorted result "only the first triangles are fine and the rest stay coarse", and only part
+ * of the polygon sits on the terrain. So instead of cutting off, the step is coarsened by a
+ * power of 2 and the whole feature is subdivided uniformly. It is a power of 2 so that the
+ * coarse grid is a subset of the fine grid (the fill and the outline are subdivided at the
+ * same points).
+ */
+export declare function polygonTessellationStep(base: TessellationStep, flatCoords: readonly number[]): TessellationStep;
+/**
+ * The number of grid cells the bounding box covers (an estimate, from a flat coordinate array)
+ *
+ * Outside the range (region) nothing is subdivided, so that part is not counted.
+ */
+export declare function boundingCells(flatCoords: readonly number[], grid: number, region?: MercatorRect | null): number;
+/**
+ * The number of grid cells the bounding box covers (an estimate, from rings)
+ *
+ * Every feature is scanned in order to estimate the total amount of the batch, so the count is
+ * made without building an array for flattening.
+ */
+export declare function ringBoundingCells(ring: readonly Coordinate[], grid: number, region?: MercatorRect | null): number;
+/**
+ * Whether the bounding box of a flat coordinate array intersects the range
+ */
+export declare function flatCoordsIntersect(flatCoords: readonly number[], region: MercatorRect): boolean;
+/**
+ * Whether the bounding box of an array of rings intersects the range
+ */
+export declare function ringsIntersect(rings: readonly Coordinate[][], region: MercatorRect): boolean;
+/**
+ * Decides the coarsening factor applied to the whole batch (a power of 2)
+ *
+ * A per-feature upper bound cannot hold back a batch with thousands of features (a
+ * dataset). The total number of cells is estimated before construction, and if
+ * it exceeds the budget the whole batch is coarsened uniformly. Applying a different factor
+ * per feature would put neighboring features on different grids and make them disagree at the
+ * boundary, so there is one factor per batch.
+ *
+ * @param totalCells The sum of the bounding box cell counts of all features
+ */
+export declare function batchTessellationFactor(totalCells: number): number;
+/**
+ * Subdivides the fill of a single feature and returns the step actually used
+ *
+ * When the step was too fine to finish subdividing (the vertex budget ran out, or a single
+ * triangle sweeps too many cells), emitting it as is produces a mixture where "part of it
+ * follows the terrain while the rest are flat triangles breaking through the terrain". This is
+ * what is behind the wedge-shaped breakage sticking out of the terrain, so it is coarsened and
+ * subdivided again. Subdividing the outline with the returned step as well guarantees that the
+ * fill and the outline lie on the same grid.
+ *
+ * @returns The subdivision result and the step that produced it
+ */
+export declare function tessellatePolygonFill(context: TerrainContext, featureId: string | undefined, partIndex: number, flatCoords: number[], indices: number[], base: TessellationStep): {
+    flatCoords: number[];
+    indices: number[];
+    step: TessellationStep;
+};
+/**
+ * Subdivides the rings of the outline
+ *
+ * It uses the same grid as the fill, so the edge of the fill and the vertices of the outline
+ * still agree after subdivision.
+ */
+export declare function tessellateRings(rings: Coordinate[][], step: TessellationStep): Coordinate[][];

package/dist/view/terrain/polygon.js

@@ -0,0 +1,301 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { TERRAIN_MAX_BATCH_SUBDIVISION_CELLS, TERRAIN_MAX_COARSEN_STEPS, TERRAIN_MAX_SUBDIVISION_POINTS, TERRAIN_MAX_TILED_SUBDIVISION_POINTS, } from './metrics.js';
+import { getTerrainRenderState } from './state.js';
+import { cellsInRegion, densifyRings, mercatorX, mercatorY, rectsIntersect, subdivideTriangles, } from './tessellation.js';
+import { tilingSignature } from './tiling.js';
+/**
+ * Returns the subdivision step of the terrain mesh for the current frame.
+ *
+ * @param context The terrain state of the draw instance
+ * @returns The step, or `null` when the terrain is disabled
+ */
+export function getTerrainTessellationStep(context) {
+    const terrain = getTerrainRenderState(context);
+    if (!terrain.active || !(terrain.stepGrid > 0))
+        return null;
+    const tiling = terrain.tessellationTiling;
+    return {
+        grid: terrain.stepGrid,
+        // When subdividing to match the tile's actual mesh, the amount is capped by the view, so
+        // the upper bound is set high (falling back to coarsening midway makes the fill drop out
+        // on ridges)
+        maxPoints: tiling ? TERRAIN_MAX_TILED_SUBDIVISION_POINTS : TERRAIN_MAX_SUBDIVISION_POINTS,
+        region: terrain.tessellationRegion,
+        tiling,
+    };
+}
+/**
+ * Decides the effective step for a single feature
+ *
+ * The step is decided by the screen (the zoom), but for a large feature the grid can reach
+ * hundreds of thousands of cells. Cutting off once the upper bound is reached produces the
+ * distorted result "only the first triangles are fine and the rest stay coarse", and only part
+ * of the polygon sits on the terrain. So instead of cutting off, the step is coarsened by a
+ * power of 2 and the whole feature is subdivided uniformly. It is a power of 2 so that the
+ * coarse grid is a subset of the fine grid (the fill and the outline are subdivided at the
+ * same points).
+ */
+export function polygonTessellationStep(base, flatCoords) {
+    // When subdividing to match the tile's actual mesh, no coarsening is applied. Coarsening
+    // would make the step coarser than the tile's mesh, and our own chord would dive below the
+    // ridge and be carved away. The amount is capped by the number of tiles, so no brake is
+    // needed in the first place.
+    if (base.tiling)
+        return base;
+    const cells = boundingCells(flatCoords, base.grid, base.region);
+    if (!(cells > base.maxPoints))
+        return base;
+    // Coarsened by a power of 2 (the coarse grid still lies on a subset of the terrain mesh
+    // nodes)
+    const factor = 2 ** Math.ceil(Math.log2(Math.sqrt(cells / base.maxPoints)));
+    return coarsen(base, factor);
+}
+/**
+ * The number of grid cells the bounding box covers (an estimate, from a flat coordinate array)
+ *
+ * Outside the range (region) nothing is subdivided, so that part is not counted.
+ */
+export function boundingCells(flatCoords, grid, region) {
+    if (flatCoords.length < 2 || !(grid > 0))
+        return 0;
+    let minX = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i < flatCoords.length; i += 2) {
+        const x = flatCoords[i];
+        const y = flatCoords[i + 1];
+        if (x < minX)
+            minX = x;
+        if (x > maxX)
+            maxX = x;
+        if (y < minY)
+            minY = y;
+        if (y > maxY)
+            maxY = y;
+    }
+    return cellsFromBounds(minX, maxX, minY, maxY, grid, region);
+}
+/**
+ * The number of grid cells the bounding box covers (an estimate, from rings)
+ *
+ * Every feature is scanned in order to estimate the total amount of the batch, so the count is
+ * made without building an array for flattening.
+ */
+export function ringBoundingCells(ring, grid, region) {
+    if (ring.length === 0 || !(grid > 0))
+        return 0;
+    let minX = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (const [x, y] of ring) {
+        if (x < minX)
+            minX = x;
+        if (x > maxX)
+            maxX = x;
+        if (y < minY)
+            minY = y;
+        if (y > maxY)
+            maxY = y;
+    }
+    return cellsFromBounds(minX, maxX, minY, maxY, grid, region);
+}
+/**
+ * The fingerprint of the conditions that decide this feature's subdivision
+ *
+ * It is decided by the tile configuration covering it (which cell has which step), the
+ * coarsening factor and the relationship with the range. The elevation is not included,
+ * because the shader looks the elevation up every frame, so there is no need to subdivide
+ * again when the DEM arrives.
+ */
+function fillSignature(step, flatCoords) {
+    if (flatCoords.length < 2)
+        return 'empty';
+    let minLng = Number.POSITIVE_INFINITY;
+    let maxLng = Number.NEGATIVE_INFINITY;
+    let minLat = Number.POSITIVE_INFINITY;
+    let maxLat = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i < flatCoords.length; i += 2) {
+        const lng = flatCoords[i];
+        const lat = flatCoords[i + 1];
+        if (lng < minLng)
+            minLng = lng;
+        if (lng > maxLng)
+            maxLng = lng;
+        if (lat < minLat)
+            minLat = lat;
+        if (lat > maxLat)
+            maxLat = lat;
+    }
+    return tilingSignature(step.tiling ?? null, step.region ?? null, step.coarsen && step.coarsen > 1 ? step.coarsen : 1, step.grid, mercatorX(minLng), 
+    // Mercator y decreases as the latitude increases
+    mercatorY(maxLat), mercatorX(maxLng), mercatorY(minLat));
+}
+/**
+ * Whether the bounding box of a flat coordinate array intersects the range
+ */
+export function flatCoordsIntersect(flatCoords, region) {
+    if (flatCoords.length < 2)
+        return false;
+    let minLng = Number.POSITIVE_INFINITY;
+    let maxLng = Number.NEGATIVE_INFINITY;
+    let minLat = Number.POSITIVE_INFINITY;
+    let maxLat = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i < flatCoords.length; i += 2) {
+        const lng = flatCoords[i];
+        const lat = flatCoords[i + 1];
+        if (lng < minLng)
+            minLng = lng;
+        if (lng > maxLng)
+            maxLng = lng;
+        if (lat < minLat)
+            minLat = lat;
+        if (lat > maxLat)
+            maxLat = lat;
+    }
+    // Mercator y decreases as the latitude increases
+    return rectsIntersect(mercatorX(minLng), mercatorY(maxLat), mercatorX(maxLng), mercatorY(minLat), region);
+}
+/**
+ * Whether the bounding box of an array of rings intersects the range
+ */
+export function ringsIntersect(rings, region) {
+    let minLng = Number.POSITIVE_INFINITY;
+    let maxLng = Number.NEGATIVE_INFINITY;
+    let minLat = Number.POSITIVE_INFINITY;
+    let maxLat = Number.NEGATIVE_INFINITY;
+    for (const ring of rings) {
+        for (const [lng, lat] of ring) {
+            if (lng < minLng)
+                minLng = lng;
+            if (lng > maxLng)
+                maxLng = lng;
+            if (lat < minLat)
+                minLat = lat;
+            if (lat > maxLat)
+                maxLat = lat;
+        }
+    }
+    if (minLng > maxLng)
+        return false;
+    return rectsIntersect(mercatorX(minLng), mercatorY(maxLat), mercatorX(maxLng), mercatorY(minLat), region);
+}
+/**
+ * Converts a longitude/latitude bounding box into a number of Mercator cells (an estimate is
+ * enough)
+ */
+function cellsFromBounds(minX, maxX, minY, maxY, grid, region) {
+    // Mercator y decreases as the latitude increases, so top and bottom are swapped
+    return cellsInRegion(mercatorX(minX), mercatorY(maxY), mercatorX(maxX), mercatorY(minY), grid, region);
+}
+/**
+ * Coarsens the step by a power of 2
+ */
+function coarsen(step, factor) {
+    if (!(factor > 1))
+        return step;
+    if (step.tiling) {
+        // When matching the tile's actual mesh, the factor is raised rather than the step
+        // (being a power of 2, the subdivision points keep lying on a subset of the nodes)
+        return { ...step, coarsen: (step.coarsen ?? 1) * factor };
+    }
+    return { grid: step.grid * factor, maxPoints: step.maxPoints, region: step.region };
+}
+/**
+ * Decides the coarsening factor applied to the whole batch (a power of 2)
+ *
+ * A per-feature upper bound cannot hold back a batch with thousands of features (a
+ * dataset). The total number of cells is estimated before construction, and if
+ * it exceeds the budget the whole batch is coarsened uniformly. Applying a different factor
+ * per feature would put neighboring features on different grids and make them disagree at the
+ * boundary, so there is one factor per batch.
+ *
+ * @param totalCells The sum of the bounding box cell counts of all features
+ */
+export function batchTessellationFactor(totalCells) {
+    if (!(totalCells > TERRAIN_MAX_BATCH_SUBDIVISION_CELLS))
+        return 1;
+    const steps = Math.ceil(Math.log2(Math.sqrt(totalCells / TERRAIN_MAX_BATCH_SUBDIVISION_CELLS)));
+    return 2 ** Math.min(steps, TERRAIN_MAX_COARSEN_STEPS);
+}
+/**
+ * Subdivides the fill of a single feature and returns the step actually used
+ *
+ * When the step was too fine to finish subdividing (the vertex budget ran out, or a single
+ * triangle sweeps too many cells), emitting it as is produces a mixture where "part of it
+ * follows the terrain while the rest are flat triangles breaking through the terrain". This is
+ * what is behind the wedge-shaped breakage sticking out of the terrain, so it is coarsened and
+ * subdivided again. Subdividing the outline with the returned step as well guarantees that the
+ * fill and the outline lie on the same grid.
+ *
+ * @returns The subdivision result and the step that produced it
+ */
+export function tessellatePolygonFill(context, featureId, partIndex, flatCoords, indices, base) {
+    // Features outside the range are left alone. Since it is already decided that they will not
+    // be subdivided, even building the vertex pool (registering every coordinate into a Map) is
+    // expensive. With 8,172 administrative boundaries and 1.1 million vertices in total, this
+    // early exit decides most of the construction time (measured: 3.9 s -> 0.5 s).
+    if (base.region && !flatCoordsIntersect(flatCoords, base.region)) {
+        return { flatCoords, indices, step: base };
+    }
+    // The subdivision cache belongs to the draw instance whose context is passed. Back when it
+    // was shared globally, triangles subdivided with a different step were returned whenever
+    // the generation happened to coincide with another instance's.
+    const fillCache = context.fillCache;
+    // The fingerprint of the conditions that decide this feature's subdivision (the covering
+    // tile configuration, the coarsening and the relationship with the range). As long as the
+    // conditions are the same it can be reused even when the range moves or a chunk is re-baked
+    const signature = fillSignature(base, flatCoords);
+    if (featureId) {
+        const cached = fillCache.get(featureId, partIndex, signature, indices);
+        if (cached) {
+            return {
+                flatCoords: cached.flatCoords,
+                indices: cached.indices,
+                step: {
+                    grid: cached.grid,
+                    maxPoints: base.maxPoints,
+                    region: base.region,
+                    tiling: cached.grid === base.grid ? base.tiling : null,
+                },
+            };
+        }
+    }
+    let step = polygonTessellationStep(base, flatCoords);
+    let result = subdivideTriangles(flatCoords, indices, step);
+    let coarsened = 0;
+    while (result.overflowed && coarsened < TERRAIN_MAX_COARSEN_STEPS) {
+        // The required factor is derived from the amount of the overflow, rounded up to a power
+        // of 2 and applied in one go (trying factor 2 at a time would mean redoing it up to the
+        // upper bound every time for a huge feature)
+        const wanted = Math.max(2, 2 ** Math.ceil(Math.log2(result.overflowFactor)));
+        const remaining = 2 ** (TERRAIN_MAX_COARSEN_STEPS - coarsened);
+        const factor = Math.min(wanted, remaining);
+        coarsened += Math.round(Math.log2(factor));
+        step = coarsen(step, factor);
+        result = subdivideTriangles(flatCoords, indices, step);
+    }
+    if (featureId) {
+        fillCache.set(featureId, partIndex, signature, indices, result.flatCoords, result.indices, step.grid);
+    }
+    return { flatCoords: result.flatCoords, indices: result.indices, step };
+}
+/**
+ * Subdivides the rings of the outline
+ *
+ * It uses the same grid as the fill, so the edge of the fill and the vertices of the outline
+ * still agree after subdivision.
+ */
+export function tessellateRings(rings, step) {
+    // Outside the range nothing is subdivided (the same test as the fill; if the two disagree
+    // they drift apart)
+    if (step.region && !ringsIntersect(rings, step.region))
+        return rings;
+    // The coarsening applied to the fill is applied to the outline too. Forgetting it would
+    // subdivide only the outline on the finest grid and make the number of points jump (both
+    // construction and rendering get heavier)
+    const coarsen = step.coarsen && step.coarsen > 1 ? step.coarsen : 1;
+    return densifyRings(rings, coarsen > 1 ? { ...step, grid: step.grid * coarsen } : step);
+}

package/dist/view/terrain/shade.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Formula for terrain shading (an aid to reading the map)
+ *
+ * There are two paths that put a polygon fill onto the ground surface: analytic drape
+ * (filling as pixels of the ground surface, `drape/renderer.ts` and `drape/quad.ts`) and
+ * vertex displacement (the path in `shaders/helpers.ts` that lifts the vertices of a
+ * feature and fills them). So that both produce the same pixels, the formula that derives
+ * the brightness factor from the gradient is kept here in a single place, and only the way
+ * the samples are taken is adapted to each path. If each path had its own formula, the
+ * brightness of the fill would jump where the bands switch over.
+ *
+ * Shading does not change the hue; it is applied to the brightness only. It is not 3D
+ * lighting that illuminates symbols with an arbitrary light, it is also distinct from
+ * vertical exaggeration of the terrain (which follows the map's own factor), and it does not
+ * change the dimensions of the relief at all.
+ */
+/**
+ * Light source for the shading
+ *
+ * It is a pair of a unit vector in the map coordinate system (east, north, up) and a
+ * strength.
+ */
+export interface TerrainShadeLight {
+    /** Unit vector in the map coordinate system (east, north, up) */
+    readonly direction: readonly [number, number, number];
+    /** Strength of the shading (0 means no shading) */
+    readonly strength: number;
+}
+/**
+ * GLSL that derives the brightness factor from the gradient
+ *
+ * The caller must declare `u_light_dir` (map coordinate system, east / north / up) and
+ * `u_shade_strength`. The unit of the gradient is meters per meter (eastward and
+ * northward), and every path converts its samples to this unit before passing them in.
+ */
+export declare const TERRAIN_SHADE_CORE_GLSL = "\nfloat terrainShadeFromGradient(float dzdEast, float dzdNorth) {\n    if (u_shade_strength <= 0.0) return 1.0;\n    vec3 normal = normalize(vec3(-dzdEast, -dzdNorth, 1.0));\n    float lambert = dot(normal, u_light_dir);\n    // The value on level ground (the normal pointing straight up). It is normalized to\n    // 1.0 here, so no shading is applied on flat places (the name flat cannot be used\n    // because it is a reserved word in GLSL)\n    float level = max(u_light_dir.z, 1e-3);\n    float factor = 1.0 + u_shade_strength * (lambert - level) / level;\n    return clamp(factor, 1.0 - u_shade_strength, 1.0 + u_shade_strength * 0.5);\n}\n";
+/**
+ * CPU mirror of `terrainShadeFromGradient`
+ *
+ * The GLSL is the authority for the implementation, but the formula itself is placed here
+ * as a pure function so that it can be verified (the same practice as `drapeShadeWindow`).
+ * Given the same samples, every path arrives at this value.
+ *
+ * @param dzdEast Eastward gradient (meters per meter)
+ * @param dzdNorth Northward gradient (meters per meter)
+ * @param light The light source
+ */
+export declare function terrainShadeFactor(dzdEast: number, dzdNorth: number, light: TerrainShadeLight): number;

package/dist/view/terrain/shade.js

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * GLSL that derives the brightness factor from the gradient
+ *
+ * The caller must declare `u_light_dir` (map coordinate system, east / north / up) and
+ * `u_shade_strength`. The unit of the gradient is meters per meter (eastward and
+ * northward), and every path converts its samples to this unit before passing them in.
+ */
+export const TERRAIN_SHADE_CORE_GLSL = `
+float terrainShadeFromGradient(float dzdEast, float dzdNorth) {
+    if (u_shade_strength <= 0.0) return 1.0;
+    vec3 normal = normalize(vec3(-dzdEast, -dzdNorth, 1.0));
+    float lambert = dot(normal, u_light_dir);
+    // The value on level ground (the normal pointing straight up). It is normalized to
+    // 1.0 here, so no shading is applied on flat places (the name flat cannot be used
+    // because it is a reserved word in GLSL)
+    float level = max(u_light_dir.z, 1e-3);
+    float factor = 1.0 + u_shade_strength * (lambert - level) / level;
+    return clamp(factor, 1.0 - u_shade_strength, 1.0 + u_shade_strength * 0.5);
+}
+`;
+/**
+ * CPU mirror of `terrainShadeFromGradient`
+ *
+ * The GLSL is the authority for the implementation, but the formula itself is placed here
+ * as a pure function so that it can be verified (the same practice as `drapeShadeWindow`).
+ * Given the same samples, every path arrives at this value.
+ *
+ * @param dzdEast Eastward gradient (meters per meter)
+ * @param dzdNorth Northward gradient (meters per meter)
+ * @param light The light source
+ */
+export function terrainShadeFactor(dzdEast, dzdNorth, light) {
+    const strength = light.strength;
+    if (strength <= 0)
+        return 1;
+    const length = Math.hypot(dzdEast, dzdNorth, 1);
+    const normal = [-dzdEast / length, -dzdNorth / length, 1 / length];
+    const dir = light.direction;
+    const lambert = normal[0] * dir[0] + normal[1] * dir[1] + normal[2] * dir[2];
+    const level = Math.max(dir[2], 1e-3);
+    const factor = 1 + (strength * (lambert - level)) / level;
+    return Math.min(Math.max(factor, 1 - strength), 1 + strength * 0.5);
+}