@sakuzu/maplibre-gl-draw 1.0.0

package/dist/display/selection.d.ts

@@ -0,0 +1,13 @@
+import type { Feature } from '../shared/types/model.js';
+import type { RetainedStyleResolver } from '../view/renderers/retained.js';
+/**
+ * Whether the analytic drape draws the polygons and lines of this feature
+ *
+ * It is paired with `collectDataset` in `view/terrain/drape/pass.ts`. Changing only one of
+ * them would show the selection highlight twice or in neither of them.
+ *
+ * A dashed outline does not go onto the drape (solving the accumulated distance along the outline
+ * from the pixels is not implemented, so drawing it as a solid line would change the appearance).
+ * For what does not go onto it, the immediate-mode path draws the highlight as before.
+ */
+export declare function isHandedToDrape(feature: Feature, styles: RetainedStyleResolver): boolean;

package/dist/display/selection.js

@@ -0,0 +1,226 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { SELECTION_HIGHLIGHT_COLOR, SELECTION_HIGHLIGHT_FILL_OPACITY, SELECTION_HIGHLIGHT_RING_EXTRA, SELECTION_HIGHLIGHT_STROKE_EXTRA, } from '../shared/config/selection-highlight.js';
+import { getBoundingBox } from '../shared/utils/feature-bbox.js';
+import { getStyleRuleChannel } from '../view/style-rule.js';
+import { isDrapePaintedDataset } from '../view/terrain/state.js';
+import { boundsIntersect } from './chunk.js';
+import { pointMarkerRadiusPx, worldUnitsPerPixel } from './thinning.js';
+/** Default line width (the same as lineString.stroke.width of feature-style) */
+const DEFAULT_STROKE_WIDTH = 2;
+/** Default radius of a point (half of point.point.size 12 of feature-style) */
+const DEFAULT_POINT_RADIUS = 6;
+/**
+ * Overpaints the selected features with the highlight
+ *
+ * Neither the retained batches nor the reused features are touched. It only overdraws on the
+ * same immediate-mode path as fallback, so switching the selection never rebuilds a GPU
+ * resource.
+ *
+ * A point is drawn as "a point of the key color slightly larger than the original → the
+ * original point", so that the difference shows as a ring. Lines and polygons are painted over
+ * in the key color.
+ *
+ * While the polygons and lines are handed to the analytic drape, however, their highlight is
+ * not drawn here (the drape draws it as ground pixels; `isHandedToDrape`). The immediate-mode
+ * path only subdivides along the terrain inside the region of the subdivision (the DEM atlas ∩
+ * the view), so drawing a surface the size of a prefecture here would leave everything outside
+ * that region as flat triangles and turn into "a red vertical wall" and "a wrong fan-shaped
+ * coverage". The test for the hand-over is paired with the drape side (collectDataset in
+ * `drape/pass.ts`), so in the band where the feature itself appears the highlight always
+ * appears too.
+ *
+ * @internal
+ */
+export function drawSelectionHighlight(input) {
+    const { target, projectionData, zoom, bounds, styles } = input;
+    if (input.selected.length === 0)
+        return;
+    const visible = input.selected.filter((feature) => feature.visible && boundsIntersect(getBoundingBox(feature), bounds));
+    if (visible.length === 0)
+        return;
+    target.beginFrame(projectionData, zoom);
+    for (const feature of visible) {
+        const prepared = input.prepare(feature);
+        // The hand-over decision (drapedFills) switches a few frames late, so looking only at it
+        // would let the immediate path draw the highlight while the drape is already painting. The
+        // immediate path does not subdivide outside the region of the subdivision, so a surface as
+        // large as a prefecture or a city becomes a flat plate there, floats off the terrain and
+        // raises a vertical wall. Whether it is actually painting is looked at as well
+        const draped = input.drapedFills || isDrapePaintedDataset(input.terrain, input.datasetId);
+        if (draped && styles && isHandedToDrape(prepared, styles)) {
+            continue;
+        }
+        target.processFeature(highlightFeature(prepared), false);
+        // To make a point look like a ring, the original point is drawn again over the highlight.
+        // For a point drawn by an external renderer the overpaint is skipped and only the halo
+        // underneath is left (the picture of the external renderer is drawn above core, so the
+        // result is a selection halo behind that picture)
+        if (getStyleRuleChannel(prepared.type) === 'point' && !input.isExternalPoint(prepared)) {
+            target.processFeature(prepared, false);
+        }
+    }
+    target.endFrame();
+}
+/**
+ * Returns the frontmost hit (the feature as stored, without the styles applied, and its row)
+ *
+ * The candidates are narrowed with the spatial index and tested precisely from the back of the
+ * draw order (the front).
+ *
+ * A point is "grabbable anywhere inside the marker that is drawn". A marker is drawn at the
+ * size of the radius + the white outline multiplied by the zoom-dependent factor, and depending
+ * on what the host specifies and on the factor it gets far larger than the click tolerance.
+ * Deciding by the tolerance alone would miss even a click inside a clearly visible circle (the
+ * tolerance passed in is kept as a lower bound).
+ *
+ * @internal
+ */
+export function hitTestDisplayFeatures(input) {
+    const { coordinate, toleranceLngLat, baseStyle, pointDefaults: defaults, scale } = input;
+    const degreesPerPixel = worldUnitsPerPixel(input.zoom) * 360;
+    // The narrowing of the index is widened to the range the largest marker reaches
+    const maxPointRadius = Math.max(pointMarkerRadiusPx(undefined, baseStyle, defaults, scale), input.maxStylePointRadius > 0
+        ? pointMarkerRadiusPx(input.maxStylePointRadius, baseStyle, defaults, scale)
+        : 0);
+    const reach = Math.max(toleranceLngLat, maxPointRadius * degreesPerPixel);
+    const bounds = {
+        minX: coordinate[0] - reach,
+        minY: coordinate[1] - reach,
+        maxX: coordinate[0] + reach,
+        maxY: coordinate[1] + reach,
+    };
+    const candidates = input.search(bounds);
+    for (let i = candidates.length - 1; i >= 0; i--) {
+        const row = candidates[i];
+        // What has been thinned away and is not visible cannot be grabbed
+        if (!input.isDrawn(row))
+            continue;
+        const feature = input.featureAt(row);
+        if (!feature.visible)
+            continue;
+        const tolerance = getStyleRuleChannel(feature.type) === 'point'
+            ? Math.max(toleranceLngLat, pointMarkerRadiusPx(feature.style?.pointRadius, baseStyle, defaults, scale) *
+                degreesPerPixel)
+            : toleranceLngLat;
+        if (input.test(feature, coordinate, tolerance))
+            return { feature, row };
+    }
+    return null;
+}
+/**
+ * Measures the largest point radius given by an individual style (0 when none is given)
+ *
+ * It is used to decide the range that narrows the hit test candidates. Only the points are
+ * walked.
+ *
+ * @internal
+ */
+export function maxStylePointRadiusOf(features) {
+    let max = 0;
+    for (const feature of features) {
+        if (getStyleRuleChannel(feature.type) !== 'point')
+            continue;
+        const radius = feature.style?.pointRadius;
+        if (radius !== undefined && radius > max)
+            max = radius;
+    }
+    return max;
+}
+/**
+ * Checks whether two feature lists have the same set of ids
+ *
+ * It is used for the diff test of the selection. The order is determined by the draw order, so
+ * if the sets are the same the order is the same too.
+ *
+ * @internal
+ */
+export function sameFeatureIds(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i].id !== b[i].id)
+            return false;
+    }
+    return true;
+}
+/**
+ * Whether the analytic drape draws the polygons and lines of this feature
+ *
+ * It is paired with `collectDataset` in `view/terrain/drape/pass.ts`. Changing only one of
+ * them would show the selection highlight twice or in neither of them.
+ *
+ * A dashed outline does not go onto the drape (solving the accumulated distance along the outline
+ * from the pixels is not implemented, so drawing it as a solid line would change the appearance).
+ * For what does not go onto it, the immediate-mode path draws the highlight as before.
+ */
+export function isHandedToDrape(feature, styles) {
+    if (feature.type === 'Polygon' || feature.type === 'MultiPolygon') {
+        const { fillColor, strokeStyle } = styles.getPolygonStyles(feature);
+        const hasStroke = strokeStyle.opacity > 0 && strokeStyle.width > 0;
+        if (hasStroke && strokeStyle.lineStyle !== 'solid')
+            return false;
+        return hasStroke || fillColor[3] > 0;
+    }
+    if (feature.type === 'LineString' ||
+        feature.type === 'MultiLineString' ||
+        feature.type === 'Freehand') {
+        const strokeStyle = styles.getLineStringStrokeStyle(feature);
+        if (strokeStyle.lineStyle !== 'solid')
+            return false;
+        return strokeStyle.opacity > 0 && strokeStyle.width > 0;
+    }
+    return false;
+}
+/**
+ * Returns a feature whose style is overwritten for the selection highlight
+ *
+ * Neither the original feature nor the cache is rewritten; a copy with only the style replaced is
+ * made. The painting is split by the channel of the geometry type (the same vocabulary as the
+ * rule colors).
+ *
+ * - Point: a point of the key color with the original radius + 3px (the original point is drawn
+ *   on top of it to make a ring)
+ * - Line: a line of the key color with the original width + 2px
+ * - Polygon: a translucent fill of the key color and a frame of the key color with the original
+ *   width + 2px
+ *
+ * @internal
+ */
+export function highlightFeature(feature) {
+    const style = feature.style;
+    const channel = getStyleRuleChannel(feature.type);
+    if (channel === 'point') {
+        return {
+            ...feature,
+            style: {
+                ...style,
+                pointColor: SELECTION_HIGHLIGHT_COLOR,
+                pointRadius: (style?.pointRadius ?? DEFAULT_POINT_RADIUS) + SELECTION_HIGHLIGHT_RING_EXTRA,
+            },
+        };
+    }
+    const strokeWidth = (style?.strokeWidth ?? DEFAULT_STROKE_WIDTH) + SELECTION_HIGHLIGHT_STROKE_EXTRA;
+    if (channel === 'stroke') {
+        return {
+            ...feature,
+            style: {
+                ...style,
+                strokeColor: SELECTION_HIGHLIGHT_COLOR,
+                strokeOpacity: 1,
+                strokeWidth,
+            },
+        };
+    }
+    return {
+        ...feature,
+        style: {
+            ...style,
+            fillColor: SELECTION_HIGHLIGHT_COLOR,
+            fillOpacity: SELECTION_HIGHLIGHT_FILL_OPACITY,
+            strokeColor: SELECTION_HIGHLIGHT_COLOR,
+            strokeOpacity: 1,
+            strokeWidth,
+        },
+    };
+}

