@sakuzu/maplibre-gl-draw 1.0.0

package/dist/display/packed-rtree.js

@@ -0,0 +1,244 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * A static R-tree packed into typed arrays (the spatial index of a dataset)
+ *
+ * The rows are ordered along a Hilbert curve of the centers of their bboxes and grouped bottom up
+ * into nodes of a fixed size. The whole tree is three typed arrays, so it is built in one pass
+ * without an object per row, and it can be built in a Worker and sent to the main thread without
+ * a copy (`prepareDatasetColumnar`). The contents of a dataset are replaced as a
+ * whole, so a tree that cannot be updated in place is enough.
+ *
+ * A pure module: it depends on nothing.
+ */
+/** The number of entries of one node */
+const DEFAULT_NODE_SIZE = 16;
+/** The side of the Hilbert grid the centers are snapped to (2^16 cells) */
+const HILBERT_SIDE = 1 << 16;
+/**
+ * Builds a packed R-tree over the bboxes of the rows
+ *
+ * A row whose bbox is NaN (a row without a geometry) is left out.
+ *
+ * @param bounds `[minX, minY, maxX, maxY]` per row
+ *
+ * @internal
+ */
+export function buildPackedRTree(bounds, nodeSize = DEFAULT_NODE_SIZE) {
+    const rowCount = bounds.length >> 2;
+    let numItems = 0;
+    for (let row = 0; row < rowCount; row++) {
+        if (!Number.isNaN(bounds[row * 4]))
+            numItems++;
+    }
+    // The level structure: leaves, then ceil(n / nodeSize) nodes per level up to a single root
+    // (an empty tree has the root alone)
+    let n = numItems;
+    let numNodes = n;
+    const levels = [n];
+    do {
+        n = Math.max(1, Math.ceil(n / nodeSize));
+        numNodes += n;
+        levels.push(numNodes);
+    } while (n !== 1);
+    const boxes = new Float64Array(numNodes * 4);
+    const indices = new Int32Array(numNodes);
+    const levelBounds = Int32Array.from(levels);
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    let leaf = 0;
+    for (let row = 0; row < rowCount; row++) {
+        const at = row * 4;
+        if (Number.isNaN(bounds[at]))
+            continue;
+        boxes[leaf * 4] = bounds[at];
+        boxes[leaf * 4 + 1] = bounds[at + 1];
+        boxes[leaf * 4 + 2] = bounds[at + 2];
+        boxes[leaf * 4 + 3] = bounds[at + 3];
+        indices[leaf] = row;
+        if (bounds[at] < minX)
+            minX = bounds[at];
+        if (bounds[at + 1] < minY)
+            minY = bounds[at + 1];
+        if (bounds[at + 2] > maxX)
+            maxX = bounds[at + 2];
+        if (bounds[at + 3] > maxY)
+            maxY = bounds[at + 3];
+        leaf++;
+    }
+    if (numItems === 0) {
+        // An empty tree: a root that nothing intersects
+        boxes.set([
+            Number.POSITIVE_INFINITY,
+            Number.POSITIVE_INFINITY,
+            Number.NEGATIVE_INFINITY,
+            Number.NEGATIVE_INFINITY,
+        ]);
+        return { nodeSize, numItems, boxes, indices, levelBounds };
+    }
+    if (numItems > nodeSize) {
+        // Order the leaves along the Hilbert curve of their centers
+        const width = maxX - minX || 1;
+        const height = maxY - minY || 1;
+        const values = new Float64Array(numItems);
+        const scale = HILBERT_SIDE - 1;
+        for (let i = 0; i < numItems; i++) {
+            const cx = (boxes[i * 4] + boxes[i * 4 + 2]) / 2;
+            const cy = (boxes[i * 4 + 1] + boxes[i * 4 + 3]) / 2;
+            const x = Math.floor((scale * (cx - minX)) / width);
+            const y = Math.floor((scale * (cy - minY)) / height);
+            values[i] = hilbertIndex(x, y);
+        }
+        sortLeaves(values, boxes, indices, 0, numItems - 1, nodeSize);
+    }
+    // Build the nodes level by level, bottom up
+    let pos = 0;
+    let write = numItems;
+    for (let level = 0; level < levelBounds.length - 1; level++) {
+        const end = levelBounds[level];
+        while (pos < end) {
+            const first = pos;
+            let nodeMinX = Number.POSITIVE_INFINITY;
+            let nodeMinY = Number.POSITIVE_INFINITY;
+            let nodeMaxX = Number.NEGATIVE_INFINITY;
+            let nodeMaxY = Number.NEGATIVE_INFINITY;
+            for (let j = 0; j < nodeSize && pos < end; j++, pos++) {
+                if (boxes[pos * 4] < nodeMinX)
+                    nodeMinX = boxes[pos * 4];
+                if (boxes[pos * 4 + 1] < nodeMinY)
+                    nodeMinY = boxes[pos * 4 + 1];
+                if (boxes[pos * 4 + 2] > nodeMaxX)
+                    nodeMaxX = boxes[pos * 4 + 2];
+                if (boxes[pos * 4 + 3] > nodeMaxY)
+                    nodeMaxY = boxes[pos * 4 + 3];
+            }
+            boxes[write * 4] = nodeMinX;
+            boxes[write * 4 + 1] = nodeMinY;
+            boxes[write * 4 + 2] = nodeMaxX;
+            boxes[write * 4 + 3] = nodeMaxY;
+            indices[write] = first;
+            write++;
+        }
+    }
+    return { nodeSize, numItems, boxes, indices, levelBounds };
+}
+/**
+ * Returns the rows whose bbox intersects the box (the edges count as intersecting), in no
+ * particular order
+ *
+ * @param out The array the rows are appended to
+ *
+ * @internal
+ */
+export function searchPackedRTree(tree, minX, minY, maxX, maxY, out = []) {
+    const { boxes, indices, levelBounds, nodeSize, numItems } = tree;
+    if (numItems === 0)
+        return out;
+    const queue = [];
+    let node = levelBounds[levelBounds.length - 1] - 1;
+    while (node !== undefined) {
+        const end = Math.min(node + nodeSize, levelEnd(levelBounds, node));
+        for (let pos = node; pos < end; pos++) {
+            const at = pos * 4;
+            if (maxX < boxes[at] ||
+                maxY < boxes[at + 1] ||
+                minX > boxes[at + 2] ||
+                minY > boxes[at + 3]) {
+                continue;
+            }
+            if (node < numItems)
+                out.push(indices[pos]);
+            else
+                queue.push(indices[pos]);
+        }
+        node = queue.pop();
+    }
+    return out;
+}
+/** The end of the level that the position belongs to */
+function levelEnd(levelBounds, position) {
+    let lo = 0;
+    let hi = levelBounds.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (levelBounds[mid] > position)
+            hi = mid;
+        else
+            lo = mid + 1;
+    }
+    return levelBounds[lo];
+}
+/**
+ * The distance along the Hilbert curve of a cell of the 2^16 grid
+ */
+function hilbertIndex(cellX, cellY) {
+    let x = cellX;
+    let y = cellY;
+    let d = 0;
+    for (let s = HILBERT_SIDE >> 1; s > 0; s >>= 1) {
+        const rx = (x & s) > 0 ? 1 : 0;
+        const ry = (y & s) > 0 ? 1 : 0;
+        d += s * s * ((3 * rx) ^ ry);
+        if (ry === 0) {
+            if (rx === 1) {
+                x = HILBERT_SIDE - 1 - x;
+                y = HILBERT_SIDE - 1 - y;
+            }
+            const t = x;
+            x = y;
+            y = t;
+        }
+    }
+    return d;
+}
+/**
+ * Sorts the leaves by their Hilbert value (quicksort on the parallel arrays)
+ *
+ * The order only matters between nodes, so a range that falls within one node is left as it is.
+ */
+function sortLeaves(values, boxes, indices, left, right, nodeSize) {
+    let lo = left;
+    let hi = right;
+    while (Math.floor(lo / nodeSize) < Math.floor(hi / nodeSize)) {
+        const pivot = values[(lo + hi) >> 1];
+        let i = lo - 1;
+        let j = hi + 1;
+        while (true) {
+            do
+                i++;
+            while (values[i] < pivot);
+            do
+                j--;
+            while (values[j] > pivot);
+            if (i >= j)
+                break;
+            swapLeaves(values, boxes, indices, i, j);
+        }
+        // Recurse into the smaller side, loop on the larger one (the stack stays shallow)
+        if (j - lo < hi - j) {
+            sortLeaves(values, boxes, indices, lo, j, nodeSize);
+            lo = j + 1;
+        }
+        else {
+            sortLeaves(values, boxes, indices, j + 1, hi, nodeSize);
+            hi = j;
+        }
+    }
+}
+function swapLeaves(values, boxes, indices, i, j) {
+    const value = values[i];
+    values[i] = values[j];
+    values[j] = value;
+    const index = indices[i];
+    indices[i] = indices[j];
+    indices[j] = index;
+    const a = i * 4;
+    const b = j * 4;
+    for (let k = 0; k < 4; k++) {
+        const box = boxes[a + k];
+        boxes[a + k] = boxes[b + k];
+        boxes[b + k] = box;
+    }
+}

