Skip to main content

MVTLoader

Loader for the Mapbox Vector Tile format for representation of geometry.

LoaderCharacteristic
File Extension.mvt,
File TypeBinary
File FormatMapbox Vector Tile
Data FormatGeometry
Supported APIsload, parse, parseSync

Usage

import {MVTLoader} from '@loaders.gl/mvt';
import {load} from '@loaders.gl/core';

// GeoJSON objects containing local coordinates decoded from tile origin to a range of [0 - (bufferSize / tileExtent), 1 + (bufferSize / tileExtent)]
const geometryData = await load(url, MVTLoader);

// Array containing GeoJSON Features
const loaderOptions = {
mvt: {
coordinates: 'wgs84',
tileIndex: {
x: 0,
y: 0,
z: 0
}
}
};

const geoJSONfeatures = await load(url, MVTLoader, loaderOptions);

Outputs

GeoJSON

The parser will return an array of GeoJSON objects with WGS84 coordinates and feature properties from MVT if coordinates property is set to wgs84 and tileIndex properties are present.

import {MVTLoader} from '@loaders.gl/mvt';
import {load} from '@loaders.gl/core';

const geoJSONfeatures = await load(url, MVTLoader, {
mvt: {
coordinates: 'wgs84',
tileIndex: {
x: xTileIndex,
y: yTileIndex,
z: zTileIndex
}
}
});

GeoJSON with local coordinates

The parser will return an array of GeoJSON objects with local coordinates in a range from 0 to 1 and feature properties from MVT by default.

Even though tile coordinates go from 0 to 1, there can be some negative (or greater than one) coordinates because of buffer cells within MVT to handle geometry clipping. That difference can be as much as bufferSize / tileExtent depending on MVT creation parameters.

Note that local coordinates are relative to tile origin, which is in the top left.

import {MVTLoader} from '@loaders.gl/mvt';
import {load} from '@loaders.gl/core';

const geoJSONfeatures = await load(url, MVTLoader);

/*
* Default loader options are:
*
* {
* mvt: {
* coordinates: 'local'
* }
* }
*/

Options

OptionTypeDefaultDescription
mvt.shape`'geojson'binarygeojson: returns GeoJSON objects. binary: returns binary data.
mvt.coordinates`'local'localwgs84: returns coordinates in longitude, latitude using the provided tile index. local returns local 0-1 coordinates relative to the tile origin.
mvt.tileIndex{x: number, y: number, z: number}N/AWhen the wgs84 coordinates option, the index of the tile being loaded (x, y, z) must be supplied.
mvt.layerPropertystring | null'layerName'When non-null, the layer name of each feature is added to feature.properties[layerProperty]. If null, a layer name property will not be added.
mvt.layersstring[]N/AIf provided, only features belonging to the named layers will be included, otherwise features from all layers are returned.

If you want to know more about how geometries are encoded into MVT tiles, please read this documentation section.

Attribution

The MVTLoader is a fork of @mapbox/vector-tile module under the BSD-3-Clause.