package/dist/display/source.d.ts

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

package/dist/display/source.js

@@ -0,0 +1,119 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { computeFeatureBounds, partitionIntoChunks } from './chunk.js';
+import { chunkTargetSizeFor } from './partition.js';
+import { collectFeatures } from './retained.js';
+import { maxStylePointRadiusOf } from './selection.js';
+import { DisplaySpatialIndex } from './spatial.js';
+import { featureThinningRole } from './thinning.js';
+/**
+ * The contents given as an array of features
+ *
+ * @internal
+ */
+export class FeatureArraySource {
+    /**
+     * @param list The normalized features, in draw order
+     */
+    constructor(list) {
+        Object.defineProperty(this, "list", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: list
+        });
+        Object.defineProperty(this, "length", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "bounds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "chunks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "index", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new DisplaySpatialIndex()
+        });
+        Object.defineProperty(this, "maxStylePointRadius", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The row of each id, built on the first request */
+        Object.defineProperty(this, "rowById", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.length = list.length;
+        // The bboxes are shared by the spatial index and the chunk splitting (not computed twice)
+        this.bounds = computeFeatureBounds(list);
+        this.index.load(this.bounds);
+        this.chunks = partitionIntoChunks(list, chunkTargetSizeFor(list.length), this.bounds);
+        this.maxStylePointRadius = maxStylePointRadiusOf(list);
+    }
+    hasGeometry(row) {
+        return !Number.isNaN(this.bounds[row * 4]);
+    }
+    featureAt(row) {
+        return this.list[row];
+    }
+    idOf(row) {
+        return this.list[row].id;
+    }
+    typeOf(row) {
+        return this.hasGeometry(row) ? this.list[row].type : null;
+    }
+    rowsOfIds(ids) {
+        const rows = [];
+        if (ids.size === 0)
+            return rows;
+        for (let row = 0; row < this.list.length; row++) {
+            if (ids.has(this.list[row].id))
+                rows.push(row);
+        }
+        return rows;
+    }
+    rowOfId(id) {
+        if (!this.rowById) {
+            const map = new Map();
+            for (let row = 0; row < this.list.length; row++)
+                map.set(this.list[row].id, row);
+            this.rowById = map;
+        }
+        return this.rowById.get(id) ?? -1;
+    }
+    features() {
+        return this.list;
+    }
+    thinningRole(row) {
+        return featureThinningRole(this.list[row]);
+    }
+    pointOf(row) {
+        return this.list[row].coordinates;
+    }
+    styleRadiusOf(row) {
+        return this.list[row].style?.pointRadius;
+    }
+    collector(rows, context) {
+        const list = this.list;
+        return collectFeatures(rows.length, (index) => {
+            const row = rows[index];
+            return context.isDrawn(row) ? context.styler.prepareIfStyled(list[row]) : null;
+        }, context);
+    }
+}

