Split tiles on-the-fly to improve over scale vector handling

CHANGELOG.md

@@ -1,6 +1,8 @@
 ## main
 
 ### ✨ Features and improvements
+
+- Slice vector tiles to improve over scale vector handling ([#6521](https://github.com/maplibre/maplibre-gl-js/pull/6521)) ⚠️ This is an experimental feature that currently only applies to Safari by default to prevent it from crashing at high zoom levels. This is not enabled by default for all browsers as it changes rendering of polygon features in high zoom levels due to tile splitting. It adds the `experimentalOverzoomingByClippingTiles` flag to `MapOptions` to allow controlling this behavior if needed. Use `true` for partitioning and `false` for scaling. It seems to have better performance at high zoom levels.
 - _...Add new stuff here..._
 
 ### 🐞 Bug fixes

src/data/bucket/symbol_bucket.ts

@@ -37,7 +37,6 @@ import {EvaluationParameters} from '../../style/evaluation_parameters';
 import {Formatted, ResolvedImage} from '@maplibre/maplibre-gl-style-spec';
 import {rtlWorkerPlugin} from '../../source/rtl_text_plugin_worker';
 import {getOverlapMode} from '../../style/style_layer/overlap_mode';
-import {isSafari} from '../../util/util';
 import type {CanonicalTileID} from '../../source/tile_id';
 import type {
     Bucket,
@@ -363,7 +362,7 @@ export class SymbolBucket implements Bucket {
     constructor(options: BucketParameters<SymbolStyleLayer>) {
         this.collisionBoxArray = options.collisionBoxArray;
         this.zoom = options.zoom;
-        this.overscaling = isSafari(globalThis) ? Math.min(options.overscaling, 128) : options.overscaling;
+        this.overscaling = options.overscaling;
         this.layers = options.layers;
         this.layerIds = this.layers.map(layer => layer.id);
         this.index = options.index;

src/geo/projection/covering_tiles.ts

@@ -50,6 +50,11 @@ export type CoveringTilesOptionsInternal = CoveringTilesOptions & {
      * its zoom set to the overscaled greater zoom. When false, such tiles will have zoom set to `maxzoom`.
      */
     reparseOverscaled?: boolean;
+    /**
+     * For vector tiles, geojsonvt is used to increase performance by providing sub-tile grids greater than source maxzoom, 
+     * therefore bypassing the need for overscaling past source maxzoom using overscaled tileIDs.
+     */
+    bypassOverscaling?: boolean;
     /**
      * When terrain is present, tile visibility will be computed in regards to the min and max elevations for each tile.
      */
@@ -191,7 +196,7 @@ export function coveringTiles(transform: IReadonlyTransform, options: CoveringTi
 
     const desiredZ = coveringZoomLevel(transform, options);
     const minZoom = options.minzoom || 0;
-    const maxZoom = options.maxzoom !== undefined ? options.maxzoom : transform.maxZoom;
+    const maxZoom = options.bypassOverscaling ? transform.maxZoom : options.maxzoom ?? transform.maxZoom;
     const nominalZ = Math.min(Math.max(0, desiredZ), maxZoom);
 
     const numTiles = Math.pow(2, nominalZ);

src/source/geojson_worker_source.ts

@@ -1,22 +1,18 @@
 import {getJSON} from '../util/ajax';
 import {RequestPerformance} from '../util/performance';
 import rewind from '@mapbox/geojson-rewind';
-import {fromVectorTileJs, GeoJSONWrapper} from '@maplibre/vt-pbf';
+import {GeoJSONWrapper} from '@maplibre/vt-pbf';
 import {EXTENT} from '../data/extent';
 import Supercluster, {type Options as SuperclusterOptions, type ClusterProperties} from 'supercluster';
 import geojsonvt, {type Options as GeoJSONVTOptions} from 'geojson-vt';
 import {VectorTileWorkerSource} from './vector_tile_worker_source';
 import {createExpression} from '@maplibre/maplibre-gl-style-spec';
 import {isAbortError} from '../util/abort_error';
-
-import type {
-    WorkerTileParameters,
-    WorkerTileResult,
-} from '../source/worker_source';
-
+import {toVirtualVectorTile} from './vector_tile_overzoomed';
+import {isUpdateableGeoJSON, type GeoJSONSourceDiff, applySourceDiff, toUpdateable, type GeoJSONFeatureId} from './geojson_source_diff';
+import type {WorkerTileParameters, WorkerTileResult} from '../source/worker_source';
 import type {LoadVectorTileResult} from './vector_tile_worker_source';
 import type {RequestParameters} from '../util/ajax';
-import {isUpdateableGeoJSON, type GeoJSONSourceDiff, applySourceDiff, toUpdateable, type GeoJSONFeatureId} from './geojson_source_diff';
 import type {ClusterIDAndSource, GeoJSONWorkerSourceLoadDataResult, RemoveSourceParams} from '../util/actor_messages';
 import type {IActor} from '../util/actor';
 import type {StyleLayerIndex} from '../style/style_layer_index';
@@ -90,19 +86,8 @@ export class GeoJSONWorkerSource extends VectorTileWorkerSource {
         }
 
         const geojsonWrapper = new GeoJSONWrapper(geoJSONTile.features, {version: 2, extent: EXTENT});
-        // Encode the geojson-vt tile into binary vector tile form.
-        // This is a convenience that allows `FeatureIndex` to operate the same way
-        // across `VectorTileSource` and `GeoJSONSource` data.
-        let pbf = fromVectorTileJs(geojsonWrapper);
-        if (pbf.byteOffset !== 0 || pbf.byteLength !== pbf.buffer.byteLength) {
-            // Compatibility with node Buffer (https://github.com/mapbox/pbf/issues/35)
-            pbf = new Uint8Array(pbf);
-        }
 
-        return {
-            vectorTile: geojsonWrapper,
-            rawData: pbf.buffer
-        };
+        return toVirtualVectorTile(geojsonWrapper);
     }
 
     /**

src/source/source_cache.ts

@@ -551,7 +551,8 @@ export class SourceCache extends Evented {
                 roundZoom: this.usedForTerrain ? false : this._source.roundZoom,
                 reparseOverscaled: this._source.reparseOverscaled,
                 terrain,
-                calculateTileZoom: this._source.calculateTileZoom
+                calculateTileZoom: this._source.calculateTileZoom,
+                bypassOverscaling: this._source.type === 'vector' && this.map._overzoomingByClippingTiles
             });
 
             if (this._source.hasTile) {

src/source/tile_cache.test.ts

@@ -1,6 +1,6 @@
 import {describe, test, expect} from 'vitest';
 import {type Tile} from './tile';
-import {TileCache} from './tile_cache';
+import {TileCache, BoundedLRUCache} from './tile_cache';
 import {OverscaledTileID} from './tile_id';
 
 const idA = new OverscaledTileID(10, 0, 10, 0, 1);
@@ -129,3 +129,63 @@ describe('TileCache', () => {
         expect(numRemoved).toBe(3);
     });
 });
+
+describe('BoundedLRUCache', () => {
+    test('evicts least-recently-used item when capacity exceeded', () => {
+        const cache = new BoundedLRUCache<string, number>(2);
+
+        cache.set('a', 1);
+        cache.set('b', 2);
+
+        // Access 'a' to make it most-recently-used
+        expect(cache.get('a')).toBe(1);
+
+        // Insert 'c' -> should evict 'b' (the least recently used)
+        cache.set('c', 3);
+
+        expect(cache.get('b')).toBeUndefined();
+        expect(cache.get('a')).toBe(1);
+        expect(cache.get('c')).toBe(3);
+    });
+
+    test('setting an existing key updates value and makes it most-recently-used', () => {
+        const cache = new BoundedLRUCache<string, number>(2);
+
+        cache.set('a', 1);
+        cache.set('b', 2);
+
+        // Update 'a' value and it should become most-recently-used
+        cache.set('a', 10);
+        // Insert 'c' -> should evict 'b'
+        cache.set('c', 3);
+
+        expect(cache.get('b')).toBeUndefined();
+        expect(cache.get('a')).toBe(10);
+        expect(cache.get('c')).toBe(3);
+    });
+
+    test('capacity 1 evicts previous entry on new set', () => {
+        const cache = new BoundedLRUCache<string, string>(1);
+
+        cache.set('x', 'first');
+        expect(cache.get('x')).toBe('first');
+
+        cache.set('y', 'second');
+        expect(cache.get('x')).toBeUndefined();
+        expect(cache.get('y')).toBe('second');
+    });
+
+    test('clear removes all entries', () => {
+        const cache = new BoundedLRUCache<number, string>(3);
+        cache.set(1, 'one');
+        cache.set(2, 'two');
+
+        expect(cache.get(1)).toBe('one');
+        expect(cache.get(2)).toBe('two');
+
+        cache.clear();
+
+        expect(cache.get(1)).toBeUndefined();
+        expect(cache.get(2)).toBeUndefined();
+    });
+});

src/source/tile_cache.ts

@@ -210,3 +210,38 @@ export class TileCache {
         }
     }
 }
+
+export class BoundedLRUCache<K, V> {
+    private maxEntries: number;
+    private map: Map<K, V>;
+
+    constructor(maxEntries: number) {
+        this.maxEntries = maxEntries;
+        this.map = new Map();
+    }
+
+    get(key: K): V | undefined {
+        const value = this.map.get(key);
+        if (value !== undefined) {
+            // Move key to end (most recently used)
+            this.map.delete(key);
+            this.map.set(key, value);
+        }
+        return value;
+    }
+
+    set(key: K, value: V): void {
+        if (this.map.has(key)) {
+            this.map.delete(key);
+        } else if (this.map.size >= this.maxEntries) {
+            // Delete oldest
+            const oldestKey = this.map.keys().next().value;
+            this.map.delete(oldestKey);
+        }
+        this.map.set(key, value);
+    }
+
+    clear(): void {
+        this.map.clear();
+    }
+}

src/source/vector_tile_overzoomed.ts

@@ -0,0 +1,119 @@
+import {type VectorTile, VectorTileFeature, VectorTileLayer} from '@mapbox/vector-tile';
+import Protobuf from 'pbf';
+import Point from '@mapbox/point-geometry';
+import {fromVectorTileJs} from '@maplibre/vt-pbf';
+import {clipGeometry} from '../symbol/clip_line';
+import type {LoadVectorTileResult} from './vector_tile_worker_source';
+import type {CanonicalTileID} from './tile_id';
+
+class VectorTileFeatureOverzoomed extends VectorTileFeature {
+    pointsArray: Point[][];
+
+    constructor(type: 0 | 1 | 2 | 3, geometry: Point[][], properties: any, id: number, extent: number) {
+        super(new Protobuf(), 0, extent, [], []);
+        this.type = type;
+        this.properties = properties ? properties : {};
+        this.extent = extent;
+        this.pointsArray = geometry;
+        this.id = id;
+    }
+
+    loadGeometry() {
+        // Clone the geometry and ensure all points are Point instances
+        return this.pointsArray.map(ring => 
+            ring.map(point => new Point(point.x, point.y))
+        );
+    }
+}
+
+class VectorTileLayerOverzoomed extends VectorTileLayer {
+    private _myFeatures: VectorTileFeatureOverzoomed[];
+    name: string;
+    extent: number;
+    version: number = 2;
+    length: number;
+
+    constructor(features: VectorTileFeatureOverzoomed[], layerName: string, extent: number) {
+        super(new Protobuf());
+        this._myFeatures = features;
+        this.name = layerName;
+        this.length = features.length;
+        this.extent = extent;
+    }
+
+    feature(i: number): VectorTileFeature {
+        return this._myFeatures[i];
+    }
+}
+
+export class VectorTileOverzoomed implements VectorTile {
+    layers: Record<string, VectorTileLayer> = {};
+
+    addLayer(layer: VectorTileLayerOverzoomed) {
+        this.layers[layer.name] = layer;
+    }
+}
+
+/**
+ * Encodes the virtual tile into binary vector tile form.
+ * This is a convenience that allows `FeatureIndex` to operate the same way across `VectorTileSource` and `GeoJSONSource` data.
+ * @param virtualVectorTile - a syntetically created vector tile, this tile should have the relevant layer and features already added to it.
+ * @returns - the encoded vector tile along with the original virtual tile binary data.
+ */
+export function toVirtualVectorTile(virtualVectorTile: VectorTile): LoadVectorTileResult {
+    let pbf: Uint8Array = fromVectorTileJs(virtualVectorTile);
+    if (pbf.byteOffset !== 0 || pbf.byteLength !== pbf.buffer.byteLength) {
+        pbf = new Uint8Array(pbf);  // Compatibility with node Buffer (https://github.com/mapbox/pbf/issues/35)
+    }
+    return {
+        vectorTile: virtualVectorTile,
+        rawData: pbf.buffer
+    };
+}
+
+/**
+ * This function slices a source tile layer into an overzoomed tile layer for a target tile ID.
+ * @param sourceLayer - the source tile layer to slice
+ * @param maxZoomTileID - the maximum zoom tile ID
+ * @param targetTileID - the target tile ID
+ * @returns - the overzoomed tile layer
+ */
+export function sliceVectorTileLayer(sourceLayer: VectorTileLayer, maxZoomTileID: CanonicalTileID, targetTileID: CanonicalTileID): VectorTileLayerOverzoomed {
+    const {extent} = sourceLayer;
+    const dz = targetTileID.z - maxZoomTileID.z;
+    const scale = Math.pow(2, dz);
+
+    // Calculate the target tile's position within the source tile in target coordinate space
+    // This ensures all tiles share the same coordinate system
+    const offsetX = (targetTileID.x - maxZoomTileID.x * scale) * extent;
+    const offsetY = (targetTileID.y - maxZoomTileID.y * scale) * extent;
+
+    const featureWrappers: VectorTileFeatureOverzoomed[] = [];
+    for (let index = 0; index < sourceLayer.length; index++) {
+        const feature: VectorTileFeature = sourceLayer.feature(index);
+        let geometry = feature.loadGeometry();
+
+        // Transform all coordinates to target tile space
+        for (const ring of geometry) {
+            for (const point of ring) {
+                point.x = point.x * scale - offsetX;
+                point.y = point.y * scale - offsetY;
+            }
+        }
+
+        const buffer = 128;
+        geometry = clipGeometry(geometry, feature.type, -buffer, -buffer, extent + buffer, extent + buffer);
+        if (geometry.length === 0) {
+            continue;
+        }
+
+        featureWrappers.push(new VectorTileFeatureOverzoomed(
+            feature.type,
+            geometry,
+            feature.properties,
+            feature.id,
+            extent
+        ));
+    }
+    return new VectorTileLayerOverzoomed(featureWrappers, sourceLayer.name, extent);
+}

src/source/vector_tile_source.ts

@@ -11,7 +11,7 @@
 import type {Dispatcher} from '../util/dispatcher';
 import type {Tile} from './tile';
 import type {VectorSourceSpecification, PromoteIdSpecification} from '@maplibre/maplibre-gl-style-spec';
-import type {WorkerTileParameters, WorkerTileResult} from './worker_source';
+import type {WorkerTileParameters, OverzoomParameters, WorkerTileResult} from './worker_source';
 import {MessageType} from '../util/actor_messages';
 
 export type VectorTileSourceOptions = VectorSourceSpecification & {
@@ -202,7 +202,8 @@
             pixelRatio: this.map.getPixelRatio(),
             showCollisionBoxes: this.map.showCollisionBoxes,
             promoteId: this.promoteId,
-            subdivisionGranularity: this.map.style.projection.subdivisionGranularity
+            subdivisionGranularity: this.map.style.projection.subdivisionGranularity,
+            overzoomParameters: this._getOverzoomParameters(tile),
         };
         params.request.collectResourceTiming = this._collectResourceTiming;
         let messageType: MessageType.loadTile | MessageType.reloadTile = MessageType.reloadTile;
@@ -236,6 +237,25 @@
         }
     }
 
+    /**
+     * When the requested tile has a higher canonical Z than source maxzoom, pass overzoom parameters so worker can load the
+     * deepest tile at source max zoom to generate sub tiles using geojsonvt for highest performance on vector overscaling
+     */
+    private _getOverzoomParameters(tile: Tile): OverzoomParameters | undefined {
+        if (tile.tileID.canonical.z <= this.maxzoom) {
+            return undefined;
+        }
+        const maxZoomTileID = tile.tileID.scaledTo(this.maxzoom).canonical;
+        const maxZoomTileUrl = maxZoomTileID.url(this.tiles, this.map.getPixelRatio(), this.scheme);
+
+        return {
+            maxZoomTileID,
+            overzoomRequest: this.map._requestManager.transformRequest(maxZoomTileUrl, ResourceType.Tile),
+            maxOverzoom: this.map.getMaxZoom(),
+            tileSize: this.tileSize
+        };
+    }
+
     private _afterTileLoadWorkerResponse(tile: Tile, data: WorkerTileResult) {
         if (data && data.resourceTiming) {
             tile.resourceTiming = data.resourceTiming;