package/dist/display/partition.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/display/partition.js

@@ -0,0 +1,226 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The splitting of the rows of a dataset into spatial chunks
+ *
+ * A pure function over typed arrays: it depends on neither the features, nor maplibre, nor
+ * WebGL, so it runs in a Worker as well (`prepareDatasetColumnar` calls it there). Both kinds of
+ * contents use it: the features (`chunk.ts` computes the per-row arrays from them) and the
+ * columnar input (`columnar/prepare.ts`).
+ *
+ * The rule: the rows are cut in half at the median of the centers of their bboxes (the way a k-d
+ * tree is built) until a range holds at most the target number of rows and the target number of
+ * vertices. Within a chunk the rows keep their original order (the draw order), and the chunks
+ * are ordered by the first row they hold.
+ */
+/**
+ * Target number of features per chunk
+ *
+ * A chunk is also "the unit of work built in one frame". With terrain, building a chunk includes
+ * the subdivision and takes 0.2 to 0.5 seconds for 500 features (measured). Lowering the count
+ * makes the hitch per frame smaller at the cost of more draw calls. 96 was taken from "about
+ * 50 ms per chunk with terrain" (it was lowered from 192 because building got heavier once the
+ * step was matched to the real mesh of the tiles).
+ *
+ * @internal
+ */
+export const CHUNK_TARGET_SIZE = 96;
+/**
+ * Target number of vertices per chunk
+ *
+ * Cutting by the count alone lets a single feature such as a municipal boundary with 130,000
+ * vertices bring in the work of dozens of features. Measured, building the chunk that contained
+ * that one feature (63 features, 226,000 vertices in total) took 1.4 seconds even with the
+ * terrain off. A chunk is "the unit of work built in one frame", so it is cut by the number of
+ * vertices as well.
+ *
+ * 40,000 was taken from "about 0.2 seconds per chunk with the terrain off". A feature that
+ * exceeds it on its own cannot be split any further, so it becomes a chunk of that one feature.
+ *
+ * @internal
+ */
+export const CHUNK_TARGET_VERTICES = 40000;
+/**
+ * Target number of features per chunk for a large dataset
+ *
+ * @internal
+ */
+export const LARGE_CHUNK_TARGET_SIZE = 4096;
+/**
+ * The count at which the target number is raised
+ *
+ * @internal
+ */
+export const LARGE_DATASET_THRESHOLD = 50000;
+/**
+ * Returns the target number of features per chunk for the total count of a dataset
+ *
+ * A chunk is also the unit of drawing, so as their number grows, "switching the program and
+ * setting the uniforms" happens that many times per frame. Cutting 260,000 features in steps of
+ * 512 gives several hundred visible chunks, and that procedure costs more than the drawing
+ * itself.
+ *
+ * The culling gets coarser, but the bbox intersection of a chunk is cheap per frame and, coarse
+ * or not, the total number of vertices the GPU processes does not change (the vertices outside
+ * the screen are dropped at the clipping stage). The target number is therefore raised for a
+ * large dataset.
+ *
+ * @internal
+ */
+export function chunkTargetSizeFor(count) {
+    return count > LARGE_DATASET_THRESHOLD ? LARGE_CHUNK_TARGET_SIZE : CHUNK_TARGET_SIZE;
+}
+/**
+ * Splits the rows into spatial chunks
+ *
+ * A row whose bbox is NaN (a row without a geometry) is left out.
+ *
+ * It used to be "cut the whole bbox into a grid and assign a feature to the cell its bbox center
+ * falls into". That form breaks as soon as a single extremely wide feature (the outline of a
+ * whole country, a feature crossing the date line) is mixed in. The whole bbox grows to the size
+ * of the world because of that one feature, and so do the cells of the grid, so everything else
+ * falls into a single cell. Cutting at the median evens out the counts regardless of the
+ * distribution. An outlier goes into its own side as a single row and does not distort the rest
+ * of the splitting.
+ *
+ * @param bounds The bboxes, `[minX, minY, maxX, maxY]` per row
+ * @param vertexCounts The number of vertices per row (the estimate of the work)
+ * @param targetSize The target number of rows per chunk (decided from the number of rows with a
+ *   geometry when omitted)
+ *
+ * @internal
+ */
+export function partitionRows(bounds, vertexCounts, targetSize) {
+    const rowCount = bounds.length >> 2;
+    const order = new Int32Array(rowCount);
+    let count = 0;
+    for (let row = 0; row < rowCount; row++) {
+        if (!Number.isNaN(bounds[row * 4]))
+            order[count++] = row;
+    }
+    if (count === 0) {
+        return { rows: new Int32Array(0), offsets: new Int32Array(1), bounds: new Float64Array(0) };
+    }
+    const target = targetSize ?? chunkTargetSizeFor(count);
+    const centerX = new Float64Array(rowCount);
+    const centerY = new Float64Array(rowCount);
+    for (let i = 0; i < count; i++) {
+        const at = order[i] * 4;
+        centerX[order[i]] = (bounds[at] + bounds[at + 2]) / 2;
+        centerY[order[i]] = (bounds[at + 1] + bounds[at + 3]) / 2;
+    }
+    /** The ranges of `order` that became chunks */
+    const ranges = [];
+    splitRange(0, count);
+    // Put the rows of each chunk back into the draw order, then order the chunks by their first row
+    for (const [from, to] of ranges)
+        order.subarray(from, to).sort();
+    ranges.sort((a, b) => order[a[0]] - order[b[0]]);
+    const rows = new Int32Array(count);
+    const offsets = new Int32Array(ranges.length + 1);
+    const chunkBounds = new Float64Array(ranges.length * 4);
+    let written = 0;
+    for (let c = 0; c < ranges.length; c++) {
+        const [from, to] = ranges[c];
+        offsets[c] = written;
+        let minX = Number.POSITIVE_INFINITY;
+        let minY = Number.POSITIVE_INFINITY;
+        let maxX = Number.NEGATIVE_INFINITY;
+        let maxY = Number.NEGATIVE_INFINITY;
+        for (let i = from; i < to; i++) {
+            const row = order[i];
+            rows[written++] = row;
+            const at = row * 4;
+            if (bounds[at] < minX)
+                minX = bounds[at];
+            if (bounds[at + 1] < minY)
+                minY = bounds[at + 1];
+            if (bounds[at + 2] > maxX)
+                maxX = bounds[at + 2];
+            if (bounds[at + 3] > maxY)
+                maxY = bounds[at + 3];
+        }
+        chunkBounds[c * 4] = minX;
+        chunkBounds[c * 4 + 1] = minY;
+        chunkBounds[c * 4 + 2] = maxX;
+        chunkBounds[c * 4 + 3] = maxY;
+    }
+    offsets[ranges.length] = written;
+    return { rows, offsets, bounds: chunkBounds };
+    /**
+     * Cuts the range [from, to) at the median down to the target count
+     */
+    function splitRange(from, to) {
+        const size = to - from;
+        if (size <= 1) {
+            ranges.push([from, to]);
+            return;
+        }
+        let vertices = 0;
+        for (let i = from; i < to; i++)
+            vertices += vertexCounts[order[i]];
+        if (size <= target && vertices <= CHUNK_TARGET_VERTICES) {
+            ranges.push([from, to]);
+            return;
+        }
+        // Cut along the axis with the larger extent
+        let minCX = Number.POSITIVE_INFINITY;
+        let maxCX = Number.NEGATIVE_INFINITY;
+        let minCY = Number.POSITIVE_INFINITY;
+        let maxCY = Number.NEGATIVE_INFINITY;
+        for (let i = from; i < to; i++) {
+            const row = order[i];
+            if (centerX[row] < minCX)
+                minCX = centerX[row];
+            if (centerX[row] > maxCX)
+                maxCX = centerX[row];
+            if (centerY[row] < minCY)
+                minCY = centerY[row];
+            if (centerY[row] > maxCY)
+                maxCY = centerY[row];
+        }
+        // If the centers are concentrated at a single point, cutting does not separate them (it only
+        // adds chunks with the same bbox), so it stops there
+        if (maxCX === minCX && maxCY === minCY) {
+            ranges.push([from, to]);
+            return;
+        }
+        const axis = maxCX - minCX >= maxCY - minCY ? centerX : centerY;
+        const mid = from + (size >> 1);
+        selectNth(axis, from, to, mid);
+        splitRange(from, mid);
+        splitRange(mid, to);
+    }
+    /**
+     * Rearranges the range so that the element at mid becomes the median (quickselect)
+     */
+    function selectNth(axis, from, to, nth) {
+        let lo = from;
+        let hi = to - 1;
+        while (lo < hi) {
+            // The middle value is used as the pivot (so that sorted input does not hit the worst case)
+            const pivot = axis[order[(lo + hi) >> 1]];
+            let i = lo;
+            let j = hi;
+            while (i <= j) {
+                while (axis[order[i]] < pivot)
+                    i++;
+                while (axis[order[j]] > pivot)
+                    j--;
+                if (i <= j) {
+                    const swap = order[i];
+                    order[i] = order[j];
+                    order[j] = swap;
+                    i++;
+                    j--;
+                }
+            }
+            if (nth <= j)
+                hi = j;
+            else if (nth >= i)
+                lo = i;
+            else
+                return;
+        }
+    }
+}

package/dist/display/provider.d.ts

@@ -0,0 +1 @@
+export {};