@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/terrain/detect.js

@@ -0,0 +1,198 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * A reusable container for elevation lookups
+ *
+ * Hit testing looks up the elevation for each vertex, so per-point allocation is avoided.
+ * The MapLibre side only reads the values and does not keep the reference.
+ */
+const elevationQuery = {
+    lng: 0,
+    lat: 0,
+    wrap() {
+        return this;
+    },
+};
+/**
+ * Gets the elevation of a single point from the DEM tile of one zoom level (in meters)
+ *
+ * This is the fallback of `groundElevationMeters` (`ground.ts`) for points no drawn tile
+ * covers. When it cannot be obtained (no terrain / the DEM has not arrived / the function is
+ * missing due to a version difference) 0 is returned. Here 0 does not mean "sea level" but
+ * "do not add an elevation", and the result is exactly the same as the rendering and hit
+ * testing before the terrain was introduced.
+ *
+ * @param tileZoom The same value as MapLibre's `transform.tileZoom` (= floor(zoom))
+ */
+export function getTerrainElevationMeters(terrain, lng, lat, tileZoom) {
+    const query = terrain?.getElevationForLngLatZoom;
+    if (typeof query !== 'function')
+        return 0;
+    elevationQuery.lng = lng;
+    elevationQuery.lat = lat;
+    let elevation;
+    try {
+        elevation = query.call(terrain, elevationQuery, tileZoom);
+    }
+    catch {
+        return 0;
+    }
+    return Number.isFinite(elevation) ? elevation : 0;
+}
+/**
+ * Extracts the camera position (in Mercator)
+ *
+ * The occlusion test for symbols (`occlusion.ts`) uses it to draw a segment from the
+ * camera to the anchor.
+ *
+ * `transform.cameraPosition` is not used. That one is "the same space as the 3D features
+ * of that projection", and in measurements its units are mixed, with x and y in world
+ * pixels and z on yet another scale, so the factor for converting it into this Mercator
+ * space depends on the version. Instead it is assembled from `getCameraLngLat()` and
+ * `getCameraAltitude()`, because their meaning is unambiguous and they can be written in
+ * the same "longitude and latitude + meters" language as the elevation of the anchor.
+ *
+ * The location of transform differs between versions (v6 has `map.painter.transform`, v5
+ * has `map.transform`). In environments where it is absent null is returned, and the
+ * occlusion test falls back to "not occluded".
+ */
+export function getCameraMercator(map, elevationScale) {
+    if (!map || !(elevationScale > 0))
+        return null;
+    const holder = map;
+    const transform = holder.transform ?? holder.painter?.transform;
+    if (!transform)
+        return null;
+    if (typeof transform.getCameraLngLat !== 'function')
+        return null;
+    if (typeof transform.getCameraAltitude !== 'function')
+        return null;
+    let lngLat;
+    let altitude;
+    try {
+        lngLat = transform.getCameraLngLat();
+        altitude = transform.getCameraAltitude();
+    }
+    catch {
+        return null;
+    }
+    if (!lngLat || !Number.isFinite(lngLat.lng) || !Number.isFinite(lngLat.lat))
+        return null;
+    if (!Number.isFinite(altitude))
+        return null;
+    const x = (lngLat.lng + 180) / 360;
+    const latRad = (lngLat.lat * Math.PI) / 180;
+    const y = (1 - Math.log(Math.tan(latRad) + 1 / Math.cos(latRad)) / Math.PI) / 2;
+    if (!Number.isFinite(x) || !Number.isFinite(y))
+        return null;
+    return [x, y, altitude * elevationScale];
+}
+/**
+ * The vertical exaggeration MapLibre applies to the terrain
+ *
+ * MapLibre multiplies every elevation by this factor: the terrain mesh it draws
+ * (`u_terrain_exaggeration` of `getTerrainData`) and `queryTerrainElevation`, which the
+ * anchors use (`ground.ts`). So that polygons, lines and symbols sit on the same surface as the map, every
+ * GPU path here (the DEM atlas and the drape) multiplies by the same factor.
+ *
+ * The factor is read from the terrain object itself (`terrain.exaggeration`, present in v5
+ * and v6), which is the very field MapLibre multiplies by, rather than from
+ * `map.getTerrain()`, which returns the specification as passed and can leave the factor
+ * undefined. When the field is missing, the specification (`terrain.options`) is consulted,
+ * and failing that 1 (MapLibre's default) is returned. A negative or non-finite value is
+ * treated as missing.
+ */
+export function getTerrainExaggeration(terrain) {
+    if (!terrain)
+        return 1;
+    const own = terrain.exaggeration;
+    if (typeof own === 'number' && Number.isFinite(own) && own >= 0)
+        return own;
+    const spec = terrain.options?.exaggeration;
+    if (typeof spec === 'number' && Number.isFinite(spec) && spec >= 0)
+        return spec;
+    return 1;
+}
+/** The number of subdivisions of MapLibre's terrain mesh (128 by default) */
+export function getTerrainMeshSize(terrain) {
+    const size = terrain.meshSize;
+    return typeof size === 'number' && Number.isFinite(size) && size > 0 ? size : 128;
+}
+/**
+ * Extracts the terrain object from the map (null when it is disabled)
+ */
+export function getMapTerrain(map) {
+    if (!map)
+        return null;
+    const terrain = map.terrain;
+    if (!terrain || typeof terrain !== 'object')
+        return null;
+    const candidate = terrain;
+    if (typeof candidate.getTerrainData !== 'function')
+        return null;
+    return candidate;
+}
+/**
+ * Enumerates the terrain tiles to be rendered
+ *
+ * In v6 they live in `tileManager`, in v5 in `sourceCache`. When neither exists, an empty
+ * result is returned.
+ */
+export function getRenderableTerrainTiles(terrain) {
+    const holder = terrain;
+    const manager = holder.tileManager ?? holder.sourceCache;
+    if (!manager || typeof manager.getRenderableTiles !== 'function')
+        return [];
+    let tiles;
+    try {
+        tiles = manager.getRenderableTiles();
+    }
+    catch {
+        return [];
+    }
+    const result = [];
+    for (const tile of tiles) {
+        const tileID = tile?.tileID;
+        const canonical = tileID?.canonical;
+        if (!canonical)
+            continue;
+        if (!Number.isFinite(canonical.x) ||
+            !Number.isFinite(canonical.y) ||
+            !Number.isFinite(canonical.z)) {
+            continue;
+        }
+        const wrap = tileID.wrap;
+        result.push({
+            x: canonical.x,
+            y: canonical.y,
+            z: canonical.z,
+            wrap: typeof wrap === 'number' && Number.isFinite(wrap) ? wrap : 0,
+            tileID,
+        });
+    }
+    return result;
+}
+/**
+ * Extracts the DEM rendering data for one tile (null when something is missing)
+ */
+export function getTerrainTileData(terrain, tile) {
+    let data;
+    try {
+        data = terrain.getTerrainData(tile.tileID);
+    }
+    catch {
+        return null;
+    }
+    if (!data || typeof data !== 'object')
+        return null;
+    const record = data;
+    const texture = record.texture;
+    const matrix = record.u_terrain_matrix;
+    const unpack = record.u_terrain_unpack;
+    const dim = record.u_terrain_dim;
+    if (!texture || !matrix || !unpack || typeof dim !== 'number' || dim <= 0)
+        return null;
+    if (matrix.length < 16 || unpack.length < 4)
+        return null;
+    return { texture, matrix, unpack, dim, exaggeration: getTerrainExaggeration(terrain) };
+}