package/dist/display/spatial.d.ts

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

package/dist/display/spatial.js

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { buildPackedRTree, searchPackedRTree } from './packed-rtree.js';
+/**
+ * Spatial index of a dataset
+ *
+ * @internal
+ */
+export class DisplaySpatialIndex {
+    constructor() {
+        Object.defineProperty(this, "tree", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    /** Number of rows stored */
+    get size() {
+        return this.tree?.numItems ?? 0;
+    }
+    /**
+     * Builds the tree over the bboxes of the rows (the existing contents are discarded)
+     *
+     * @param bounds `[minX, minY, maxX, maxY]` per row (a NaN row is left out)
+     */
+    load(bounds) {
+        this.tree = buildPackedRTree(bounds);
+    }
+    /** Takes a tree built elsewhere (in a Worker, for example) */
+    adopt(tree) {
+        this.tree = tree;
+    }
+    /**
+     * Returns the rows whose bbox intersects the bounding box, in draw order
+     */
+    search(bounds) {
+        if (!this.tree)
+            return [];
+        const rows = searchPackedRTree(this.tree, bounds.minX, bounds.minY, bounds.maxX, bounds.maxY);
+        rows.sort((a, b) => a - b);
+        return rows;
+    }
+    /**
+     * Returns the rows whose bbox intersects the bounding box and that `keep` accepts, in draw order
+     *
+     * The rows are filtered before they are sorted, so a filter that drops most of what is in the
+     * range keeps the sort as small as what is kept.
+     */
+    searchWhere(bounds, keep) {
+        if (!this.tree)
+            return new Int32Array(0);
+        const hits = searchPackedRTree(this.tree, bounds.minX, bounds.minY, bounds.maxX, bounds.maxY);
+        const rows = new Int32Array(hits.length);
+        let count = 0;
+        for (let i = 0; i < hits.length; i++) {
+            const row = hits[i];
+            if (keep(row))
+                rows[count++] = row;
+        }
+        const kept = count === rows.length ? rows : rows.slice(0, count);
+        // A typed array sorts its numbers by value
+        return kept.sort();
+    }
+    /**
+     * Empties the index
+     */
+    clear() {
+        this.tree = null;
+    }
+}

package/dist/display/style.d.ts

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

package/dist/display/style.js

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { StyleRuleCache } from '../view/cache/style-rule.js';
+import { applyRuleColor, getStyleRuleChannel } from '../view/style-rule.js';
+/**
+ * The rule and the base style of a dataset, and the features carrying them
+ *
+ * The features carrying the rule colors are reused per id (so that they are not copied every
+ * frame). Whoever changes what they depend on (the rule, the base style, the contents) calls
+ * `clear()`.
+ *
+ * @internal
+ */
+export class DisplayFeatureStyler {
+    constructor(styleRule, baseStyle) {
+        Object.defineProperty(this, "styleRule", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Base style per dataset (per channel) */
+        Object.defineProperty(this, "baseStyle", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "styleCache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new StyleRuleCache()
+        });
+        /** Reuse of the features carrying the rule colors (to avoid copying them every frame) */
+        Object.defineProperty(this, "preparedCache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        this.styleRule = styleRule;
+        this.baseStyle = baseStyle;
+    }
+    /** The base style (undefined when not set) */
+    get base() {
+        return this.baseStyle;
+    }
+    /** The style rule (undefined when not set) */
+    get rule() {
+        return this.styleRule;
+    }
+    /** Whether a rule or a base style is set (without either, a feature is returned as it is) */
+    get isStyled() {
+        return Boolean(this.styleRule) || Boolean(this.baseStyle);
+    }
+    /** Replaces the rule and discards the caches */
+    setRule(rule) {
+        this.styleRule = rule;
+        this.clear();
+    }
+    /**
+     * Replaces the base style and discards the caches
+     *
+     * The cache of the rule colors does not depend on the base style, but it is discarded together
+     * with it, to keep the handling in step with setRule.
+     */
+    setBase(style) {
+        this.baseStyle = style;
+        this.clear();
+    }
+    /** Discards the evaluation results and the reused features */
+    clear() {
+        this.styleCache.clear();
+        this.preparedCache.clear();
+    }
+    /**
+     * Returns the feature carrying the rule color and the base style
+     *
+     * When the individual style has a color for that channel, the rule has no effect
+     * (applyRuleColor returns the same reference). The base style goes underneath the rule color
+     * and the individual style, so it is spread first and overwritten afterwards. Only when neither
+     * the rule nor the base style had any effect is the original feature returned as it is.
+     */
+    prepare(feature) {
+        const cached = this.preparedCache.get(feature.id);
+        if (cached)
+            return cached;
+        const channel = getStyleRuleChannel(feature.type);
+        const ruleColor = this.styleCache.resolve(feature, this.styleRule);
+        const style = this.effectiveStyle(feature.style, ruleColor, channel);
+        const prepared = style === feature.style ? feature : { ...feature, style };
+        this.preparedCache.set(feature.id, prepared);
+        return prepared;
+    }
+    /**
+     * The style that `prepare` gives a feature: the individual style over the rule color over the
+     * base style of the channel
+     *
+     * @param style The individual style (undefined for none)
+     * @param ruleColor The rule color (null without a rule)
+     */
+    effectiveStyle(style, ruleColor, channel) {
+        const styled = applyRuleColor(style, ruleColor, channel);
+        const base = this.baseStyle?.[channel];
+        return base ? { ...base, ...styled } : styled;
+    }
+    /** Like `prepare`, but returns the feature as it is when nothing is set */
+    prepareIfStyled(feature) {
+        return this.isStyled ? this.prepare(feature) : feature;
+    }
+    /**
+     * Returns the array of features carrying the rule colors and the base style
+     *
+     * The original array is returned as it is when neither the rule nor the base style is set.
+     */
+    prepareAll(features) {
+        if (!this.isStyled)
+            return features;
+        const result = new Array(features.length);
+        for (let i = 0; i < features.length; i++) {
+            result[i] = this.prepare(features[i]);
+        }
+        return result;
+    }
+}

package/dist/display/thinning.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The collision thinning of the point markers of a dataset, as the host
+ * passes it.
+ *
+ * Everything can be omitted, and an omitted item takes its default value. While it is
+ * enabled, `Point` markers that overlap on screen are not drawn and cannot be hit; lines,
+ * polygons and MultiPoint are always drawn. The overlap is tested with the size actually drawn
+ * (the radius + the outline + `marginPx`), and the winners are picked greedily from the front
+ * of the draw order for each integer zoom band, so panning does not swap them.
+ *
+ * @example
+ * ```ts
+ * const places = draw.addDataset({
+ *   id: 'places',
+ *   features,
+ *   collisionThinning: { enabled: true, fullDisplayZoom: 17, marginPx: 2 },
+ * });
+ * const { total, visible } = places.getThinningStats(); // "showing 1,200 of 50,000"
+ * ```
+ */
+export interface DatasetCollisionThinning {
+    /** Whether the thinning is enabled (false by default = everything is drawn as before) */
+    enabled?: boolean;
+    /**
+     * The zoom at which the thinning stops (17 by default)
+     *
+     * At or above this zoom the set of winners becomes every feature. It is an escape hatch that
+     * avoids "something in the source data can never be seen no matter what", and it can be
+     * changed at runtime because it is decided by looking at the real thing.
+     */
+    fullDisplayZoom?: number;
+    /**
+     * Margin added around each marker's footprint, in screen px (2 by default; NaN or a negative
+     * value gives 2)
+     */
+    marginPx?: number;
+}
+/**
+ * The collision thinning in effect, with every default filled in, as
+ * {@link Dataset.getCollisionThinning} returns it.
+ */
+export interface ResolvedCollisionThinning {
+    /** Whether the thinning is enabled */
+    enabled: boolean;
+    /** The zoom at or above which every feature is drawn */
+    fullDisplayZoom: number;
+    /** The margin added around each marker's footprint, in screen px */
+    marginPx: number;
+}
+/**
+ * The current result of the collision thinning, as {@link Dataset.getThinningStats}
+ * returns it; for a message such as "showing n of N".
+ */
+export interface DatasetThinningStats {
+    /** Whether it is enabled as a setting */
+    enabled: boolean;
+    /** Whether it is actually thinning (the band is below fullDisplayZoom and winners exist) */
+    active: boolean;
+    /** The number of all the features held */
+    total: number;
+    /** The number of features drawn (the same as total when nothing is thinned) */
+    visible: number;
+    /** The zoom band the winners were picked for (null when not computed or disabled) */
+    band: number | null;
+}