@loaders.gl/mvt 3.2.0-alpha.1 → 3.2.0-alpha.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loaders.gl/mvt",
   "description": "Loader for Mapbox Vector Tiles",
-  "version": "3.2.0-alpha.1",
+  "version": "3.2.0-alpha.4",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -32,14 +32,14 @@
     "build-worker": "esbuild src/workers/mvt-worker.ts --bundle --outfile=dist/mvt-worker.js --define:__VERSION__=\\\"$npm_package_version\\\""
   },
   "dependencies": {
-    "@loaders.gl/gis": "3.2.0-alpha.1",
-    "@loaders.gl/loader-utils": "3.2.0-alpha.1",
-    "@loaders.gl/schema": "3.2.0-alpha.1",
+    "@loaders.gl/gis": "3.2.0-alpha.4",
+    "@loaders.gl/loader-utils": "3.2.0-alpha.4",
+    "@loaders.gl/schema": "3.2.0-alpha.4",
     "@math.gl/polygon": "^3.5.1",
     "pbf": "^3.2.1"
   },
   "devDependencies": {
     "@types/pbf": "^3.0.2"
   },
-  "gitHead": "423a2815092b08dcf93ad5b7dc2940b167305afe"
+  "gitHead": "f030d39d5cdedb137e43e757a9da10dd637857fd"
 }

package/src/helpers/mapbox-util-functions.ts

@@ -1,5 +1,5 @@
 import Protobuf from 'pbf';
-import {MvtMapboxGeometry} from '../lib/types';
+import {MVTMapboxGeometry} from '../lib/types';
 import VectorTileFeature from '../lib/mapbox-vector-tile/vector-tile-feature';
 
 /**
@@ -7,7 +7,7 @@ import VectorTileFeature from '../lib/mapbox-vector-tile/vector-tile-feature';
  * @param rings
  * @returns polygons
  */
