Mapbox Vector Tile (MVT) and MVT Tileset Reader/Writer

FME can read Mapbox Vector Tile (MVT) tiles, and read and write MVT tilesets. FME can read from a web address, a local file, or a local folder; and can write to a local folder.

Tiles are spatially related collections of vector features that can be stored on one or more layers. Tiles can also be stored in groups called tilesets that contain tiles at the same zoom level. The tiles are contained within .mvt files or compressed .mvt.gz files.

Layers are used to semantically group different vector features, and they can span multiple tiles (for example, rivers, roads, or vector features within a city).

Mapbox Vector Tile (MVT) Product and System Requirements

Format	FME Platform			Operating System
Reader/Writer	FME Form	FME Flow	FME Flow Hosted	Windows 64-bit	Linux	Mac
Reader	Yes	Yes	Yes	Yes	Yes	Yes

Mapbox Vector Tile (MVT) Tileset Product and System Requirements

Format	FME Platform			Operating System
Reader/Writer	FME Form	FME Flow	FME Flow Hosted	Windows 64-bit	Linux	Mac
Reader	Yes	Yes	Yes	Yes	Yes	Yes
Writer	Yes	Yes	Yes	Yes	Yes	Yes

How FME Works with MVT Data

To access vector data, it helps to subdivide the data into smaller tiles according to a well-known tiling scheme, and store each tile. MapBox has created the MVT tile schema to store tiles and tilesets at different zoom levels and access them on either a server or local host. These tiles are stored in efficient protocol buffer files, vector tiles files, or compressed vector tiles files. See GDAL Documentation – MVT for more information on MVT file structure.

FME can read and analyze individual tiles or tilesets, filter them, organize them, and then output the results into a new tileset, or any other vector format. FME can also integrate vector feature data from other formats (for example, GIS, CAD, or any other vector data) into a new or existing tileset.

Are OpenStreetMap PBF files related to Mapbox Vector Tiles?

They are not related. PBFs are a format – much like XML – and can take many forms. Mapbox Vector Tiles and OpenStreetMap PBFs are protobuf files, but they conform to different specifications and protobuf schemas, and they are used in different ways. FME does not use this extension, but other MVT providers might.

Terminology in this Section

Definition or FME Representation	MVT and MVT Tileset Equivalent
reader dataset	tile
reader or writer dataset	tileset
feature type	layer
attribute	field/attribute
feature	feature

Reader Overview

The MVT reader supports reading multiple one or more vector tiles from a URL or local file system. Each tile may contain any number of vector features of any supported geometry type, which then become features in FME.

The vector features are classified into different layers whose names and attributes become feature type names and attributes in FME. Layers can be defined in an optional metadata.json file at the root of a tileset which is read automatically when tiles are configured in a tile scheme.

Choosing an MVT Reader

Two readers exist for different types of MVT datasets: Mapbox Vector Tile (MVT), and Mapbox Vector Tile (MVT) Tileset. The features of each reader are described in the table below.

Mapbox Vector Tile (MVT)

Reads single files from the local file system. The reader can also accept URLs and read single files or entire tilesets when the URL only specifies a zoom level. For example, https://b.tiles.mapbox.com/v4/<mapID>/15 will read all the tiles in the specified map at zoom level 15.

Select the reader Mapbox Vector Tile (MVT) when the dataset is a file or URL:

File with the extensions .mvt or .mvt.gz.
URL address to a tile or a tileset (for example, http[s]://path/to/some.mvt for a single tile and http[s]://path/to/{Z} for a tileset, where Z is the desired zoom level).

Mapbox Vector Tile (MVT) Tileset

Reads tilesets that are in the specified directory zoom level. The directory hierarchy for a tileset must conform to the structure specified in the format usage notes – otherwise, the metadata may not be read correctly.

Select the reader Mapbox Vector Tile (MVT) Tileset to read a local folder.

Each layer in the vector tile corresponds with its own feature type. A tile may have multiple layers and therefore multiple feature types.

Dataset

The dataset can be an MVT file with extension .mvt or .mvt.gz, or it can be a URL address to a tile or a tileset (for example, http[s]://path/to/some.mvt for a single tile and http[s]://path/to/{Z} for a tileset, where Z is the desired zoom level).

See Usage Notes for further information.

MVT Tileset Writer Overview

The MVT writer generates tiles in the WebMercator (EPSG:3857) projection by default.

The writer accepts input vector features from various layers and tiles them up into a base zoom level. Subsequent lower-resolution zoom levels may also be generated from the base zoom level. Each zoom level is a unique tileset that can be read together, or as individual tiles. Several semantic layers of vector features may be written to each file and zoom level.

Dataset

The dataset is an output folder into which the writer will create one tileset per applicable zoom level requested in the new folder.

Note If Overwrite Folder is set to Yes, the output folder is deleted and recreated to prevent incorrect tileset creation when reusing the existing folder. This means existing data in the folder will be deleted. (If Overwrite Folder is set to No, the writer will return an error if the dataset is a non-empty folder.)

These folders correspond to the MVT tile directory specification, <output_directory>/{Z}/{X}/{Y}.<tile_extension>, where {Z} is a zoom level between 0 and 22, and {X} and {Y} are the tile indexes within the tile specification.

Example
The MVT writer receives input vector data for countries of the world, and has the following parameters: an output dataset of c:/output, min and max zoom levels of 0 and 0, and a tile extension of .mvt. We would expect the following output folder and files: c:/output/0/0/0.mvt c:/output/0/0/1.mvt c:/output/0/0/2.mvt c:/output/0/0/3.mvt c:/output/0/1/0.mvt c:/output/0/1/1.mvt c:/output/0/1/2.mvt c:/output/0/1/3.mvt

Example

The MVT writer receives input vector data for countries of the world, and has the following parameters:

an output dataset of c:/output,
min and max zoom levels of 0 and 0, and
a tile extension of .mvt.

We would expect the following output folder and files:

c:/output/0/0/0.mvt

c:/output/0/0/1.mvt

c:/output/0/0/2.mvt

c:/output/0/0/3.mvt

c:/output/0/1/0.mvt

c:/output/0/1/1.mvt

c:/output/0/1/2.mvt

c:/output/0/1/3.mvt

See Usage Notes for further information.

To read a tileset in a local folder, please use the Mapbox Vector Tile (MVT) Tileset reader, which accepts folders as datasets.

Note While the MVT Tileset writer creates multiple tilesets, the MVT Tileset reader typically only reads one at a time.

Usage Notes

FME supports reading MapBox Vector Tiles specification version 1.x and 2.x, and writing version 2.1.
The MVT reader uses three integer coordinates, where z is the zoom level and (x,y) is the coordinate of the tile in the zoom level.
The MVT writer uses the json key from the metadata.json file to populate feature type names, attribute names and types, and the geometry type. The bounds key is also used for the feature type extents. All other contents of the metadata.json file are unused. If a metadata.json file cannot be found, the feature type schema is established by scanning the features of the tile(s).
If a metadata.json file cannot be found, the feature type schema is established by scanning the features of the tile(s).
Each layer in the vector tile corresponds to its own feature type. A Tile may have multiple layers, and therefore multiple feature types.