package/dist/view/terrain/drape/bin-store.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Storage of the binning results of the analytic drape
+ *
+ * The analytic drape of polygons and lines is built on "a per-tile index (the bins)". The
+ * index changes only on an edit or a change of the view, so it is cached per tile and only the
+ * tiles that newly entered the view are built, within the frame's budget.
+ *
+ * Two disciplines are upheld here.
+ *
+ * - No re-binning every frame. Even during a pan, only the new tiles are rebuilt
+ * - Drawing continues with the previous version while a rebuild is in progress. When the
+ *   features or the styles change, the old version (active) is drawn until the new version
+ *   (pending) has all the tiles of the view. The index and the element order are swapped as a
+ *   pair (mixing them midway swaps the colors)
+ *
+ * Once the amount retained exceeds the upper bound, only the tiles of the view are kept and
+ * the arrays are repacked (the bins are still held, so it takes only a repacking of the
+ * arrays, not a rebuild).
+ */
+import type { DrapeElement, DrapeQuadBreak, DrapeTile, TileBins } from './binning.js';
+/** The number of style texels per element */
+export declare const DRAPE_STYLE_TEXELS = 4;
+/**
+ * The index of the texel the selection highlight uses within the style table
+ *
+ * 0 = fill, 1 = stroke, 2 = specifications (width, kind, source, reference zoom), 3 =
+ * selection. The selection alone is put in a separate texel so that the index (the binning)
+ * need not be touched at all when the selection changes. Mixing it into the same texel as the
+ * color or the width would mean rebuilding the other values too on every rewrite.
+ */
+export declare const DRAPE_SELECTION_TEXEL = 3;
+/** The upper bound on the number of edge texels (16 bytes per texel, so 1M is 16MB) */
+export declare const DRAPE_MAX_EDGE_TEXELS = 1048576;
+/** The key of a tile */
+export declare function drapeTileKey(tile: DrapeTile): string;
+/** The position of one packed tile */
+export interface DrapeTileEntry {
+    /** A tile that cannot be put through the analytic evaluation (it is not drawn) */
+    readonly unfit: boolean;
+    readonly grid: number;
+    /** The starting position within the cell index texture (in texels) */
+    readonly cellOffset: number;
+    /** The binning result (used when repacking) */
+    readonly bins: TileBins;
+    /** The number of the frame it was used in most recently */
+    lastUsed: number;
+}
+/**
+ * The arrays packed into the data textures (append-only)
+ *
+ * Adding a tile only piles it onto the end, so the transfer to the GPU is limited to the rows
+ * that were added (the renderer remembers the position it has transferred up to).
+ */
+export declare class DrapePackBuilder {
+    private static nextId;
+    /** The identity of this version (with which the renderer tells whether it has been
+     * transferred) */
+    readonly id: number;
+    edges: Float32Array<ArrayBuffer>;
+    edgeCount: number;
+    runs: Float32Array<ArrayBuffer>;
+    runCount: number;
+    cells: Float32Array<ArrayBuffer>;
+    cellCount: number;
+    styles: Float32Array<ArrayBuffer>;
+    elementCount: number;
+    /**
+     * The version of the selection (when it changes, the style table is sent again)
+     *
+     * Edges, runs and cells are append-only so sending only the added rows is enough, but the
+     * selection rewrites rows that have already been sent. The renderer tells a rewrite apart by
+     * this version.
+     */
+    selectionVersion: number;
+    /** The number of elements with the selection mark raised (for diagnostics) */
+    markedCount: number;
+    /** Builds the style table (only when the element order changes) */
+    setElements(elements: readonly DrapeElement[]): void;
+    /**
+     * Rewrites the marks of the selection highlight
+     *
+     * What is rewritten is only one texel of the style table (`DRAPE_SELECTION_TEXEL`); the
+     * index (edges, runs, cells) is not touched at all. The selection changes with a single
+     * click, whereas rebuilding the index takes several hundred milliseconds for 8,172
+     * administrative boundaries, so it cannot be rebuilt on every selection.
+     *
+     * @returns Whether anything actually changed (it is transferred again only when it did)
+     */
+    setSelection(elements: readonly DrapeElement[], selected: ReadonlySet<string>): boolean;
+    /** Piles one tile onto the end */
+    addTile(bins: TileBins): number;
+}
+/** The result of the preparation */
+export interface DrapePrepareResult {
+    /** The estimate of the tile with the most edges among the tiles of the view (diagnostic) */
+    readonly maxTileEdges: number;
+    /** The maximum number of edges that fell into one cell (diagnostic) */
+    readonly maxEdgesPerCell: number;
+    /** The maximum number of runs that fell into one cell (diagnostic) */
+    readonly maxRunsPerCell: number;
+    /** The number of cells truncated for exceeding the budget (diagnostic) */
+    readonly truncatedCells: number;
+    /** The number of tiles that could not be put through the analytic evaluation (diagnostic) */
+    readonly unfitTiles: number;
+    /** Whether all the tiles drawable in this frame are ready (it draws even when they are
+     * not) */
+    readonly complete: boolean;
+    /** Whether anything is left over (it then requests another frame) */
+    readonly pending: boolean;
+    /** Whether there was a cell that exceeded the budget */
+    readonly overflow: boolean;
+    /** The number of tiles built in this frame */
+    readonly built: number;
+}
+/**
+ * The store of the tile indices
+ */
+export declare class DrapeTileStore {
+    private active;
+    private pending;
+    private frame;
+    /** The keys of the features currently selected (drapeSelectionKey in `binning.ts`) */
+    private selection;
+    /**
+     * Announces the element order
+     *
+     * When the version changes, a new version is started. The old version can keep being drawn
+     * as it is.
+     */
+    sync(revision: string, elements: readonly DrapeElement[], quadBreaks?: readonly DrapeQuadBreak[], entryStarts?: ReadonlyMap<string, number>, aboveStoreStart?: number): void;
+    /**
+     * Announces the targets of the selection highlight (the rendering side calls it every frame)
+     *
+     * It does nothing when the contents are the same. Scanning all the elements every frame with
+     * the same set would be a wasted scan per frame for 8,172 administrative boundaries. How
+     * they are drawn is held in the per-version style table, so the same selection is copied
+     * into the version under construction (pending) as well.
+     */
+    setSelection(selected: ReadonlySet<string>): void;
+    /**
+     * Prepares the indices of the tiles of the view
+     *
+     * @param tiles The terrain tiles of the view
+     * @param budgetMs The time that may be used in this frame (at least one tile is always
+     *   built; at 0 or less, not a single one is built)
+     * @param zoom The current zoom (used to estimate the line width, which decides the margin of
+     *   the index)
+     */
+    prepare(tiles: readonly DrapeTile[], budgetMs: number, zoom?: number): DrapePrepareResult;
+    /** The version used for rendering */
+    get pack(): DrapePackBuilder | null;
+    /** The number of elements of the version used for rendering */
+    get elementCount(): number;
+    /**
+     * The breaks in the stacking order of the version used for rendering (the positions of the
+     * images)
+     *
+     * It returns those of the version being drawn right now, not of the version that was just
+     * collected. While a rebuild is in progress the old version keeps being drawn, so making
+     * only the breaks new would make the indices disagree with the element list and the
+     * segmented rendering would paint a different element or paint nothing.
+     */
+    get quadBreaks(): readonly DrapeQuadBreak[];
+    /** The starting position of each entry of the stack, in the version being drawn */
+    get entryStarts(): ReadonlyMap<string, number>;
+    /** The index at which the datasets above the stack begin, in the version being drawn */
+    get aboveStoreStart(): number;
+    /** The position of one tile */
+    entryOf(tile: DrapeTile): DrapeTileEntry | undefined;
+    /** Throws everything away */
+    clear(): void;
+    /**
+     * Once the amount retained exceeds the upper bound, keeps only the tiles of the view and
+     * repacks
+     *
+     * The bins are still held, so it takes only a repacking of the arrays, not a rebuild.
+     */
+    private compactIfNeeded;
+}