@loaders.gl/mvt 4.2.1 → 4.3.0-alpha.2

package/src/lib/vector-tile/vector-tile-feature.ts

@@ -0,0 +1,416 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+// This code is forked from https://github.com/mapbox/vector-tile-js under BSD 3-clause license.
+import {Feature} from '@loaders.gl/schema';
+import {FlatFeature, FlatIndexedGeometry, GeojsonGeometryInfo} from '@loaders.gl/schema';
+import Protobuf from 'pbf';
+import {classifyRings, classifyRingsFlat} from '../utils/geometry-utils';
+import {projectToLngLat, projectToLngLatFlat} from '../utils/geometry-utils';
+import {convertToLocalCoordinates, convertToLocalCoordinatesFlat} from '../utils/geometry-utils';
+
+export class VectorTileFeature {
+  properties: {[x: string]: string | number | boolean | null};
+  extent: any;
+  type: number;
+  id: number | null;
+  _pbf: Protobuf;
+  _geometry: number;
+  _keys: string[];
+  _values: (string | number | boolean | null)[];
+  _geometryInfo: GeojsonGeometryInfo;
+
+  static types: Readonly<string[]> = ['Unknown', 'Point', 'LineString', 'Polygon'];
+
+  // eslint-disable-next-line max-params
+  constructor(
+    pbf: Protobuf,
+    end: number,
+    extent: any,
+    keys: string[],
+    values: (string | number | boolean | null)[],
+    geometryInfo?: GeojsonGeometryInfo
+  ) {
+    // Public
+    this.properties = {};
+    this.extent = extent;
+    this.type = 0;
+    this.id = null;
+
+    // Private
+    this._pbf = pbf;
+    this._geometry = -1;
+    this._keys = keys;
+    this._values = values;
+
+    // Only used by binary tiles
+    this._geometryInfo = geometryInfo!;
+
+    pbf.readFields(readFeature, this, end);
+  }
+
+  toGeoJSONFeature(
+    coordinates: 'wgs84' | 'local',
+    tileIndex?: {x: number; y: number; z: number}
+  ): Feature {
+    const coords = this.loadGeometry();
+
+    switch (coordinates) {
+      case 'wgs84':
+        return _toGeoJSONFeature(this, coords, (line: number[][]) =>
+          projectToLngLat(line, tileIndex!, this.extent)
+        );
+
+      default:
+        return _toGeoJSONFeature(this, coords, convertToLocalCoordinates);
+    }
+  }
+  /**
+   *
+   * @param options
+   * @returns
+   */
+  toBinaryFeature(
+    coordinates: 'wgs84' | 'local',
+    tileIndex?: {x: number; y: number; z: number}
+  ): FlatFeature {
+    const geom = this.loadFlatGeometry();
+
+    switch (coordinates) {
+      case 'wgs84':
+        return this._toBinaryCoordinates(geom, (coords: number[]) =>
+          projectToLngLatFlat(coords, tileIndex!, this.extent)
+        );
+
+      default:
+        return this._toBinaryCoordinates(geom, convertToLocalCoordinatesFlat);
+    }
+  }
+
+  /** Read a bounding box from the feature */
+  // eslint-disable-next-line max-statements
+  bbox() {
+    const pbf = this._pbf;
+    pbf.pos = this._geometry;
+
+    const end = pbf.readVarint() + pbf.pos;
+    let cmd = 1;
+    let length = 0;
+    let x = 0;
+    let y = 0;
+    let x1 = Infinity;
+    let x2 = -Infinity;
+    let y1 = Infinity;
+    let y2 = -Infinity;
+
+    while (pbf.pos < end) {
+      if (length <= 0) {
+        const cmdLen = pbf.readVarint();
+        cmd = cmdLen & 0x7;
+        length = cmdLen >> 3;
+      }
+
+      length--;
+
+      if (cmd === 1 || cmd === 2) {
+        x += pbf.readSVarint();
+        y += pbf.readSVarint();
+        if (x < x1) x1 = x;
+        if (x > x2) x2 = x;
+        if (y < y1) y1 = y;
+        if (y > y2) y2 = y;
+      } else if (cmd !== 7) {
+        throw new Error(`unknown command ${cmd}`);
+      }
+    }
+
+    return [x1, y1, x2, y2];
+  }
+
+  // BINARY HELPERS
+
+  /**
+   *
+   * @param transform
+   * @returns result
+   */
+  _toBinaryCoordinates(
+    geom: FlatIndexedGeometry,
+    transform: (data: number[], extent: number) => void
+  ) {
+    let geometry;
+
+    // Apply the supplied transformation to data
+    transform(geom.data, this.extent);
+
+    const coordLength = 2;
+
+    // eslint-disable-next-line default-case
+    switch (this.type) {
+      case 1: // Point
+        this._geometryInfo.pointFeaturesCount++;
+        this._geometryInfo.pointPositionsCount += geom.indices.length;
+        geometry = {type: 'Point', ...geom};
+        break;
+
+      case 2: // LineString
+        this._geometryInfo.lineFeaturesCount++;
+        this._geometryInfo.linePathsCount += geom.indices.length;
+        this._geometryInfo.linePositionsCount += geom.data.length / coordLength;
+        geometry = {type: 'LineString', ...geom};
+        break;
+
+      case 3: // Polygon
+        geometry = classifyRingsFlat(geom);
+
+        // Unlike Point & LineString geom.indices is a 2D array, thanks
+        // to the classifyRings method
+        this._geometryInfo.polygonFeaturesCount++;
+        this._geometryInfo.polygonObjectsCount += geometry.indices.length;
+
+        for (const indices of geometry.indices) {
+          this._geometryInfo.polygonRingsCount += indices.length;
+        }
+        this._geometryInfo.polygonPositionsCount += geometry.data.length / coordLength;
+
+        break;
+      default:
+        throw new Error(`Invalid geometry type: ${this.type}`);
+    }
+
+    const result: FlatFeature = {type: 'Feature', geometry, properties: this.properties};
+
+    if (this.id !== null) {
+      result.id = this.id;
+    }
+
+    return result;
+  }
+
+  // GEOJSON HELPER
+
+  // eslint-disable-next-line complexity, max-statements
+  loadGeometry(): number[][][] {
+    const pbf = this._pbf;
+    pbf.pos = this._geometry;
+
+    const end = pbf.readVarint() + pbf.pos;
+    let cmd = 1;
+    let length = 0;
+    let x = 0;
+    let y = 0;
+    const lines: number[][][] = [];
+    let line: number[][] | undefined;
+
+    while (pbf.pos < end) {
+      if (length <= 0) {
+        const cmdLen = pbf.readVarint();
+        cmd = cmdLen & 0x7;
+        length = cmdLen >> 3;
+      }
+
+      length--;
+
+      switch (cmd) {
+        case 1:
+        case 2:
+          x += pbf.readSVarint();
+          y += pbf.readSVarint();
+
+          if (cmd === 1) {
+            // moveTo
+            if (line) lines.push(line);
+            line = [];
+          }
+          if (line) line.push([x, y]);
+          break;
+        case 7:
+          // Workaround for https://github.com/mapbox/mapnik-vector-tile/issues/90
+          if (line) {
+            line.push(line[0].slice()); // closePolygon
+          }
+          break;
+        default:
+          throw new Error(`unknown command ${cmd}`);
+      }
+    }
+
+    if (line) lines.push(line);
+
+    return lines;
+  }
+
+  /**
+   * Expands the protobuf data to an intermediate Flat GeoJSON
+   * data format, which maps closely to the binary data buffers.
+   * It is similar to GeoJSON, but rather than storing the coordinates
+   * in multidimensional arrays, we have a 1D `data` with all the
+   * coordinates, and then index into this using the `indices`
+   * parameter, e.g.
+   *
+   * geometry: {
+   *   type: 'Point', data: [1,2], indices: [0]
+   * }
+   * geometry: {
+   *   type: 'LineString', data: [1,2,3,4,...], indices: [0]
+   * }
+   * geometry: {
+   *   type: 'Polygon', data: [1,2,3,4,...], indices: [[0, 2]]
+   * }
+   * Thus the indices member lets us look up the relevant range
+   * from the data array.
+   * The Multi* versions of the above types share the same data
+   * structure, just with multiple elements in the indices array
+   */
+  // eslint-disable-next-line complexity, max-statements
+  loadFlatGeometry(): FlatIndexedGeometry {
+    const pbf = this._pbf;
+    pbf.pos = this._geometry;
+
+    const endPos = pbf.readVarint() + pbf.pos;
+    let cmd = 1;
+    let cmdLen: number;
+    let length = 0;
+    let x = 0;
+    let y = 0;
+    let i = 0;
+
+    // Note: I attempted to replace the `data` array with a
+    // Float32Array, but performance was worse, both using
+    // `set()` and direct index access. Also, we cannot
+    // know how large the buffer should be, so it would
+    // increase memory usage
+    const indices: number[] = []; // Indices where geometries start
+    const data: number[] = []; // Flat array of coordinate data
+
+    while (pbf.pos < endPos) {
+      if (length <= 0) {
+        cmdLen = pbf.readVarint();
+        cmd = cmdLen & 0x7;
+        length = cmdLen >> 3;
+      }
+
+      length--;
+
+      if (cmd === 1 || cmd === 2) {
+        x += pbf.readSVarint();
+        y += pbf.readSVarint();
+
+        if (cmd === 1) {
+          // New line
+          indices.push(i);
+        }
+        data.push(x, y);
+        i += 2;
+      } else if (cmd === 7) {
+        // Workaround for https://github.com/mapbox/mapnik-vector-tile/issues/90
+        if (i > 0) {
+          const start = indices[indices.length - 1]; // start index of polygon
+          data.push(data[start], data[start + 1]); // closePolygon
+          i += 2;
+        }
+      } else {
+        throw new Error(`unknown command ${cmd}`);
+      }
+    }
+
+    return {data, indices};
+  }
+}
+
+function _toGeoJSONFeature(
+  vtFeature: VectorTileFeature,
+  coords: number[][][],
+  transform: (data: number[][], extent: number) => void
+): Feature {
+  let type = VectorTileFeature.types[vtFeature.type];
+  let i: number;
+  let j: number;
+
+  let coordinates: number[][] | number[][][] | number[][][][];
+  switch (vtFeature.type) {
+    case 1:
+      const points: number[][] = [];
+      for (i = 0; i < coords.length; i++) {
+        points[i] = coords[i][0];
+      }
+      coordinates = points;
+      transform(coordinates, vtFeature.extent);
+      break;
+
+    case 2:
+      coordinates = coords;
+      for (i = 0; i < coordinates.length; i++) {
+        transform(coordinates[i], vtFeature.extent);
+      }
+      break;
+
+    case 3:
+      coordinates = classifyRings(coords);
+      for (i = 0; i < coordinates.length; i++) {
+        for (j = 0; j < coordinates[i].length; j++) {
+          transform(coordinates[i][j], vtFeature.extent);
+        }
+      }
+      break;
+
+    default:
+      throw new Error('illegal vector tile type');
+  }
+
+  if (coordinates.length === 1) {
+    // @ts-expect-error
+    coordinates = coordinates[0];
+  } else {
+    type = `Multi${type}`;
+  }
+
+  const result: Feature = {
+    type: 'Feature',
+    geometry: {
+      type: type as any,
+      coordinates: coordinates as any
+    },
+    properties: vtFeature.properties
+  };
+
+  if (vtFeature.id !== null) {
+    result.properties ||= {};
+    result.properties.id = vtFeature.id;
+  }
+
+  return result;
+}
+
+// PBF READER UTILS
+
+/**
+ *
+ * @param tag
+ * @param feature
+ * @param pbf
+ */
+function readFeature(tag: number, feature?: VectorTileFeature, pbf?: Protobuf): void {
+  if (feature && pbf) {
+    if (tag === 1) feature.id = pbf.readVarint();
+    else if (tag === 2) readTag(pbf, feature);
+    else if (tag === 3) feature.type = pbf.readVarint();
+    else if (tag === 4) feature._geometry = pbf.pos;
+  }
+}
+
+/**
+ *
+ * @param pbf
+ * @param feature
+ */
+function readTag(pbf: Protobuf, feature: VectorTileFeature): void {
+  const end = pbf.readVarint() + pbf.pos;
+
+  while (pbf.pos < end) {
+    const key = feature._keys[pbf.readVarint()];
+    const value = feature._values[pbf.readVarint()];
+    feature.properties[key] = value;
+  }
+}

