@maplibre/geojson-vt 6.2.0 → 6.3.0

package/src/geojsonvt.ts

@@ -1,10 +1,11 @@
 import {convertToInternal} from './convert';
 import {convertToGeoJSON, featureToGeoJSON} from './deconvert';
+import {getWorldCoordinateHelper, type WorldCoordinateHelper} from './world-coordinate-helper';
 import {wrap} from './wrap';
 import {applySourceDiff, type GeoJSONVTSourceDiff} from './difference';
 import {ClusterTileIndex, defaultClusterOptions} from './cluster-tile-index';
 import {TileIndex} from './tile-index';
-import type {ClusterOrPointFeature, GeoJSONVTTileIndex, GeoJSONVTInternalFeature, GeoJSONVTOptions, GeoJSONVTTile, SuperclusterOptions} from './definitions';
+import type {ClusterOrPointFeature, GeoJSONVTTileIndex, GeoJSONVTInternalFeature, GeoJSONVTOptions, GeoJSONVTTile} from './definitions';
 
 export const defaultOptions: GeoJSONVTOptions = {
     maxZoom: 14,
@@ -20,7 +21,8 @@ export const defaultOptions: GeoJSONVTOptions = {
     cluster: false,
     clusterOptions: defaultClusterOptions,
     debug: 0,
-    worldCoordinates: false
+    coordinates: 'lngLat',
+    wrap: true
 };
 
 /**
@@ -28,12 +30,15 @@ export const defaultOptions: GeoJSONVTOptions = {
  */
 export class GeoJSONVT {
     private options: GeoJSONVTOptions;
+    private worldCoordinateHelper: WorldCoordinateHelper;
     
     private source?: GeoJSONVTInternalFeature[];
+    private unlocated?: Map<string | number, GeoJSON.Feature>;
     private tileIndex: GeoJSONVTTileIndex;
 
     constructor(data: GeoJSON.GeoJSON, options?: GeoJSONVTOptions) {
         options = this.options = Object.assign({}, defaultOptions, options);
+        this.worldCoordinateHelper = getWorldCoordinateHelper(options.coordinates);
 
         const debug = options.debug;
 
@@ -42,8 +47,11 @@ export class GeoJSONVT {
         if (options.maxZoom < 0 || options.maxZoom > 24) throw new Error('maxZoom should be in the 0-24 range');
         if (options.promoteId && options.generateId) throw new Error('promoteId and generateId cannot be used together.');
 
+        // for updateable indexes, keep the properties of the features without coordinates, so that an update can give them some
+        if (options.updateable) this.unlocated = new Map();
+
         // projects and adds simplification info
-        let features = convertToInternal(data, options);
+        let features = convertToInternal(data, options, this.unlocated);
 
         if (debug) {
             console.timeEnd('preprocess data');
@@ -63,7 +71,7 @@ export class GeoJSONVT {
     }
 
     private initializeIndex(features: GeoJSONVTInternalFeature[], options: GeoJSONVTOptions) {
-        this.tileIndex = options.cluster ? new ClusterTileIndex(options.clusterOptions, options.worldCoordinates) : new TileIndex(options);
+        this.tileIndex = options.cluster ? new ClusterTileIndex({...options.clusterOptions, coordinates: options.coordinates, wrap: options.wrap}) : new TileIndex(options);
         if (!features.length) return;
         this.tileIndex.initialize(features);
     }
@@ -95,7 +103,7 @@ export class GeoJSONVT {
         if (!options.updateable) throw new Error('to update tile geojson `updateable` option must be set to true');
 
         // apply diff and collect affected features and updated source that will be used to invalidate tiles
-        let {affected, source} = applySourceDiff(this.source, diff, options);
+        let {affected, source} = applySourceDiff(this.source, diff, options, this.unlocated);
 
         if (filter) {
             ({affected, source} = this.filterUpdate(source, affected, filter));
@@ -111,19 +119,25 @@ export class GeoJSONVT {
     }
 
     /**
-     * Filter an update using a predicate function. Returns the affected and updated source features.
+     * Filter an update using a predicate function, the features an update emptied included, so that one the filter
+     * rejects can't come back with a later update. A feature without a geometry at all isn't passed to the predicate.
+     * Returns the affected and updated source features.
      */
     private filterUpdate(source: GeoJSONVTInternalFeature[], affected: GeoJSONVTInternalFeature[], predicate: (feature: GeoJSON.Feature) => boolean) {
         const removeIds = new Set();
 
         for (const feature of source) {
             if (feature.id == undefined) continue;
-            if (predicate(featureToGeoJSON(feature, this.options.worldCoordinates))) continue;
+            if (predicate(featureToGeoJSON(feature, this.worldCoordinateHelper))) continue;
             affected.push(feature);
             removeIds.add(feature.id);
         }
         source = source.filter(feature => !removeIds.has(feature.id));
 
+        for (const [id, feature] of this.unlocated ?? []) {
+            if (feature.geometry && !predicate(feature)) this.unlocated.delete(id);
+        }
+
         return {affected, source};
     }
 
@@ -132,15 +146,15 @@ export class GeoJSONVT {
      */
     getData(): GeoJSON.GeoJSON {
         if (!this.options.updateable) throw new Error('to retrieve data the `updateable` option must be set to true');
-        return convertToGeoJSON(this.source, this.options.worldCoordinates);
+        return convertToGeoJSON(this.source, this.worldCoordinateHelper);
     }
     
     /**
      * Update supercluster options and regenerate the index.
      * @param cluster - whether to enable clustering
-     * @param clusterOptions - {@link SuperclusterOptions}
+     * @param clusterOptions - {@link SuperclusterOptions} without `coordinates` and `wrap`, which come from the index options
      */
-    updateClusterOptions(cluster: boolean, clusterOptions: SuperclusterOptions) {
+    updateClusterOptions(cluster: boolean, clusterOptions: GeoJSONVTOptions['clusterOptions']) {
         const wasCluster = this.options.cluster;
         this.options.cluster = cluster;
         this.options.clusterOptions = clusterOptions;

package/src/index.ts

@@ -1,6 +1,6 @@
 
 import type {GeoJSONVTFeatureDiff, GeoJSONVTSourceDiff} from './difference';
-import type {GeoJSONVTInternalFeature, GeoJSONVTInternalLineStringFeature, GeoJSONVTInternalMultiLineStringFeature, GeoJSONVTInternalMultiPointFeature, GeoJSONVTInternalMultiPolygonFeature, GeoJSONVTInternalPointFeature, GeoJSONVTInternalPolygonFeature, GeoJSONVTOptions, GeoJSONToTileOptions, PartialGeoJSONVTFeature, SliceArray, SliceFixedArray, ClusterProperties, ClusterFeature, ClusterOrPointFeature, GeoJSONVTTile, GeoJSONVTFeature, GeoJSONVTFeaturePoint, GeoJSONVTFeatureNonPoint, GeoJSONVTInternalTileFeaturePoint, GeoJSONVTInternalTileFeatureNonPoint, GeoJSONVTInternalTile, GeoJSONVTInternalTileFeature, GeoJSONVTTileIndex, SuperclusterOptions} from './definitions';
+import type {GeoJSONVTInternalFeature, GeoJSONVTInternalLineStringFeature, GeoJSONVTInternalMultiLineStringFeature, GeoJSONVTInternalMultiPointFeature, GeoJSONVTInternalMultiPolygonFeature, GeoJSONVTInternalPointFeature, GeoJSONVTInternalPolygonFeature, GeoJSONVTOptions, GeoJSONToTileOptions, PartialGeoJSONVTFeature, SliceArray, SliceFixedArray, ClusterProperties, ClusterFeature, ClusterOrPointFeature, GeoJSONVTTile, GeoJSONVTFeature, GeoJSONVTFeaturePoint, GeoJSONVTFeatureNonPoint, GeoJSONVTInternalTileFeaturePoint, GeoJSONVTInternalTileFeatureNonPoint, GeoJSONVTInternalTile, GeoJSONVTInternalTileFeature, GeoJSONVTTileIndex, SuperclusterOptions, GeoJSONVTCoordinatesType} from './definitions';
 import type {KDBushWithData} from './cluster-tile-index';
 import {GeoJSONVT} from './geojsonvt';
 import {ClusterTileIndex} from './cluster-tile-index';
@@ -39,6 +39,7 @@ export type {
     GeoJSONVTInternalPolygonFeature,
     GeoJSONVTInternalMultiPolygonFeature,
     SuperclusterOptions,
+    GeoJSONVTCoordinatesType,
     ClusterProperties,
     ClusterFeature,
     ClusterOrPointFeature,

package/src/tile-index.ts

@@ -84,7 +84,7 @@ export class TileIndex implements GeoJSONVTTileIndex {
         const {extent, debug} = this.options;
         
         const z2 = 1 << z;
-        if (this.options.worldCoordinates && (x < 0 || x >= z2)) return null; // a row outside the world has no tile either
+        if (!this.options.wrap && (x < 0 || x >= z2)) return null; // a row outside the world has no tile either
         x = (x + z2) & (z2 - 1); // wrap tile x coordinate
 
         const id = toID(z, x, y);
@@ -122,14 +122,16 @@ export class TileIndex implements GeoJSONVTTileIndex {
     }
 
     /**
-     * The features the top tile starts from: all of them in a wrapping world, where wrapping already put them inside,
-     * and only what lies inside the world square and its buffer with `worldCoordinates`. The index keeps the rest, so
-     * an update can still move a feature in from outside.
+     * The features the top tile starts from. A world that wraps keeps them all left and right, where wrapping already
+     * put them inside, and one that doesn't only what lies inside the world square and its buffer. Positions in the
+     * unit square are also cut above and below in a world that wraps, where lng/lat is clamped already. The index keeps
+     * the rest, so an update can still move a feature in from outside.
      */
     private clipToWorld(features: GeoJSONVTInternalFeature[]): GeoJSONVTInternalFeature[] {
-        if (!this.options.worldCoordinates) return features;
+        const {wrap, coordinates} = this.options;
+        if (wrap && coordinates !== 'unitSquare') return features;
         const buffer = this.options.buffer / this.options.extent;
-        const inX = clip(features, 1, -buffer, 1 + buffer, AxisType.X, -Infinity, Infinity, this.options) || [];
+        const inX = wrap ? features : clip(features, 1, -buffer, 1 + buffer, AxisType.X, -Infinity, Infinity, this.options) || [];
         return clip(inX, 1, -buffer, 1 + buffer, AxisType.Y, -Infinity, Infinity, this.options) || [];
     }
 

package/src/world-coordinate-helper.ts

@@ -0,0 +1,63 @@
+import type {GeoJSONVTCoordinatesType} from './definitions';
+
+/**
+ * How the positions of the input relate to the world square the tiles cover, in which x and y run from 0 to 1.
+ */
+export interface WorldCoordinateHelper {
+    projectX(x: number): number;
+    projectY(y: number): number;
+    unprojectX(x: number): number;
+    unprojectY(y: number): number;
+}
+
+/**
+ * Longitude and latitude, which spherical mercator puts in the world square.
+ */
+class MercatorWorldCoordinateHelper implements WorldCoordinateHelper {
+    projectX(lng: number): number {
+        return lng / 360 + 0.5;
+    }
+
+    projectY(lat: number): number {
+        const sin = Math.sin(lat * Math.PI / 180);
+        const y = 0.5 - 0.25 * Math.log((1 + sin) / (1 - sin)) / Math.PI;
+        return y < 0 ? 0 : y > 1 ? 1 : y;
+    }
+
+    unprojectX(x: number): number {
+        return (x - 0.5) * 360;
+    }
+
+    unprojectY(y: number): number {
+        const y2 = (180 - y * 360) * Math.PI / 180;
+        return 360 * Math.atan(Math.exp(y2)) / Math.PI - 90;
+    }
+}
+
+/**
+ * Positions in the unit square already, see `coordinates` in {@link GeoJSONVTOptions}.
+ */
+class IdentityWorldCoordinateHelper implements WorldCoordinateHelper {
+    projectX(x: number): number {
+        return x;
+    }
+
+    projectY(y: number): number {
+        return y;
+    }
+
+    unprojectX(x: number): number {
+        return x;
+    }
+
+    unprojectY(y: number): number {
+        return y;
+    }
+}
+
+export const mercatorWorldCoordinateHelper: WorldCoordinateHelper = new MercatorWorldCoordinateHelper();
+const identityWorldCoordinateHelper: WorldCoordinateHelper = new IdentityWorldCoordinateHelper();
+
+export function getWorldCoordinateHelper(coordinates?: GeoJSONVTCoordinatesType): WorldCoordinateHelper {
+    return coordinates === 'unitSquare' ? identityWorldCoordinateHelper : mercatorWorldCoordinateHelper;
+}

package/src/wrap.ts

@@ -4,7 +4,7 @@ import type { GeoJSONVTInternalFeature, GeoJSONVTOptions, SliceArray, SliceFixed
 import {createFeature, optimizeLineMemory} from './feature';
 
 export function wrap(features: GeoJSONVTInternalFeature[], options: GeoJSONVTOptions): GeoJSONVTInternalFeature[] {
-    if (options.worldCoordinates) return features;
+    if (!options.wrap) return features;
 
     const buffer = options.buffer / options.extent;
     let merged = features;