@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/dist/table/builder.js

@@ -0,0 +1,381 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/** The number of offset arrays of each geometry type */
+const OFFSET_LEVELS = {
+    Point: 0,
+    LineString: 1,
+    MultiPoint: 1,
+    Polygon: 2,
+    MultiLineString: 2,
+    MultiPolygon: 3,
+};
+/** The initial number of rows when no capacity is given */
+const DEFAULT_CAPACITY = 64;
+/** A Float64Array that grows as values are pushed */
+class GrowingFloat64 {
+    constructor(capacity) {
+        Object.defineProperty(this, "data", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "length", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        this.data = new Float64Array(Math.max(4, capacity));
+    }
+    push2(a, b) {
+        if (this.length + 2 > this.data.length) {
+            const next = new Float64Array(Math.max(this.data.length * 2, this.length + 2));
+            next.set(this.data);
+            this.data = next;
+        }
+        this.data[this.length++] = a;
+        this.data[this.length++] = b;
+    }
+    /** A copy of exactly the pushed values */
+    finish() {
+        return this.data.slice(0, this.length);
+    }
+}
+/** An Int32Array that grows as values are pushed */
+class GrowingInt32 {
+    constructor(capacity) {
+        Object.defineProperty(this, "data", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "length", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        this.data = new Int32Array(Math.max(4, capacity));
+    }
+    push(value) {
+        if (this.length + 1 > this.data.length) {
+            const next = new Int32Array(this.data.length * 2);
+            next.set(this.data);
+            this.data = next;
+        }
+        this.data[this.length++] = value;
+    }
+    get(index) {
+        return this.data[index];
+    }
+    /** The last value pushed */
+    last() {
+        return this.data[this.length - 1];
+    }
+    /** A copy of exactly the pushed values */
+    finish() {
+        return this.data.slice(0, this.length);
+    }
+}
+/** The geometry column of one geometry type, collected row by row */
+class GeometryColumnBuilder {
+    constructor(type, capacity) {
+        Object.defineProperty(this, "type", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: type
+        });
+        /** The number of rows collected */
+        Object.defineProperty(this, "rows", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "coords", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The offset arrays, outermost first; each starts with 0 */
+        Object.defineProperty(this, "offsets", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        this.coords = new GrowingFloat64(capacity * 2);
+        for (let level = 0; level < OFFSET_LEVELS[type]; level++) {
+            const offsets = new GrowingInt32(capacity + 1);
+            offsets.push(0);
+            this.offsets.push(offsets);
+        }
+    }
+    /** The number of coordinates collected */
+    get vertexCount() {
+        return this.coords.length / 2;
+    }
+    pushPositions(positions) {
+        for (const position of positions)
+            this.coords.push2(position[0], position[1]);
+    }
+    /** Closes an element of an offset level at the current end of the level below it */
+    close(level) {
+        const below = level + 1 < this.offsets.length ? this.offsets[level + 1].length - 1 : null;
+        this.offsets[level].push(below ?? this.vertexCount);
+    }
+    /** Adds the coordinates of one row, shaped as for the type of the column */
+    add(coordinates) {
+        switch (this.type) {
+            case 'Point': {
+                const position = coordinates;
+                this.coords.push2(position[0], position[1]);
+                break;
+            }
+            case 'LineString':
+            case 'MultiPoint':
+                this.pushPositions(coordinates);
+                this.close(0);
+                break;
+            case 'Polygon':
+            case 'MultiLineString':
+                for (const ring of coordinates) {
+                    this.pushPositions(ring);
+                    this.close(1);
+                }
+                this.close(0);
+                break;
+            case 'MultiPolygon':
+                for (const polygon of coordinates) {
+                    for (const ring of polygon) {
+                        this.pushPositions(ring);
+                        this.close(2);
+                    }
+                    this.close(1);
+                }
+                this.close(0);
+                break;
+        }
+        this.rows++;
+    }
+    /** The column as collected: one row per row added */
+    finish() {
+        const geometry = { type: this.type, coords: this.coords.finish() };
+        if (this.offsets.length > 0)
+            geometry.offsets = this.offsets.map((o) => o.finish());
+        return geometry;
+    }
+    /**
+     * The column spread over the rows of the table, with an empty run (NaN coordinates for a
+     * Point) for every row without a geometry
+     *
+     * @param childOf The child of every row of the table (negative for a row without a geometry)
+     * @param length The number of rows of the table
+     */
+    finishSpread(childOf, length) {
+        if (this.type === 'Point') {
+            const source = this.coords.finish();
+            const coords = new Float64Array(length * 2);
+            let k = 0;
+            for (let row = 0; row < length; row++) {
+                if (childOf[row] < 0) {
+                    coords[row * 2] = Number.NaN;
+                    coords[row * 2 + 1] = Number.NaN;
+                }
+                else {
+                    coords[row * 2] = source[k * 2];
+                    coords[row * 2 + 1] = source[k * 2 + 1];
+                    k++;
+                }
+            }
+            return { type: 'Point', coords };
+        }
+        const outer = this.offsets[0];
+        const first = new Int32Array(length + 1);
+        let k = 0;
+        for (let row = 0; row < length; row++) {
+            if (childOf[row] >= 0)
+                k++;
+            first[row + 1] = outer.get(k);
+        }
+        return {
+            type: this.type,
+            coords: this.coords.finish(),
+            offsets: [first, ...this.offsets.slice(1).map((o) => o.finish())],
+        };
+    }
+}
+/** Whether a GeoJSON geometry type is one a table holds */
+function isTableGeometryType(type) {
+    return type in OFFSET_LEVELS;
+}
+/**
+ * Creates a builder that makes a table from rows added one at a time.
+ *
+ * The coordinates are collected into growing typed arrays in the layout of GeoArrow. When every
+ * row has the same geometry type the table has one geometry column of that type; otherwise it
+ * has a mixed geometry column. An attribute whose values are all numbers (or null) becomes a
+ * `Float64Array` with NaN for null; any other attribute becomes a plain array.
+ *
+ * @param options `geometryType` fixes the geometry type of every row (a geometry of another
+ *   type throws), and gives the type of a table without any geometry. `capacity` is the
+ *   expected number of rows, to size the arrays from the start. `columns` limits the attributes
+ *   that become columns to these names (every one is created, even if no row has it)
+ * @returns A new builder
+ */
+export function createTableBuilder(options) {
+    const fixedType = options?.geometryType;
+    const capacity = Math.max(1, Math.floor(options?.capacity ?? DEFAULT_CAPACITY));
+    const fixedColumns = options?.columns !== undefined;
+    let length = 0;
+    let finished = false;
+    /** The child of every row (-1 for a row without a geometry) */
+    let childOf = new Int8Array(capacity);
+    /** The row within its child of every row */
+    let childRow = new Int32Array(capacity);
+    const children = [];
+    const childByType = new Map();
+    const columns = new Map();
+    for (const name of options?.columns ?? [])
+        columns.set(name, { values: [], numeric: true });
+    let ids = null;
+    const ensureRowCapacity = () => {
+        if (length < childOf.length)
+            return;
+        const nextOf = new Int8Array(childOf.length * 2);
+        nextOf.set(childOf);
+        childOf = nextOf;
+        const nextRow = new Int32Array(childRow.length * 2);
+        nextRow.set(childRow);
+        childRow = nextRow;
+    };
+    const childFor = (type) => {
+        let child = childByType.get(type);
+        if (child === undefined) {
+            child = children.length;
+            children.push(new GeometryColumnBuilder(type, capacity));
+            childByType.set(type, child);
+        }
+        return child;
+    };
+    const checkOpen = () => {
+        if (finished)
+            throw new Error('TableBuilder: finish was already called');
+    };
+    const add = (geometry, properties, id) => {
+        checkOpen();
+        ensureRowCapacity();
+        const row = length;
+        let child = -1;
+        if (geometry && isTableGeometryType(geometry.type)) {
+            if (fixedType !== undefined && geometry.type !== fixedType) {
+                throw new TypeError(`TableBuilder: row ${row} is a ${geometry.type}, but the table holds ${fixedType}`);
+            }
+            child = childFor(geometry.type);
+            childRow[row] = children[child].rows;
+            children[child].add(geometry.coordinates);
+        }
+        childOf[row] = child;
+        if (properties) {
+            for (const name of Object.keys(properties)) {
+                let column = columns.get(name);
+                if (!column) {
+                    if (fixedColumns)
+                        continue;
+                    column = { values: new Array(row).fill(null), numeric: true };
+                    columns.set(name, column);
+                }
+                const value = properties[name] ?? null;
+                if (value !== null && typeof value !== 'number')
+                    column.numeric = false;
+                column.values.push(value);
+            }
+        }
+        for (const column of columns.values()) {
+            if (column.values.length === row)
+                column.values.push(null);
+        }
+        if (id !== undefined && ids === null)
+            ids = Array.from({ length: row }, (_, i) => i);
+        if (ids !== null)
+            ids.push(id ?? row);
+        length++;
+    };
+    const finish = () => {
+        checkOpen();
+        finished = true;
+        const types = childOf.slice(0, length);
+        let geometry;
+        if (children.length === 0) {
+            geometry = emptyGeometry(fixedType ?? 'Point', length);
+        }
+        else if (children.length === 1) {
+            const only = children[0];
+            geometry = only.rows === length ? only.finish() : only.finishSpread(types, length);
+        }
+        else {
+            const offsets = childRow.slice(0, length);
+            for (let row = 0; row < length; row++)
+                if (types[row] < 0)
+                    offsets[row] = 0;
+            geometry = {
+                type: 'Mixed',
+                types,
+                offsets,
+                children: children.map((child) => child.finish()),
+            };
+        }
+        const table = { length, geometry, columns: {} };
+        const out = table.columns;
+        for (const [name, column] of columns) {
+            out[name] = column.numeric
+                ? Float64Array.from(column.values, (value) => value === null ? Number.NaN : value)
+                : column.values;
+        }
+        if (ids !== null)
+            table.ids = ids;
+        return table;
+    };
+    return { add, finish };
+}
+/** A geometry column of one type whose rows all have no geometry */
+function emptyGeometry(type, length) {
+    if (type === 'Point') {
+        return { type, coords: new Float64Array(length * 2).fill(Number.NaN) };
+    }
+    const levels = OFFSET_LEVELS[type];
+    const offsets = [new Int32Array(length + 1)];
+    for (let level = 1; level < levels; level++)
+        offsets.push(new Int32Array(1));
+    return { type, coords: new Float64Array(0), offsets };
+}
+/**
+ * Makes a table from an array of GeoJSON features.
+ *
+ * It is {@link createTableBuilder} with one `add` per feature: the geometry, the properties and
+ * the id of each feature become a row. Rows of different geometry types give a mixed geometry
+ * column.
+ *
+ * @param features The features, in row order
+ * @param options `columns` limits the properties that become columns to these names
+ * @returns The table
+ *
+ * @example
+ * ```ts
+ * import { tableFromFeatures } from '@sakuzu/maplibre-gl-draw/table';
+ *
+ * const table = tableFromFeatures(collection.features, { columns: ['name', 'visitors'] });
+ * draw.datasets.add({ id: 'places', table });
+ * ```
+ */
+export function tableFromFeatures(features, options) {
+    const builder = createTableBuilder({ capacity: features.length, columns: options?.columns });
+    for (const feature of features) {
+        builder.add(feature.geometry, feature.properties, feature.id);
+    }
+    return builder.finish();
+}

package/dist/table/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Read a large table in a Worker and put it on the map.
+ *
+ * Use it when the data has hundreds of thousands of rows or more and comes from a file: read
+ * and prepare it in a Worker, and the main thread only receives it and passes it to
+ * `draw.datasets.add`. For a few thousand rows, passing an array of features as `rows` is
+ * simpler. It depends on neither maplibre nor WebGL nor the DOM, so a Worker can import it
+ * without pulling in the engine.
+ *
+ * ```ts
+ * // worker.ts
+ * import {
+ *   tableFromFeatures, prepareTable, transferList,
+ * } from '@sakuzu/maplibre-gl-draw/table';
+ *
+ * const features = await readGeoJSON(url);          // read it any way you like
+ * const prepared = prepareTable(tableFromFeatures(features));
+ * self.postMessage(prepared, { transfer: transferList(prepared) });
+ *
+ * // main.ts
+ * worker.onmessage = (e) =>
+ *   draw.datasets.add({ id: 'places', table: e.data });
+ * ```
+ *
+ * Read next: the guide
+ * [showing large data](https://sakuzu.github.io/maplibre-gl-draw/guides/large-data). The
+ * functions used most are {@link tableFromFeatures}, {@link createTableBuilder},
+ * {@link prepareTable} and {@link transferList}.
+ *
+ * @module table
+ */
+export type { TableBuilder } from './builder.js';
+export { createTableBuilder, tableFromFeatures } from './builder.js';
+export type { Table } from './types.js';
+export { prepareTable, transferList } from './prepare.js';
+export type { PreparedTable } from './types.js';
+export type { Column, DictionaryColumn, GeometryType, TableGeometry, TableMixedGeometry, } from './types.js';

package/dist/table/index.js

@@ -0,0 +1,5 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export { createTableBuilder, tableFromFeatures } from './builder.js';
+// Prepare in a Worker
+export { prepareTable, transferList } from './prepare.js';

package/dist/table/packed-rtree.d.ts

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

package/dist/{display → table}/packed-rtree.js

@@ -6,7 +6,7 @@
  * 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
+ * a copy (`prepareTable`). 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.

package/dist/table/partition.d.ts

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

package/dist/{display → table}/partition.js

@@ -4,9 +4,9 @@
  * 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`).
+ * WebGL, so it runs in a Worker as well (`prepareTable` calls it there). Both kinds of contents
+ * use it: the features (`dataset/chunk.ts` computes the per-row arrays from them) and the tables
+ * (`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

package/dist/table/prepare.d.ts

@@ -0,0 +1,44 @@
+import type { PreparedTable, Table } from './types.js';
+/**
+ * Computes the bboxes, the spatial chunks and the spatial index of a table, and returns them
+ * with the table.
+ *
+ * It is the work that the dataset would otherwise do on the main thread when it is given the
+ * table. Call it where the table is read (in a Worker), send the result to the main thread and
+ * pass it as `table` to `draw.datasets.add` or to `Dataset.setTable`. It uses neither maplibre nor
+ * WebGL, so it runs in any Worker.
+ *
+ * @param table The table
+ * @returns The table with its prepared arrays, which belong to this table only
+ * @throws when the shape of the table does not add up (the same checks as `Dataset.setTable`)
+ *
+ * @example In a Worker
+ * ```ts
+ * import { prepareTable, transferList } from '@sakuzu/maplibre-gl-draw/table';
+ *
+ * self.onmessage = async (event) => {
+ *   const table = await readTable(event.data); // your reader, which returns a Table
+ *   const prepared = prepareTable(table);
+ *   self.postMessage(prepared, { transfer: transferList(prepared) });
+ * };
+ * ```
+ */
+export declare function prepareTable(table: Table): PreparedTable;
+/**
+ * Lists the buffers of a table, or of a prepared table, for the transfer list of `postMessage`.
+ *
+ * The buffers move to the other thread without a copy. The geometry arrays of every child of a
+ * mixed geometry column are listed too, and for a prepared table the prepared arrays as well.
+ * Each buffer appears once, even when several arrays share it. A `SharedArrayBuffer` is left
+ * out (it is shared, not moved). After the transfer the arrays are empty on the sending side.
+ *
+ * @param table The table, or the result of {@link prepareTable}
+ * @returns The buffers to pass as the transfer list
+ *
+ * @example
+ * ```ts
+ * const prepared = prepareTable(tableFromFeatures(features));
+ * self.postMessage(prepared, { transfer: transferList(prepared) });
+ * ```
+ */
+export declare function transferList(table: Table | PreparedTable): ArrayBuffer[];

package/dist/table/prepare.js

@@ -0,0 +1,136 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { buildPackedRTree } from './packed-rtree.js';
+import { partitionRows } from './partition.js';
+import { isDictionaryColumn, TableReader } from './table.js';
+/**
+ * Computes the bboxes, the spatial chunks and the spatial index of a table, and returns them
+ * with the table.
+ *
+ * It is the work that the dataset would otherwise do on the main thread when it is given the
+ * table. Call it where the table is read (in a Worker), send the result to the main thread and
+ * pass it as `table` to `draw.datasets.add` or to `Dataset.setTable`. It uses neither maplibre nor
+ * WebGL, so it runs in any Worker.
+ *
+ * @param table The table
+ * @returns The table with its prepared arrays, which belong to this table only
+ * @throws when the shape of the table does not add up (the same checks as `Dataset.setTable`)
+ *
+ * @example In a Worker
+ * ```ts
+ * import { prepareTable, transferList } from '@sakuzu/maplibre-gl-draw/table';
+ *
+ * self.onmessage = async (event) => {
+ *   const table = await readTable(event.data); // your reader, which returns a Table
+ *   const prepared = prepareTable(table);
+ *   self.postMessage(prepared, { transfer: transferList(prepared) });
+ * };
+ * ```
+ */
+export function prepareTable(table) {
+    const reader = new TableReader(table);
+    const rowBounds = reader.computeBounds();
+    const chunks = partitionRows(rowBounds, reader.computeVertexCounts());
+    const index = buildPackedRTree(rowBounds);
+    return {
+        table,
+        length: reader.length,
+        bounds: extentOf(rowBounds),
+        rowBounds,
+        chunkRows: chunks.rows,
+        chunkOffsets: chunks.offsets,
+        chunkBounds: chunks.bounds,
+        indexNodeSize: index.nodeSize,
+        indexItemCount: index.numItems,
+        indexBoxes: index.boxes,
+        indexEntries: index.indices,
+        indexLevels: index.levelBounds,
+    };
+}
+/** The extent of the bboxes of the rows (NaN for a row without a geometry), or null */
+function extentOf(rowBounds) {
+    let west = Number.POSITIVE_INFINITY;
+    let south = Number.POSITIVE_INFINITY;
+    let east = Number.NEGATIVE_INFINITY;
+    let north = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i < rowBounds.length; i += 4) {
+        if (Number.isNaN(rowBounds[i]))
+            continue;
+        west = Math.min(west, rowBounds[i]);
+        south = Math.min(south, rowBounds[i + 1]);
+        east = Math.max(east, rowBounds[i + 2]);
+        north = Math.max(north, rowBounds[i + 3]);
+    }
+    return west <= east ? [west, south, east, north] : null;
+}
+/**
+ * Whether a value is a prepared table rather than a bare table
+ *
+ * @internal
+ */
+export function isPreparedTable(value) {
+    return 'table' in value && typeof value.table === 'object' && value.table !== null;
+}
+/**
+ * Lists the buffers of a table, or of a prepared table, for the transfer list of `postMessage`.
+ *
+ * The buffers move to the other thread without a copy. The geometry arrays of every child of a
+ * mixed geometry column are listed too, and for a prepared table the prepared arrays as well.
+ * Each buffer appears once, even when several arrays share it. A `SharedArrayBuffer` is left
+ * out (it is shared, not moved). After the transfer the arrays are empty on the sending side.
+ *
+ * @param table The table, or the result of {@link prepareTable}
+ * @returns The buffers to pass as the transfer list
+ *
+ * @example
+ * ```ts
+ * const prepared = prepareTable(tableFromFeatures(features));
+ * self.postMessage(prepared, { transfer: transferList(prepared) });
+ * ```
+ */
+export function transferList(table) {
+    const buffers = new Set();
+    const add = (view) => {
+        if (view && view.buffer instanceof ArrayBuffer)
+            buffers.add(view.buffer);
+    };
+    const addColumn = (column) => {
+        if (!column)
+            return;
+        if (isDictionaryColumn(column))
+            add(column.codes);
+        else if (ArrayBuffer.isView(column))
+            add(column);
+    };
+    const addGeometry = (geometry) => {
+        add(geometry.coords);
+        for (const offsets of geometry.offsets ?? [])
+            add(offsets);
+    };
+    const prepared = isPreparedTable(table) ? table : null;
+    const input = prepared ? prepared.table : table;
+    const geometry = input.geometry;
+    if (geometry.type === 'Mixed') {
+        add(geometry.types);
+        add(geometry.offsets);
+        for (const child of geometry.children)
+            addGeometry(child);
+    }
+    else {
+        addGeometry(geometry);
+    }
+    add(input.validity);
+    addColumn(input.ids);
+    for (const column of Object.values(input.columns ?? {}))
+        addColumn(column);
+    if (prepared) {
+        add(prepared.rowBounds);
+        add(prepared.chunkRows);
+        add(prepared.chunkOffsets);
+        add(prepared.chunkBounds);
+        add(prepared.indexBoxes);
+        add(prepared.indexEntries);
+        add(prepared.indexLevels);
+    }
+    return [...buffers];
+}

package/dist/table/table.d.ts

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