package/src/lib/{mapbox-vector-tile → vector-tile}/vector-tile-layer.ts

@@ -7,6 +7,7 @@
 
 import Protobuf from 'pbf';
 import {VectorTileFeature} from './vector-tile-feature';
+import {GeojsonGeometryInfo} from '@loaders.gl/schema';
 
 export class VectorTileLayer {
   version: number;
@@ -17,6 +18,7 @@ export class VectorTileLayer {
   _keys: string[];
   _values: (string | number | boolean | null)[];
   _features: number[];
+
   constructor(pbf: Protobuf, end: number) {
     // Public
     this.version = 1;
@@ -40,8 +42,7 @@ export class VectorTileLayer {
    * @param index
    * @returns feature
    */
-
-  feature(i: number): VectorTileFeature {
+  getGeoJSONFeature(i: number): VectorTileFeature {
     if (i < 0 || i >= this._features.length) {
       throw new Error('feature index out of bounds');
     }
@@ -51,6 +52,31 @@ export class VectorTileLayer {
     const end = this._pbf.readVarint() + this._pbf.pos;
     return new VectorTileFeature(this._pbf, end, this.extent, this._keys, this._values);
   }
+
+  /**
+   * return binary feature `i` from this layer as a `VectorTileFeature`
+   *
+   * @param index
+   * @param geometryInfo
+   * @returns binary feature
+   */
+  getBinaryFeature(i: number, geometryInfo: GeojsonGeometryInfo): VectorTileFeature {
+    if (i < 0 || i >= this._features.length) {
+      throw new Error('feature index out of bounds');
+    }
+
+    this._pbf.pos = this._features[i];
+
+    const end = this._pbf.readVarint() + this._pbf.pos;
+    return new VectorTileFeature(
+      this._pbf,
+      end,
+      this.extent,
+      this._keys,
+      this._values,
+      geometryInfo
+    );
+  }
 }
 
 /**

package/src/lib/{geojson-tiler → vector-tiler}/clip.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 // Forked from https://github.com/mapbox/geojson-vt under compatible ISC license
 
-import type {GeoJSONTileFeature} from './tile';
+import type {TableTileFeature} from './tile';
 import {createFeature} from './feature';
 
 /* eslint-disable no-continue */
@@ -21,7 +21,7 @@ import {createFeature} from './feature';
  */
 // eslint-disable-next-line max-params, complexity, max-statements
 export function clip(
-  features: GeoJSONTileFeature[],
+  features: TableTileFeature[],
   scale: number,
   k1: number,
   k2: number,
@@ -29,7 +29,7 @@ export function clip(
   minAll: number,
   maxAll: number,
   options: {lineMetrics: boolean}
-): GeoJSONTileFeature[] | null {
+): TableTileFeature[] | null {
   k1 /= scale;
   k2 /= scale;
 
@@ -41,7 +41,7 @@ export function clip(
     return null; // trivial reject
   }
 
-  const clipped: GeoJSONTileFeature[] = [];
+  const clipped: TableTileFeature[] = [];
 
   for (const feature of features) {
     const geometry = feature.geometry;

package/src/lib/{geojson-tiler → vector-tiler}/convert.ts

@@ -6,15 +6,17 @@
 /* eslint-disable */
 // @ts-nocheck
 
-import type {Feature} from '@loaders.gl/schema';
-import type {GeoJSONTileFeature} from './tile';
+import type {Feature, FeatureCollection} from '@loaders.gl/schema';
+import type {TableTileFeature} from './tile';
 
 import {simplify} from './simplify';
 import {createFeature} from './feature';
 
-// converts GeoJSON feature into an intermediate projected JSON vector format with simplification data
-
-export function convert(data: Feature, options): GeoJSONTileFeature[] {
+/**
+ * converts a GeoJSON feature into an intermediate projected JSON vector format
+ * with simplification data
+ */
+export function convert(data: Feature | FeatureCollection, options): TableTileFeature[] {
   const features = [];
   if (data.type === 'FeatureCollection') {
     for (let i = 0; i < data.features.length; i++) {
@@ -31,14 +33,22 @@ export function convert(data: Feature, options): GeoJSONTileFeature[] {
 }
 
 export type ConvertFeatureOptions = {
+  /** max zoom to preserve detail on */
   maxZoom?: number;
-  tolerance: number;
-  extent: number;
-  lineMetrics: boolean;
+  /** simplification tolerance (higher means simpler) */
+  tolerance?: number;
+  /** tile extent */
+  extent?: number;
+  /** whether to calculate line metrics */
+  lineMetrics?: boolean;
 };
 
+/**
+ * converts a GeoJSON feature into an intermediate projected JSON vector format
+ * with simplification data
+ */
 function convertFeature(
-  features: GeoJSONTileFeature[],
+  features: TableTileFeature[],
   geojson: Feature,
   options: ConvertFeatureOptions,
   index: number

package/src/lib/{geojson-tiler → vector-tiler}/feature.ts

@@ -3,10 +3,10 @@
 // Copyright (c) vis.gl contributors
 // Forked from https://github.com/mapbox/geojson-vt under compatible ISC license
 
-import {GeoJSONTileFeature} from './tile';
+import {TableTileFeature} from './tile';
 
-export function createFeature(id, type, geom, tags): GeoJSONTileFeature {
-  const feature: GeoJSONTileFeature = {
+export function createFeature(id, type, geom, tags): TableTileFeature {
+  const feature: TableTileFeature = {
     // eslint-disable-next-line
     id: id == null ? null : id,
     type,

package/src/lib/{geojson-tiler → vector-tiler}/tile.ts

@@ -5,7 +5,7 @@
 
 // import type {Feature} from '@loaders.gl/schema';
 
-export type GeoJSONTileFeature = {
+export type TableTileFeature = {
   type: any;
   geometry: any;
 
@@ -20,8 +20,8 @@ export type GeoJSONTileFeature = {
   maxY: number;
 };
 
-export type GeoJSONTile = {
-  features: GeoJSONTileFeature[]; // Feature[]; Doesn't seem JSON compatible??
+export type TableTile = {
+  features: TableTileFeature[]; // Feature[]; Doesn't seem JSON compatible??
   type?: number;
   tags?: Record<string, string>;
 
@@ -53,9 +53,9 @@ export type CreateTileOptions = {
 /**
  * Create a tile from features and tile index
  */
-export function createTile(features: any[], z, tx, ty, options: CreateTileOptions): GeoJSONTile {
+export function createTile(features: any[], z, tx, ty, options: CreateTileOptions): TableTile {
   const tolerance = z === options.maxZoom ? 0 : options.tolerance / ((1 << z) * options.extent);
-  const tile: GeoJSONTile = {
+  const tile: TableTile = {
     features: [],
     numPoints: 0,
     numSimplified: 0,
@@ -77,7 +77,7 @@ export function createTile(features: any[], z, tx, ty, options: CreateTileOption
 }
 
 // eslint-disable-next-line complexity, max-statements
-function addFeature(tile: GeoJSONTile, feature, tolerance: number, options: CreateTileOptions) {
+function addFeature(tile: TableTile, feature, tolerance: number, options: CreateTileOptions) {
   const geom = feature.geometry;
   const type = feature.type;
   const simplified: number[] = [];
@@ -121,14 +121,14 @@ function addFeature(tile: GeoJSONTile, feature, tolerance: number, options: Crea
     }
 
     // @ts-expect-error TODO - create sub type?
-    const tileFeature: GeoJSONTileFeature = {
+    const tileFeature: TableTileFeature = {
       geometry: simplified,
       type:
         type === 'Polygon' || type === 'MultiPolygon'
           ? 3
           : type === 'LineString' || type === 'MultiLineString'
-            ? 2
-            : 1,
+          ? 2
+          : 1,
       tags
     };
     if (feature.id !== null) {
@@ -142,7 +142,7 @@ function addFeature(tile: GeoJSONTile, feature, tolerance: number, options: Crea
 function addLine(
   result,
   geom,
-  tile: GeoJSONTile,
+  tile: TableTile,
   tolerance: number,
   isPolygon: boolean,
   isOuter: boolean

package/src/lib/{geojson-tiler → vector-tiler}/transform.ts

@@ -3,13 +3,13 @@
 // Copyright (c) vis.gl contributors
 // Forked from https://github.com/mapbox/geojson-vt under compatible ISC license
 
-import type {GeoJSONTile} from './tile';
+import type {TableTile} from './tile';
 
 /**
  * Transforms the coordinates of each feature in the given tile from
  * mercator-projected space into (extent x extent) tile space.
  */
-export function transformTile(tile: GeoJSONTile, extent: number): GeoJSONTile {
+export function transformTile(tile: TableTile, extent: number): TableTile {
   if (tile.transformed) {
     return tile;
   }

package/src/lib/{geojson-tiler → vector-tiler}/wrap.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 // Forked from https://github.com/mapbox/geojson-vt under compatible ISC license
 
-import type {GeoJSONTileFeature} from './tile';
+import type {TableTileFeature} from './tile';
 import {clip} from './clip';
 import {createFeature} from './feature';
 
@@ -22,9 +22,9 @@ export type WrapOptions = {
  * @param options buffer and extent
  * @returns
  */
-export function wrap(features: GeoJSONTileFeature[], options: WrapOptions) {
+export function wrap(features: TableTileFeature[], options: WrapOptions) {
   const buffer = options.buffer / options.extent;
-  let merged: GeoJSONTileFeature[] = features;
+  let merged: TableTileFeature[] = features;
   const left = clip(features, 1, -1 - buffer, buffer, 0, -1, 2, options); // left world copy
   const right = clip(features, 1, 1 - buffer, 2 + buffer, 0, -1, 2, options); // right world copy
 
@@ -48,8 +48,8 @@ export function wrap(features: GeoJSONTileFeature[], options: WrapOptions) {
  * @param offset
  * @returns
  */
-function shiftFeatureCoords(features: GeoJSONTileFeature[], offset: number): GeoJSONTileFeature[] {
-  const newFeatures: GeoJSONTileFeature[] = [];
+function shiftFeatureCoords(features: TableTileFeature[], offset: number): TableTileFeature[] {
+  const newFeatures: TableTileFeature[] = [];
 
   for (let i = 0; i < features.length; i++) {
     const feature = features[i];