MVT: Mapbox Vector Tiles

Starting with GDAL 2.3, the MVT driver can read and write Mapbox Vector Tile files, as standalone files, uncompressed or gzip-compressed (typical extensions are .pbf, .mvt, .mvt.gz), or a tileset at a given zoom level of such files. Write support requires GDAL to be built with libsqlite3 and GEOS support.

Mapbox Vector Tiles stored within a SQLite container conforming to the MBTiles format are handled by the MBTiles driver.

Tilesets of MVT files can for example be generated by tippecanoe or tileserver-gl. The output file hierarchy will contain a metadata.json file at its root and {z}/{x}/{y}.pbf files with the tiles, where z is the zoom level and (x, y) the coordinate of the tile in a given zoom level. The origin of the tiling system is the top-left tile(XYZ convention). For example, for zoom levels 0 and 1 :

/metadata.json
/0/
   0/
     0.pbf
/1/
   0/
     0.pbf
     1.pbf
   1/
     0.pbf
     1.pbf

The driver will assume by default EPSG:3857 (WebMercator) spatial reference system and Z/X/Y tiling structure, if opening a filename with {Z}/{X}/{Y}.pbf or {Z}-{X}-{Y}.pbf name, or a zoom level of a tileset. Otherwise integer coordinates will be reported.

Note: When opening a zoom level of a tileset, the driver will make no effort of stiching together geometries for features that overlap several tiles.

Connection strings

The following connection strings are supported:

The MVT: prefix may be added before the filename or directory name to help forcing identification of datasets in some rare cases where non-guided identification would fail.

metadata.json

This file is typically generated by tippecanoe and has the following content:

{
    "name": "my_layername",
    "description": "my_layername",
    "version": "2",
    "minzoom": "0",
    "maxzoom": "0",
    "center": "2.500000,49.500000,0",
    "bounds": "2.000000,49.000000,3.000000,50.000000",
    "type": "overlay",
    "format": "pbf",
    "json": "{
        \"vector_layers\": [ {
            \"id\": \"my_layername\",
            \"description\": \"\",
            \"minzoom\": 0,
            \"maxzoom\": 0,
            \"fields\": {
                \"bool_false\": \"Boolean\",
                \"bool_true\": \"Boolean\",
                \"float_value\": \"Number\",
                \"pos_int_value\": \"Number\",
                \"pos_int64_value\": \"Number\",
                \"neg_int_value\": \"Number\",
                \"neg_int64_value\": \"Number\",
                \"pos_sint_value\": \"Number\",
                \"pos_sint64_value\": \"Number\",
                \"neg_sint_value\": \"Number\",
                \"neg_sint64_value\": \"Number\",
                \"real_value\": \"Number\",
                \"string_value\": \"String\",
                \"uint_value\": \"Number\",
                \"uint64_value\": \"Number\"
            }
        } ],
        \"tilestats\": {
            \"layerCount\": 1,
            \"layers\": [
                {
                \"layer\": \"my_layername\",
                \"count\": 2,
                \"geometry\": \"Point\",
                \"attributeCount\": 0,
                \"attributes\": []
                }
            ]
        }
    }}"
}

The MVT driver only uses the "json" key to retrieve the layer names, their fields and the geometry type, and the "bounds" key for the layer extent.

If this file cannot be found, the layer schema is established by scanning the features of the tile(s).

As an extension, OGR handles in reading and writing custom tiling schemes by using the crs, tile_origin_upper_left_x, tile_origin_upper_left_y and tile_dimension_zoom_0 metadata items. For example, for the Finnish ETRS-TM35FIN (EPSG:3067) tiling scheme:

{
 ...
  "crs":"EPSG:3067",
  "tile_origin_upper_left_x":-548576.0,
  "tile_origin_upper_left_y":8388608.0,
  "tile_dimension_zoom_0":2097152.0,
}

Opening options

The following open options are available:

Creation issues

Tiles are generated with WebMercator (EPSG:3857) projection by default ( custom tiling schemes can be defined with the TILING_SCHEME option). Several layers can be written. It is possible to decide at which zoom level ranges a given layer is written.

Part of the conversion is multi-threaded by default, using as many threads as they are cores. The number of threads used can be controlled with the GDAL_NUM_THREADS configuration option.

Dataset creation options

Layer configuration

The above mentionned CONF dataset creation option can be set to a string whose value is a JSon serialized document such as the below one:

        {
            "boundaries_lod0": {
                "target_name": "boundaries",
                "description": "Country boundaries",
                "minzoom": 0,
                "maxzoom": 2
            },
            "boundaries_lod1": {
                "target_name": "boundaries",
                "minzoom": 3,
                "maxzoom": 5
            }
        }

boundaries_lod0 and boundaries_lod1 are the name of the OGR layers that are created into the target MVT dataset. They are mapped to the MVT target layer boundaries.

It is also possible to get the same behaviour with the below layer creation options, although that is not convenient in the ogr2ogr use case.

Layer creation options

Examples

ogrinfo MVT:https://free.tilehosting.com/data/v3/1 -oo tile_extension="pbf.pict?key=${YOUR_KEY}" --debug on -oo metadata_file="https://free.tilehosting.com/data/v3.json?key=${YOUR_KEY}"
ogr2ogr -f MVT mytileset source.gpkg -dsco MAXZOOM=10

See Also: