@maplibre/geojson-vt 6.1.1 → 6.2.0

package/src/cluster-tile-index.ts

@@ -11,7 +11,14 @@ type ClusterOrPointFeatureInternal = ClusterFeatureInternal | GeoJSONVTInternalP
 
 /** @internal */
 export type KDBushWithData = KDBush & {
-    flatData: number[];
+    /**
+     * The projected x and y of each point or cluster, as integers, see `encode`.
+     */
+    flatCoords: Int32Array;
+    /**
+     * The other values of each point or cluster, at the `OFFSET_` positions.
+     */
+    flatData: Int32Array;
 };
 
 export const defaultClusterOptions: Required<SuperclusterOptions> = {
@@ -27,35 +34,82 @@ export const defaultClusterOptions: Required<SuperclusterOptions> = {
     map: (props) => props as Record<string, unknown>
 };
 
-const OFFSET_ZOOM = 2;
-const OFFSET_ID = 3;
-const OFFSET_PARENT = 4;
-const OFFSET_NUM = 5;
-const OFFSET_PROP = 6;
+/**
+ * The highest zoom level to cluster on. A cluster id keeps its zoom level in five bits.
+ */
+const MAX_ZOOM = 30;
+
+/**
+ * Projected coordinates, which are 0 to 1 inside the world, are stored as integers with this many steps per world,
+ * so that they take half the memory of doubles. One step is ~4 cm at the equator.
+ */
+const SCALE = 0x40000000;
+
+/**
+ * The largest value a 32-bit integer holds.
+ */
+const MAX_INTEGER = 0x7fffffff;
+
+/**
+ * A projected coordinate in steps from the center of the world, see `SCALE`.
+ */
+function encode(coord: number): number {
+    return (coord - 0.5) * SCALE;
+}
+
+function decode(value: number): number {
+    return value / SCALE + 0.5;
+}
+
+/**
+ * Whether a projected coordinate fits in a 32-bit integer. One that is more than two worlds from the center of the
+ * world does not, and neither does one that is not a number.
+ */
+function fitsInteger(coord: number): boolean {
+    return Math.abs(encode(coord)) < MAX_INTEGER;
+}
+
+const OFFSET_ZOOM = 0;
+const OFFSET_ID = 1;
+const OFFSET_PARENT = 2;
+const OFFSET_NUM = 3;
+const OFFSET_PROP = 4;
 
 /**
  * This class allow clustering of geojson points.
  */
 export class ClusterTileIndex implements GeoJSONVTTileIndex {
     options: Required<SuperclusterOptions>;
+    /**
+     * A tree per zoom level. A zoom level where no clusters form shares the tree of the zoom level above it.
+     */
     trees: KDBushWithData[];
     stride: number;
     clusterProps: Record<string, unknown>[];
     points: GeoJSONVTInternalPointFeature[];
+    /**
+     * Whether points are in world coordinates, see `worldCoordinates` in {@link GeoJSONVTOptions}. Points outside the
+     * world are then left out of the clusters, tiles at an edge get no points from the opposite one, `getTile` returns
+     * `null` outside the world, and clusters come back in world coordinates.
+     * @experimental
+     */
+    worldCoordinates: boolean;
 
-    constructor(options?: SuperclusterOptions) {
-        this.options = Object.assign(Object.create(defaultClusterOptions), options) as Required<SuperclusterOptions>;
+    constructor(options?: SuperclusterOptions, worldCoordinates = false) {
+        this.options = createOptions(options);
+        this.worldCoordinates = worldCoordinates;
         this.trees = new Array(this.options.maxZoom + 1);
-        this.stride = this.options.reduce ? 7 : 6;
+        this.stride = this.options.reduce ? 5 : 4;
         this.clusterProps = [];
         this.points = [];
     }
 
     /**
-     * Loads GeoJSON point features and builds the internal clustering index.
-     * @param points - GeoJSON point features to cluster.
+     * Loads GeoJSON Point and MultiPoint features and builds the internal clustering index.
+     * Each position of a MultiPoint is clustered as a point of its own, with the id and properties of its feature.
+     * @param points - GeoJSON Point and MultiPoint features to cluster.
      */
-    load(points: GeoJSON.Feature<GeoJSON.Point>[]): void {
+    load(points: GeoJSON.Feature<GeoJSON.Point | GeoJSON.MultiPoint>[]): void {
         const features: GeoJSONVTInternalPointFeature[] = [];
         
         // Convert GeoJSON point features to GeoJSONVT internal point features
@@ -64,17 +118,20 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
                 continue;
             }
 
-            const [lng, lat] = point.geometry.coordinates;
-            const [x, y] = [projectX(lng), projectY(lat)];
-            
-            const feature: GeoJSONVTInternalPointFeature = {
-                id: point.id,
-                type: 'Point',
-                geometry: [x, y],
-                tags: point.properties
-            };
-            
-            features.push(feature);
+            const positions = point.geometry.type === 'MultiPoint' ? point.geometry.coordinates : [point.geometry.coordinates];
+            for (const [lng, lat] of positions) {
+                const [x, y] = [projectX(lng, this.worldCoordinates), projectY(lat, this.worldCoordinates)];
+                if (this.worldCoordinates && !isInWorld([x, y])) continue;
+
+                const feature: GeoJSONVTInternalPointFeature = {
+                    id: point.id,
+                    type: 'Point',
+                    geometry: [x, y],
+                    tags: point.properties
+                };
+
+                features.push(feature);
+            }
         }
         
         this.createIndex(features);
@@ -83,14 +140,25 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
     /**
      * @internal
      * Loads internal GeoJSONVT point features from a data source and builds the clustering index.
+     * Each position of a MultiPoint feature becomes a point of its own, with the id and properties of its feature.
      * @param features - {@link GeoJSONVTInternalFeature} data source features to filter and cluster.
      */
     initialize(features: GeoJSONVTInternalFeature[]): void {
         const points: GeoJSONVTInternalPointFeature[] = [];
 
         for (const feature of features) {
-            if (feature.type !== 'Point') continue;
-            points.push(feature);
+            if (feature.type === 'Point') {
+                if (this.worldCoordinates && !isInWorld(feature.geometry)) continue;
+                points.push(feature);
+                continue;
+            }
+            if (feature.type !== 'MultiPoint') continue;
+
+            for (let i = 0; i < feature.geometry.length; i += 3) {
+                const geometry = [feature.geometry[i], feature.geometry[i + 1]];
+                if (this.worldCoordinates && !isInWorld(geometry)) continue;
+                points.push({id: feature.id, type: 'Point', geometry, tags: feature.tags});
+            }
         }
 
         this.createIndex(points);
@@ -102,13 +170,22 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
      * @param features 
      */
     updateIndex(features: GeoJSONVTInternalFeature[], _affected: GeoJSONVTInternalFeature[], options: GeoJSONVTOptions) {
-        this.options = Object.assign(Object.create(defaultClusterOptions), options.clusterOptions) as Required<SuperclusterOptions>;
+        this.options = createOptions(options.clusterOptions);
         this.initialize(features);
     }
 
+    /**
+     * Builds a tree per zoom level from the points. A point whose position does not fit in an integer is left out,
+     * see `fitsInteger`.
+     */
     private createIndex(points: GeoJSONVTInternalPointFeature[]): void {
         const {log, minZoom, maxZoom} = this.options;
 
+        // start over, since the options can have changed since the last build
+        this.trees = new Array(maxZoom + 1);
+        this.stride = this.options.reduce ? 5 : 4;
+        this.clusterProps = [];
+
         if (log) console.time('total time');
 
         const timerId = `prepare ${points.length} points`;
@@ -116,38 +193,46 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
 
         this.points = points;
 
+        const stride = this.stride;
+        const notProcessed = maxZoom + 1;
+
         // generate a cluster object for each point and index input points into a KD-tree
-        const data: number[] = [];
+        const coords = new Int32Array(points.length * 2);
+        const data = new Int32Array(points.length * stride);
+        let numItems = 0;
 
         for (let i = 0; i < points.length; i++) {
             const p = points[i];
-            if (!p?.geometry) continue;
-
-            let [x, y] = p.geometry;
-            x = Math.fround(x);
-            y = Math.fround(y);
+            if (!p?.geometry || !fitsInteger(p.geometry[0]) || !fitsInteger(p.geometry[1])) continue;
 
             // store internal point/cluster data in flat numeric arrays for performance
-            data.push(
-                x, y, // projected point coordinates
-                Infinity, // the last zoom the point was processed at
-                i, // index of the source feature in the original input array
-                -1, // parent cluster id
-                1 // number of points in a cluster
-            );
-            if (this.options.reduce) data.push(0); // noop
+            coords[numItems * 2] = Math.round(encode(p.geometry[0])); // projected point coordinates
+            coords[numItems * 2 + 1] = Math.round(encode(p.geometry[1]));
+            const k = numItems * stride;
+            data[k + OFFSET_ZOOM] = notProcessed; // the last zoom the point was processed at
+            data[k + OFFSET_ID] = i; // index of the source feature in the original input array
+            data[k + OFFSET_PARENT] = -1; // parent cluster id
+            data[k + OFFSET_NUM] = 1; // number of points in a cluster
+            numItems++;
         }
-        let tree = this.trees[maxZoom + 1] = this.createTree(data);
+        let tree = this.trees[maxZoom + 1] = this.createTree(coords, data, numItems);
 
         if (log) console.timeEnd(timerId);
 
         // cluster points on max zoom, then cluster the results on previous zoom, etc.;
         // results in a cluster hierarchy across zoom levels
+        const nextCoords = new Int32Array(numItems * 2);
+        const nextData = new Int32Array(numItems * stride);
         for (let z = maxZoom; z >= minZoom; z--) {
             const now = Date.now();
 
-            // create a new set of clusters for the zoom and index them with a KD-tree
-            tree = this.trees[z] = this.createTree(this.cluster(tree, z));
+            const nextNumItems = this.cluster(tree, z, nextCoords, nextData);
+
+            if (!this.isSameAsTree(tree, nextData, nextNumItems)) {
+                // create a new set of clusters for the zoom and index them with a KD-tree
+                tree = this.createTree(nextCoords.slice(0, nextNumItems * 2), nextData.slice(0, nextNumItems * stride), nextNumItems);
+            }
+            this.trees[z] = tree;
 
             if (log) console.log('z%d: %d clusters in %dms', z, tree.numItems, Date.now() - now);
         }
@@ -157,12 +242,12 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
 
     /**
      * Returns clusters and/or points within a bounding box at a given zoom level.
-     * @param bbox - Bounding box in `[westLng, southLat, eastLng, northLat]` order.
+     * @param bbox - Bounding box in `[westLng, southLat, eastLng, northLat]` order, or `[minX, minY, maxX, maxY]` in world coordinates.
      * @param zoom - Zoom level to query.
      */
     public getClusters(bbox: [number, number, number, number], zoom: number): ClusterOrPointFeature[] {
-        const clusterInternal = this.getClustersInternal(bbox, zoom);
-        return clusterInternal.map((f) => featureToGeoJSON(f) as ClusterOrPointFeature);
+        const clusterInternal = this.worldCoordinates ? this.getClustersInRange(bbox, zoom) : this.getClustersInternal(bbox, zoom);
+        return clusterInternal.map((f) => featureToGeoJSON(f, this.worldCoordinates) as ClusterOrPointFeature);
     }
 
     private getClustersInternal(bbox: [number, number, number, number], zoom: number): ClusterOrPointFeatureInternal[] {
@@ -180,13 +265,21 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
             return easternHem.concat(westernHem);
         }
 
+        return this.getClustersInRange([projectX(minLng), projectY(maxLat), projectX(maxLng), projectY(minLat)], zoom);
+    }
+
+    /**
+     * The clusters and points in a box of the internal coordinates, `[minX, minY, maxX, maxY]`.
+     */
+    private getClustersInRange([minX, minY, maxX, maxY]: [number, number, number, number], zoom: number): ClusterOrPointFeatureInternal[] {
         const tree = this.trees[this.limitZoom(zoom)];
-        const ids = tree.range(projectX(minLng), projectY(maxLat), projectX(maxLng), projectY(minLat));
+        const ids = tree.range(encode(minX), encode(minY), encode(maxX), encode(maxY));
+        const coords = tree.flatCoords;
         const data = tree.flatData;
         const clusters: ClusterOrPointFeatureInternal[] = [];
         for (const id of ids) {
             const k = this.stride * id;
-            clusters.push(data[k + OFFSET_NUM] > 1 ? getClusterFeature(data, k, this.clusterProps) : this.points[data[k + OFFSET_ID]]);
+            clusters.push(data[k + OFFSET_NUM] > 1 ? getClusterFeature(coords, id, data, k, this.clusterProps) : this.points[data[k + OFFSET_ID]]);
         }
         return clusters;
     }
@@ -203,18 +296,19 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
         const tree = this.trees[originZoom];
         if (!tree) throw clusterError;
 
+        const coords = tree.flatCoords;
         const data = tree.flatData;
-        if (originId * this.stride >= data.length) throw clusterError;
+        if (originId >= tree.numItems) throw clusterError;
 
-        const r = this.options.radius / (this.options.extent * Math.pow(2, originZoom - 1));
-        const x = data[originId * this.stride];
-        const y = data[originId * this.stride + 1];
+        const r = this.options.radius / (this.options.extent * Math.pow(2, originZoom - 1)) * SCALE;
+        const x = coords[originId * 2];
+        const y = coords[originId * 2 + 1];
         const ids = tree.within(x, y, r);
         const children: ClusterOrPointFeature[] = [];
         for (const id of ids) {
             const k = id * this.stride;
             if (data[k + OFFSET_PARENT] === clusterId) {
-                children.push(data[k + OFFSET_NUM] > 1 ? getClusterGeoJSON(data, k, this.clusterProps) : featureToGeoJSON(this.points[data[k + OFFSET_ID]]) as GeoJSON.Feature<GeoJSON.Point>);
+                children.push(data[k + OFFSET_NUM] > 1 ? getClusterGeoJSON(coords, id, data, k, this.clusterProps, this.worldCoordinates) : featureToGeoJSON(this.points[data[k + OFFSET_ID]], this.worldCoordinates) as GeoJSON.Feature<GeoJSON.Point>);
             }
         }
 
@@ -251,10 +345,11 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
             return null;
         }
         const z2 = Math.pow(2, z);
+        if (this.worldCoordinates && (x < 0 || x >= z2 || y < 0 || y >= z2)) return null;
         const {extent, radius} = this.options;
         const p = radius / extent;
-        const top = (y - p) / z2;
-        const bottom = (y + 1 + p) / z2;
+        const top = encode((y - p) / z2);
+        const bottom = encode((y + 1 + p) / z2);
 
         const tile: GeoJSONVTTile = {
             transformed: true,
@@ -266,18 +361,18 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
         };
 
         this.addTileFeatures(
-            tree.range((x - p) / z2, top, (x + 1 + p) / z2, bottom),
-            tree.flatData, x, y, z2, tile);
+            tree.range(encode((x - p) / z2), top, encode((x + 1 + p) / z2), bottom),
+            tree, x, y, z2, tile);
 
-        if (x === 0) {
+        if (!this.worldCoordinates && x === 0) {
             this.addTileFeatures(
-                tree.range(1 - p / z2, top, 1, bottom),
-                tree.flatData, z2, y, z2, tile);
+                tree.range(encode(1 - p / z2), top, encode(1), bottom),
+                tree, z2, y, z2, tile);
         }
-        if (x === z2 - 1) {
+        if (!this.worldCoordinates && x === z2 - 1) {
             this.addTileFeatures(
-                tree.range(0, top, p / z2, bottom),
-                tree.flatData, -1, y, z2, tile);
+                tree.range(encode(0), top, encode(p / z2), bottom),
+                tree, -1, y, z2, tile);
         }
 
         return tile;
@@ -319,16 +414,32 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
         return skipped;
     }
 
-    private createTree(data: number[]): KDBushWithData {
-        const tree = new KDBush(data.length / this.stride | 0, this.options.nodeSize, Float32Array) as unknown as KDBushWithData;
-        for (let i = 0; i < data.length; i += this.stride) tree.add(data[i], data[i + 1]);
+    private createTree(coords: Int32Array, data: Int32Array, numItems: number): KDBushWithData {
+        const tree = new KDBush(numItems, this.options.nodeSize, Int32Array) as unknown as KDBushWithData;
+        for (let i = 0; i < numItems; i++) tree.add(coords[i * 2], coords[i * 2 + 1]);
         tree.finish();
+        tree.flatCoords = coords;
         tree.flatData = data;
         tree.data = null; // clear original data to free memory as it isn't used later on.
         return tree;
     }
 
-    private addTileFeatures(ids: number[], data: number[], x: number, y: number, z2: number, tile: GeoJSONVTTile): void {
+    /**
+     * Whether clustering a tree left all its points and clusters as they were, in the same order.
+     */
+    private isSameAsTree(tree: KDBushWithData, nextData: Int32Array, nextNumItems: number): boolean {
+        if (nextNumItems !== tree.numItems) return false;
+
+        const data = tree.flatData;
+        for (let k = OFFSET_ID; k < nextNumItems * this.stride; k += this.stride) {
+            if (nextData[k] !== data[k]) return false;
+        }
+        return true;
+    }
+
+    private addTileFeatures(ids: number[], tree: KDBushWithData, x: number, y: number, z2: number, tile: GeoJSONVTTile): void {
+        const coords = tree.flatCoords;
+        const data = tree.flatData;
         for (const i of ids) {
             const k = i * this.stride;
             const isCluster = data[k + OFFSET_NUM] > 1;
@@ -338,8 +449,8 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
             let py: number;
             if (isCluster) {
                 tags = getClusterProperties(data, k, this.clusterProps);
-                px = data[k];
-                py = data[k + 1];
+                px = decode(coords[i * 2]);
+                py = decode(coords[i * 2 + 1]);
             } else {
                 const p = this.points[data[k + OFFSET_ID]];
                 tags = p.tags;
@@ -375,30 +486,38 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
         return Math.max(this.options.minZoom, Math.min(Math.floor(+z), this.options.maxZoom + 1));
     }
 
-    private cluster(tree: KDBushWithData, zoom: number): number[] {
-        const {radius, extent, reduce, minPoints} = this.options;
-        const r = radius / (extent * Math.pow(2, zoom));
+    /**
+     * Clusters the points of a tree on a zoom level, writing the result to `nextCoords` and `nextData`.
+     * @returns the number of points and clusters written
+     */
+    private cluster(tree: KDBushWithData, zoom: number, nextCoords: Int32Array, nextData: Int32Array): number {
+        const {radius, extent, reduce, minPoints, maxZoom} = this.options;
+        const r = radius / (extent * Math.pow(2, zoom)) * SCALE;
+        const notProcessed = maxZoom + 1;
+        const coords = tree.flatCoords;
         const data = tree.flatData;
-        const nextData: number[] = [];
         const stride = this.stride;
+        const neighborIds = new Uint32Array(tree.numItems);
+        let nextNumItems = 0;
 
         // loop through each point
-        for (let i = 0; i < data.length; i += stride) {
+        for (let index = 0; index < tree.numItems; index++) {
+            const i = index * stride;
             // if we've already visited the point at this zoom level, skip it
             if (data[i + OFFSET_ZOOM] <= zoom) continue;
             data[i + OFFSET_ZOOM] = zoom;
 
             // find all nearby points
-            const x = data[i];
-            const y = data[i + 1];
-            const neighborIds = tree.within(data[i], data[i + 1], r);
+            const x = coords[index * 2];
+            const y = coords[index * 2 + 1];
+            const numNeighbors = tree.withinInto(x, y, r, neighborIds);
 
             const numPointsOrigin = data[i + OFFSET_NUM];
             let numPoints = numPointsOrigin;
 
             // count the number of points in a potential cluster
-            for (const neighborId of neighborIds) {
-                const k = neighborId * stride;
+            for (let n = 0; n < numNeighbors; n++) {
+                const k = neighborIds[n] * stride;
                 // filter out neighbors that are already processed
                 if (data[k + OFFSET_ZOOM] > zoom) numPoints += data[k + OFFSET_NUM];
             }
@@ -412,17 +531,18 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
                 let clusterPropIndex = -1;
 
                 // encode both zoom and point index on which the cluster originated -- offset by total length of features
-                const id = ((i / stride | 0) << 5) + (zoom + 1) + this.points.length;
+                const id = (index << 5) + (zoom + 1) + this.points.length;
 
-                for (const neighborId of neighborIds) {
-                    const k = neighborId * stride;
+                for (let n = 0; n < numNeighbors; n++) {
+                    const neighborIndex = neighborIds[n];
+                    const k = neighborIndex * stride;
 
                     if (data[k + OFFSET_ZOOM] <= zoom) continue;
                     data[k + OFFSET_ZOOM] = zoom; // save the zoom (so it doesn't get processed twice)
 
                     const numPoints2 = data[k + OFFSET_NUM];
-                    wx += data[k] * numPoints2; // accumulate coordinates for calculating weighted center
-                    wy += data[k + 1] * numPoints2;
+                    wx += coords[neighborIndex * 2] * numPoints2; // accumulate coordinates for calculating weighted center
+                    wy += coords[neighborIndex * 2 + 1] * numPoints2;
 
                     data[k + OFFSET_PARENT] = id;
 
@@ -437,24 +557,38 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
                 }
 
                 data[i + OFFSET_PARENT] = id;
-                nextData.push(wx / numPoints, wy / numPoints, Infinity, id, -1, numPoints);
-                if (reduce) nextData.push(clusterPropIndex);
+                nextCoords[nextNumItems * 2] = Math.round(wx / numPoints);
+                nextCoords[nextNumItems * 2 + 1] = Math.round(wy / numPoints);
+                const next = nextNumItems * stride;
+                nextData[next + OFFSET_ZOOM] = notProcessed;
+                nextData[next + OFFSET_ID] = id;
+                nextData[next + OFFSET_PARENT] = -1;
+                nextData[next + OFFSET_NUM] = numPoints;
+                if (reduce) nextData[next + OFFSET_PROP] = clusterPropIndex;
+                nextNumItems++;
 
             } else { // left points as unclustered
-                for (let j = 0; j < stride; j++) nextData.push(data[i + j]);
+                nextCoords[nextNumItems * 2] = x;
+                nextCoords[nextNumItems * 2 + 1] = y;
+                for (let j = 0; j < stride; j++) nextData[nextNumItems * stride + j] = data[i + j];
+                nextNumItems++;
 
                 if (numPoints > 1) {
-                    for (const neighborId of neighborIds) {
-                        const k = neighborId * stride;
+                    for (let n = 0; n < numNeighbors; n++) {
+                        const neighborIndex = neighborIds[n];
+                        const k = neighborIndex * stride;
                         if (data[k + OFFSET_ZOOM] <= zoom) continue;
                         data[k + OFFSET_ZOOM] = zoom;
-                        for (let j = 0; j < stride; j++) nextData.push(data[k + j]);
+                        nextCoords[nextNumItems * 2] = coords[neighborIndex * 2];
+                        nextCoords[nextNumItems * 2 + 1] = coords[neighborIndex * 2 + 1];
+                        for (let j = 0; j < stride; j++) nextData[nextNumItems * stride + j] = data[k + j];
+                        nextNumItems++;
                     }
                 }
             }
         }
 
-        return nextData;
+        return nextNumItems;
     }
 
     // get index of the point from which the cluster originated
@@ -467,7 +601,7 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
         return (clusterId - this.points.length) % 32;
     }
 
-    private map(data: number[], i: number, clone?: boolean): Record<string, unknown> {
+    private map(data: Int32Array, i: number, clone?: boolean): Record<string, unknown> {
         if (data[i + OFFSET_NUM] > 1) {
             const props = this.clusterProps[data[i + OFFSET_PROP]];
             return clone ? Object.assign({}, props) : props;
@@ -478,28 +612,35 @@ export class ClusterTileIndex implements GeoJSONVTTileIndex {
     }
 }
 
-function getClusterFeature(data: number[], i: number, clusterProps: Record<string, unknown>[]): ClusterFeatureInternal {
+function createOptions(options?: SuperclusterOptions): Required<SuperclusterOptions> {
+    const result = Object.assign(Object.create(defaultClusterOptions), options) as Required<SuperclusterOptions>;
+    result.minZoom = Math.min(result.minZoom, MAX_ZOOM);
+    result.maxZoom = Math.min(result.maxZoom, MAX_ZOOM);
+    return result;
+}
+
+function getClusterFeature(coords: Int32Array, index: number, data: Int32Array, i: number, clusterProps: Record<string, unknown>[]): ClusterFeatureInternal {
     return {
         id: data[i + OFFSET_ID],
         type: 'Point',
         tags: getClusterProperties(data, i, clusterProps),
-        geometry: [data[i], data[i + 1]]
+        geometry: [decode(coords[index * 2]), decode(coords[index * 2 + 1])]
     };
 }
 
-function getClusterGeoJSON(data: number[], i: number, clusterProps: Record<string, unknown>[]): ClusterFeature {
+function getClusterGeoJSON(coords: Int32Array, index: number, data: Int32Array, i: number, clusterProps: Record<string, unknown>[], worldCoordinates: boolean): ClusterFeature {
     return {
         type: 'Feature',
         id: data[i + OFFSET_ID],
         properties: getClusterProperties(data, i, clusterProps),
         geometry: {
             type: 'Point',
-            coordinates: [unprojectX(data[i]), unprojectY(data[i + 1])]
+            coordinates: [unprojectX(decode(coords[index * 2]), worldCoordinates), unprojectY(decode(coords[index * 2 + 1]), worldCoordinates)]
         }
     };
 }
 
-function getClusterProperties(data: number[], i: number, clusterProps: Record<string, unknown>[]): ClusterProperties {
+function getClusterProperties(data: Int32Array, i: number, clusterProps: Record<string, unknown>[]): ClusterProperties {
     const count = data[i + OFFSET_NUM];
     const abbrev =
         count >= 10000 ? `${Math.round(count / 1000)  }k` :
@@ -514,3 +655,7 @@ function getClusterProperties(data: number[], i: number, clusterProps: Record<st
         point_count_abbreviated: abbrev
     });
 }
+
+function isInWorld(geometry: number[]): boolean {
+    return geometry[0] >= 0 && geometry[0] <= 1 && geometry[1] >= 0 && geometry[1] <= 1;
+}