-export function classifyRings(rings: MvtMapboxGeometry) {
+export function classifyRings(rings: MVTMapboxGeometry) {
   const len = rings.length;
 
   if (len <= 1) return [rings];

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

@@ -1,6 +1,6 @@
 // This code is forked from https://github.com/mapbox/vector-tile-js under BSD 3-clause license.
 import Protobuf from 'pbf';
-import {MvtMapboxCoordinates, MvtMapboxGeometry} from '../types';
+import {MVTMapboxCoordinates, MVTMapboxGeometry} from '../types';
 import {readFeature, classifyRings} from '../../helpers/mapbox-util-functions';
 
 export default class VectorTileFeature {
@@ -39,7 +39,7 @@ export default class VectorTileFeature {
   }
 
   // eslint-disable-next-line complexity, max-statements
-  loadGeometry(): MvtMapboxGeometry {
+  loadGeometry(): MVTMapboxGeometry {
     const pbf = this._pbf;
     pbf.pos = this._geometry;
 
@@ -163,7 +163,7 @@ export default class VectorTileFeature {
       type = `Multi${type}`;
     }
 
-    const result: MvtMapboxCoordinates = {
+    const result: MVTMapboxCoordinates = {
       type: 'Feature',
       geometry: {
         type,
@@ -181,7 +181,7 @@ export default class VectorTileFeature {
 
   toGeoJSON(
     options: {x: number; y: number; z: number} | ((data: number[], feature: {extent: any}) => void)
-  ): MvtMapboxCoordinates {
+  ): MVTMapboxCoordinates {
     if (typeof options === 'function') {
       return this._toGeoJSON(options);
     }

package/src/lib/parse-mvt.ts

@@ -1,14 +1,19 @@
-// import {VectorTile} from '@mapbox/vector-tile';
-import VectorTile from './mapbox-vector-tile/vector-tile';
-import BinaryVectorTile from './binary-vector-tile/vector-tile';
-
 import {flatGeojsonToBinary} from '@loaders.gl/gis';
+import type {
+  FlatFeature,
+  Feature,
+  GeojsonGeometryInfo,
+  BinaryFeatures,
+  GeoJSONRowTable
+} from '@loaders.gl/schema';
 import Protobuf from 'pbf';
-import type {FlatFeature} from '@loaders.gl/schema';
-import type {MvtMapboxCoordinates, MvtOptions} from '../lib/types';
+
+import type {MVTMapboxCoordinates, MVTOptions, MVTLoaderOptions} from '../lib/types';
+
+import VectorTile from './mapbox-vector-tile/vector-tile';
+import BinaryVectorTile from './binary-vector-tile/vector-tile';
 import VectorTileFeatureBinary from './binary-vector-tile/vector-tile-feature';
 import VectorTileFeatureMapBox from './mapbox-vector-tile/vector-tile-feature';
-import {LoaderOptions} from '@loaders.gl/loader-utils';
 
 /**
  * Parse MVT arrayBuffer and return GeoJSON.
@@ -17,94 +22,130 @@ import {LoaderOptions} from '@loaders.gl/loader-utils';
  * @param options
  * @returns A GeoJSON geometry object or a binary representation
  */
-export default function parseMVT(arrayBuffer: ArrayBuffer, options?: LoaderOptions) {
-  options = normalizeOptions(options);
-  const features: (FlatFeature | MvtMapboxCoordinates)[] = [];
-
-  if (options) {
-    const binary = options.gis.format === 'binary';
-    const geometryInfo = {
-      coordLength: 2,
-      pointPositionsCount: 0,
-      pointFeaturesCount: 0,
-      linePositionsCount: 0,
-      linePathsCount: 0,
-      lineFeaturesCount: 0,
-      polygonPositionsCount: 0,
-      polygonObjectsCount: 0,
-      polygonRingsCount: 0,
-      polygonFeaturesCount: 0
-    };
-
-    if (arrayBuffer.byteLength > 0) {
-      const tile = binary
-        ? new BinaryVectorTile(new Protobuf(arrayBuffer))
-        : new VectorTile(new Protobuf(arrayBuffer));
-      const loaderOptions = options.mvt;
-
-      const selectedLayers = Array.isArray(loaderOptions.layers)
-        ? loaderOptions.layers
-        : Object.keys(tile.layers);
-
-      selectedLayers.forEach((layerName: string) => {
-        const vectorTileLayer = tile.layers[layerName];
-        const featureOptions = {...loaderOptions, layerName};
-
-        if (!vectorTileLayer) {
-          return;
-        }
-
-        for (let i = 0; i < vectorTileLayer.length; i++) {
-          const vectorTileFeature = vectorTileLayer.feature(i, geometryInfo);
-
-          const decodedFeature = binary
-            ? getDecodedFeatureBinary(vectorTileFeature as VectorTileFeatureBinary, featureOptions)
-            : getDecodedFeature(vectorTileFeature as VectorTileFeatureMapBox, featureOptions);
-          features.push(decodedFeature);
-        }
-      });
+export default function parseMVT(arrayBuffer: ArrayBuffer, options?: MVTLoaderOptions) {
+  const mvtOptions = normalizeOptions(options);
+
+  const shape = options?.gis?.format || options?.mvt?.shape;
+  switch (shape) {
+    case 'columnar-table': // binary + some JS arrays
+      return {shape: 'columnar-table', data: parseToBinary(arrayBuffer, mvtOptions)};
+    case 'geojson-row-table': {
+      const table: GeoJSONRowTable = {
+        shape: 'geojson-row-table',
+        data: parseToGeojson(arrayBuffer, mvtOptions)
+      };
+      return table;
     }
+    case 'geojson':
+      return parseToGeojson(arrayBuffer, mvtOptions);
+    case 'binary-geometry':
+      return parseToBinary(arrayBuffer, mvtOptions);
+    case 'binary':
+      return parseToBinary(arrayBuffer, mvtOptions);
+    default:
+      throw new Error(shape);
+  }
+}
 
-    if (binary) {
-      const data = flatGeojsonToBinary(features as FlatFeature[], geometryInfo);
-      // Add the original byteLength (as a reasonable approximation of the size of the binary data)
-      // TODO decide where to store extra fields like byteLength (header etc) and document
-      // @ts-ignore
-      data.byteLength = arrayBuffer.byteLength;
-      return data;
-    }
+function parseToBinary(arrayBuffer: ArrayBuffer, options: MVTOptions): BinaryFeatures {
+  const [flatGeoJsonFeatures, geometryInfo] = parseToFlatGeoJson(arrayBuffer, options);
+
+  const binaryData = flatGeojsonToBinary(flatGeoJsonFeatures, geometryInfo);
+  // Add the original byteLength (as a reasonable approximation of the size of the binary data)
+  // TODO decide where to store extra fields like byteLength (header etc) and document
+  // @ts-ignore
+  binaryData.byteLength = arrayBuffer.byteLength;
+  return binaryData;
+}
+
+function parseToFlatGeoJson(
+  arrayBuffer: ArrayBuffer,
+  options: MVTOptions
+): [FlatFeature[], GeojsonGeometryInfo] {
+  const features: FlatFeature[] = [];
+  const geometryInfo: GeojsonGeometryInfo = {
+    coordLength: 2,
+    pointPositionsCount: 0,
+    pointFeaturesCount: 0,
+    linePositionsCount: 0,
+    linePathsCount: 0,
+    lineFeaturesCount: 0,
+    polygonPositionsCount: 0,
+    polygonObjectsCount: 0,
+    polygonRingsCount: 0,
+    polygonFeaturesCount: 0
+  };
+
+  if (arrayBuffer.byteLength <= 0) {
+    return [features, geometryInfo];
   }
-  return features;
+
+  const tile = new BinaryVectorTile(new Protobuf(arrayBuffer));
+
+  const selectedLayers =
+    options && Array.isArray(options.layers) ? options.layers : Object.keys(tile.layers);
+
+  selectedLayers.forEach((layerName: string) => {
+    const vectorTileLayer = tile.layers[layerName];
+    if (!vectorTileLayer) {
+      return;
+    }
+
+    for (let i = 0; i < vectorTileLayer.length; i++) {
+      const vectorTileFeature = vectorTileLayer.feature(i, geometryInfo);
+      const decodedFeature = getDecodedFeatureBinary(vectorTileFeature, options, layerName);
+      features.push(decodedFeature);
+    }
+  });
+
+  return [features, geometryInfo];
 }
 
-/**
- * @param options
- * @returns options
- */
-function normalizeOptions(options: LoaderOptions | undefined) {
-  if (options) {
-    options = {
-      ...options,
-      mvt: options.mvt || {},
-      gis: options.gis || {}
-    };
-
-    // Validate
-    const wgs84Coordinates = options.coordinates === 'wgs84';
-    const {tileIndex} = options;
-    const hasTileIndex =
-      tileIndex &&
-      Number.isFinite(tileIndex.x) &&
-      Number.isFinite(tileIndex.y) &&
-      Number.isFinite(tileIndex.z);
-
-    if (wgs84Coordinates && !hasTileIndex) {
-      throw new Error(
-        'MVT Loader: WGS84 coordinates need tileIndex property. Check documentation.'
-      );
+function parseToGeojson(arrayBuffer: ArrayBuffer, options: MVTOptions): Feature[] {
+  if (arrayBuffer.byteLength <= 0) {
+    return [];
+  }
+
+  const features: MVTMapboxCoordinates[] = [];
+  const tile = new VectorTile(new Protobuf(arrayBuffer));
+
+  const selectedLayers = Array.isArray(options.layers) ? options.layers : Object.keys(tile.layers);
+
+  selectedLayers.forEach((layerName: string) => {
+    const vectorTileLayer = tile.layers[layerName];
+    if (!vectorTileLayer) {
+      return;
     }
+
+    for (let i = 0; i < vectorTileLayer.length; i++) {
+      const vectorTileFeature = vectorTileLayer.feature(i);
+      const decodedFeature = getDecodedFeature(vectorTileFeature, options, layerName);
+      features.push(decodedFeature);
+    }
+  });
+
+  return features as Feature[];
+}
+
+function normalizeOptions(options?: MVTLoaderOptions): MVTOptions {
+  if (!options?.mvt) {
+    throw new Error('mvt options required');
+  }
+
+  // Validate
+  const wgs84Coordinates = options.mvt?.coordinates === 'wgs84';
+  const {tileIndex} = options.mvt;
+  const hasTileIndex =
+    tileIndex &&
+    Number.isFinite(tileIndex.x) &&
+    Number.isFinite(tileIndex.y) &&
+    Number.isFinite(tileIndex.z);
+
+  if (wgs84Coordinates && !hasTileIndex) {
+    throw new Error('MVT Loader: WGS84 coordinates need tileIndex property');
   }
-  return options;
+
+  return options.mvt;
 }
 
 /**
@@ -114,15 +155,16 @@ function normalizeOptions(options: LoaderOptions | undefined) {
  */
 function getDecodedFeature(
   feature: VectorTileFeatureMapBox,
-  options: MvtOptions
-): MvtMapboxCoordinates {
+  options: MVTOptions,
+  layerName: string
+): MVTMapboxCoordinates {
   const decodedFeature = feature.toGeoJSON(
     options.coordinates === 'wgs84' ? options.tileIndex : transformToLocalCoordinates
   );
 
   // Add layer name to GeoJSON properties
   if (options.layerProperty) {
-    decodedFeature.properties[options.layerProperty] = options.layerName;
+    decodedFeature.properties[options.layerProperty] = layerName;
   }
 
   return decodedFeature;
@@ -135,7 +177,8 @@ function getDecodedFeature(
  */
 function getDecodedFeatureBinary(
   feature: VectorTileFeatureBinary,
-  options: MvtOptions
+  options: MVTOptions,
+  layerName: string
 ): FlatFeature {
   const decodedFeature = feature.toBinaryCoordinates(
     options.coordinates === 'wgs84' ? options.tileIndex : transformToLocalCoordinatesBinary
@@ -143,7 +186,7 @@ function getDecodedFeatureBinary(
 
   // Add layer name to GeoJSON properties
   if (options.layerProperty && decodedFeature.properties) {
-    decodedFeature.properties[options.layerProperty] = options.layerName;
+    decodedFeature.properties[options.layerProperty] = layerName;
   }
 
   return decodedFeature;

package/src/lib/types.ts

@@ -1,23 +1,69 @@
-export type MvtOptions = {
-  coordinates: string | number[];
+import type {LoaderOptions} from '@loaders.gl/loader-utils';
+
+/** For local coordinates, the tileIndex is not required */
+type MVTLocalCoordinatesOptions = {
+  /**
+   * When set to `local`, the parser will return a flat array of GeoJSON objects with local coordinates decoded from tile origin.
+   */
+  coordinates: 'local';
+  tileIndex: null;
+};
+
+/** In WGS84 coordinates, the tileIndex is required */
+type MVTWgs84CoordinatesOptions = {
+  /**
+   * When set to `wgs84`, the parser will return a flat array of GeoJSON objects with coordinates in longitude, latitude decoded from the provided tile index.
+   */
+  coordinates: 'wgs84';
+
+  /**
+   * Mandatory with `wgs84` coordinates option. An object containing tile index values (`x`, `y`,
+   * `z`) to reproject features' coordinates into WGS84.
+   */
   tileIndex: {x: number; y: number; z: number};
-  layerProperty: string | number;
-  layerName: string;
 };
 
-export type MvtMapboxGeometry = {
+export type MVTOptions = (MVTLocalCoordinatesOptions | MVTWgs84CoordinatesOptions) & {
+  /**
+   * When non-`null`, the layer name of each feature is added to
+   * `feature.properties[layerProperty]`. (A `feature.properties` object is created if the feature
+   * has no existing properties). If set to `null`, a layer name property will not be added.
+   */
+  layerProperty?: string | number;
+
+  /**
+   * Optional list of layer names. If not `null`, only features belonging to the named layers will
+   * be included in the output. If `null`, features from all layers are returned.
+   */
+  layers?: string[];
+  shape?: 'geojson-row-table' | 'columnar-table' | 'geojson' | 'binary' | 'binary-geometry';
+};
+
+export type MVTMapboxGeometry = {
   type?: string;
   id?: number;
   length: number;
   coordinates?: any[];
 };
 
-export type MvtMapboxCoordinates = {
+export type MVTMapboxCoordinates = {
   type: string;
   geometry: {
     type: string;
-    coordinates: MvtMapboxGeometry;
+    coordinates: MVTMapboxGeometry;
   };
   properties: {[x: string]: string | number | boolean | null};
   id?: number;
 };
+
+export type MVTLoaderOptions = LoaderOptions & {
+  mvt?: MVTOptions;
+  gis?: {
+    /**
+     * When set to `true`, the parser will output the data in binary format. This is equivalent to loading the data as GeoJSON and then applying [geojsonToBinary](https://loaders.gl/modules/gis/docs/api-reference/geojson-to-binary).
+     */
+    binary?: boolean;
+    /** @deprecated. Use options.mvt.shape */
+    format?: 'geojson-row-table' | 'columnar-table' | 'geojson' | 'binary' | 'binary-geometry';
+  };
+};

package/src/mvt-loader.ts

@@ -1,10 +1,21 @@
 import type {Loader, LoaderWithParser} from '@loaders.gl/loader-utils';
+import type {MVTLoaderOptions} from './lib/types';
 import parseMVT from './lib/parse-mvt';
 
 // __VERSION__ is injected by babel-plugin-version-inline
 // @ts-ignore TS2304: Cannot find name '__VERSION__'.
 const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
 
+const DEFAULT_MVT_LOADER_OPTIONS: MVTLoaderOptions = {
+  mvt: {
+    shape: 'geojson',
+    coordinates: 'local',
+    layerProperty: 'layerName',
+    layers: undefined,
+    tileIndex: null
+  }
+};
+
 /**
  * Worker loader for the Mapbox Vector Tile format
  */
@@ -22,14 +33,7 @@ export const MVTWorkerLoader: Loader = {
   ],
   worker: true,
   category: 'geometry',
-  options: {
-    mvt: {
-      coordinates: 'local',
-      layerProperty: 'layerName',
-      layers: null,
-      tileIndex: null
-    }
-  }
+  options: DEFAULT_MVT_LOADER_OPTIONS
 };
 
 /**
@@ -37,7 +41,7 @@ export const MVTWorkerLoader: Loader = {
  */
 export const MVTLoader: LoaderWithParser = {
   ...MVTWorkerLoader,
-  parse: async (arrayBuffer, options) => parseMVT(arrayBuffer, options),
+  parse: async (arrayBuffer, options?: MVTLoaderOptions) => parseMVT(arrayBuffer, options),
   parseSync: parseMVT,
   binary: true
 };