Content

TomTom Vector Format

TomTom Vector tiles contain map features (points, lines, road shapes, water polygons, building footprints, etc.) that can be used to visualize map data. The data is divided into multiple protobuf layers. Besides the layers, the protobuf tags are also used to further describe the geographic features.

Legend

Tile

Represents a vector tile as a whole entity. It consists of at least one TileLayer.
If the tile does not contain any relevant data, it contains one layer named empty.

TileLayer

Part of a Tile , representing one of the layers that can be rendered later. One layer consists of e.g., all Parks, Roads, Build up areas, or Points of interest.

Each TileLayer contains geometries of the same type. A geometry in the vector tile can be one of three types: POINT , LINESTRING , or POLYGON. Every TileLayer contains the following fields:

• name

• version

• extent

It may also contain the following fields:

• keys are an array of unique strings.

• values are an array of unique TileValues.

• features are an array of unique TileFeatures.

Arrays of keys and values contain the mapping for tags of TileFeature.

TileFeature

Member of an array of features stored in a TileLayer , containing a geometry representation that can be rendered.

It always contains the following fields:

• type is a type of geometry. It can be point , linestring , or polygon.

• geometry is an array of encoded geometry that can be used for rendering. See the Decoding tile geometry section for details.

It may also contain the following fields:

• tags is an array containing properties of feature.

  • They are a TileFeature's detailed description which can be used for styling and later rendering the geometry.

  • They are encoded into an array of integers.

  • In order to decode them, the arrays of keys and values from a corresponding TileLayer must be used.

  • See the Decoding feature tags section for details.

TileValue

Encoded representation of a string, integer, floating point, or boolean value.

• It is stored in a values array, in a TileLayer.

• It is used for decoding tags of a TileFeature (together with the members of a keys array).

• See the Decoding feature tags section for details.

TomTom Vector Schema

Schema data

Formally, the structure of vector tile is described by the protocol buffer schema. It allows the generation of C++, Java, Python, Go, Ruby, Objective-C, and C# code based on proto file.

1package vector_tile
2
3option optimize_for = LITE_RUNTIME;
4
5message Tile {
6
7    enum GeomType {
8        UNKNOWN = 0;
9        POINT = 1;
10        LINESTRING = 2;
11        POLYGON = 3;
12    }
13
14    message Value {
15        optional string string_value = 1;
16        optional float float_value = 2;
17        optional double double_value = 3;
18        optional int64 int_value = 4;
19        optional uint64 uint_value = 5;
20        optional sint64 sint_value = 6;
21        optional bool bool_value = 7;
22        extensions 8 to max;
23    }
24
25    message Feature {
26        optional uint64 id = 1 [ default = 0 ];
27        repeated uint32 tags = 2 [ packed = true ];
28        optional GeomType type = 3 [ default = UNKNOWN ];
29        repeated uint32 geometry = 4 [ packed = true ];
30        optional bytes raster = 5;
31    }
32
33    message Layer {
34        required uint32 version = 15 [ default = 1 ];
35        required string name = 1;
36        repeated Feature features = 2;
37        repeated string keys = 3;
38        repeated Value values = 4;
39        optional uint32 extent = 5 [ default = 4096 ];
40
41        extensions 16 to max;
42    }
43
44    repeated Layer layers = 3;
45
46    extensions 16 to 8191;
47}

Decoding tile geometry

Vector Tile geometry uses the following coordinate system:

• Coordinates are always integers.
• The (0,0) point is located in the upper-left corner of the tile.
• The X axis has values increasing towards the right of the tile.
• The Y axis has values increasing towards the bottom of the tile.
• The tile may have margin, which is a buffer around the tile in the shape of a square frame. The size of the margin is by default equal to 10% of the width/length of the tile.
• The extent is equal to 4096, so the value range for X and Y coordinates is from 0 to 4095 for visible points.
• If the tile has a margin, the coordinates values range is extended by its size in both directions. This may cause coordinate values for points in the left or upper margin to be negative.

Vector Tile geometry is encoded as an array of 32 bit unsigned integers in the geometry field of the TileFeature.

Encoded format has the following structure:

[command_and_count][x0][y0]..[xn][yn][command_and_count][x0][y0]..

• command_and_count contains encoded values of command and count.
• [x0][y0]..[xn][yn] are (x,y) coordinate pairs.

Command

The value of command is decoded as follows:

command = command_and_count & 0x7

Commands are to be executed relative to previous path coordinates or the point (0,0) if it is the first command.

Count

The value of count is decoded as follows: count = command_and_count >> 0x3

• It defines the n number of [xn][yn] encoded coordinate pairs following the command_and_count value.
• These coordinate pairs must be interpreted according to the preceding command type.

Coordinates

Coordinates [x0][y0]..[xn][yn] are encoded in zigzag encoding and are relative to the previous coordinate pair. This means that only the first coordinate pair [x0][y0] in the first command in every TileFeature stores absolute values.

The coordinates are decoded as follows:

1decode(x0) = ((x0 >> 0x1) ^ (-(x0 & 0x1)))
2decode(y0) = ((y0 >> 0x1) ^ (-(y0 & 0x1)))
3
4decode(x1) = decode(x0) + ((x1 >> 0x1) ^ (-(x1 & 0x1)))
5decode(y1) = decode(y0) + ((y1 >> 0x1) ^ (-(y1 & 0x1)))
6
7...
8
9decode(xn) = decode(xn-1) + ((xn >> 0x1) ^ (-(xn & 0x1)))
10decode(yn) = decode(yn-1) + ((yn >> 0x1) ^ (-(yn & 0x1)))

Examples

For a POINT type feature

1layer: 0
2    feature: 0
3        type: POINT
4        geometry: [9, 1136, 6564]

1geometry:
2    command_and_count = 9
3    command = 9 & 0x7 = 1
4    count = 9 >> 0x3 = 1
5
6    x0 = 1136, y0 = 6564
7    decode(x0) = ((1136 >> 0x1) ^ (-(1136 & 0x1))) = 568
8    decode(y0) = ((6564 >> 0x1) ^ (-(6564 & 0x1))) = 3282

1layer: 0
2    feature: 0
3    geometry: POINT(561, 3282)

For a LINESTRING type feature

1layer: 0
2    feature: 0
3        type: LINESTRING
4        geometry: [9, 846, 2312, 10, 652, 1938]

1geometry:
2    1:
3        command_and_count = 9
4        command = 9 & 0x7 = 1
5        count = 9 >> 0x3 = 1
6
7        x0 = 846, y0 = 2312
8        decode(x0) = ((846 >> 0x1) ^ (-(846 & 0x1))) = 423
9        decode(y0) = ((2312 >> 0x1) ^ (-(2312 & 0x1))) = 1156
10    2:
11        command_and_count = 10
12        command = 10 & 0x7 = 2
13        count = 10 >> 0x3 = 1
14
15        x0 = 652, y0 = 1938
16        decode(x0) = decode(1:x0) + ((652 >> 0x1) ^ (-(652 & 0x1))) = 423 + 326 = 749
17        decode(y0) = decode(1:y0) + ((1938 >> 0x1) ^ (-(1938 & 0x1))) = 1156 + 969 = 2125

1layer: 0
2    feature: 0
3    geometry: LINESTRING[(423, 1156), (749, 2125)]

For a POLYGON type feature

1layer: 0
2    feature: 0
3        type: POLYGON
4        geometry: [9, 1320, 5622, 26, 416, 707, 68, 612, 483, 96, 7]

1geometry:
2    1:
3        command_and_count = 9
4        command = 9 & 0x7 = 1
5        count = 9 >> 0x3 = 1
6
7        x0 = 1320, y0 = 5622
8        decode(x0) = ((1320 >> 0x1) ^ (-(1320 & 0x1))) = 660
9        decode(y0) = ((5622 >> 0x1) ^ (-(5622 & 0x1))) = 2811
10    2:
11        command_and_count = 26
12        command = 26 & 0x7 = 2
13        count = 26 >> 0x3 = 3
14
15        x0 = 1736, y0 = 4914
16        decode(x0) = decode(1:x0) + ((416 >> 0x1) ^ (-(416 & 0x1))) = 660 + 208 = 868
17        decode(y0) = decode(1:y0) + ((707 >> 0x1) ^ (-(707 & 0x1))) = 2811 + (-354) = 2457
18
19        x1 = 68, y1 = 612
20        decode(x1) = decode(x0) + ((68 >> 0x1) ^ (-(68 & 0x1))) = 902
21        decode(y1) = decode(y0) + ((612 >> 0x1) ^ (-(612 & 0x1))) = 2763
22
23        x2 = 483, y2 = 96
24        decode(x2) = decode(x1) + ((483 >> 0x1) ^ (-(483 & 0x1))) = 660
25        decode(y2) = decode(y1) + ((96 >> 0x1) ^ (-(96 & 0x1))) = 2811
26    3:
27        command_and_count = 7
28        command = 7 & 0x7 = 7
29        count = 7 >> 0x3 = 0

1layer: 0
2    feature: 0
3    geometry: POLYGON[(660, 2811), (868, 2457), (902, 2763), (660, 2811)]

Decoding feature tags

In order to reduce tile size, the properties of each feature are encoded in a tags array. The tags array contains integer values which are indexes of keys and values arrays belonging to the corresponding layer. The size of a tags array is always even.

The content of a tags array can be grouped into a list of pairs. Each odd element of an array is the first element of a pair, and each even element of an array is the second element of a pair.

• The first element of each pair should be mapped to a keys array.
• The second element of each pair should be mapped to a values array.

As a result, we get a decoded list of tags where the first element is the tag name and the second element is the tag value in the form of TileValue.

Example

Below is an example of what an encoded tile may look like.

1layer: 0
2    keys: ["country_code", "icon_text"],
3    values: ["SWE", "E4"]
4    feature: 0
5        tags : [0,0,1,1]

After decoding it has to be read like this:

1layer: 0
2    feature: 0
3        properties:
4            country_code : "SWE"
5            icon_text : "E4"

Tile Layers

The data in TomTom Vector Tiles is organized in layers that can be arranged into groups, consisting of layers that describe similar map features. The following section provides detailed information about:

• All groups.
• Layers that are contained in each group.
• Tags that typically appear in features from a given group.

Landuse

The landuse layers include polygons that represent land use and land cover.

• Group name: landuse
• Geometry type: polygon

Landuse layers

This layer group does not use any additional tags.

Earth Cover

The Earth Cover layers include polygons that represent the dominant physical cover of the earth's surface from a top-down perspective.

• Group name: earth_cover
• Geometry type: polygon

Earth Cover layer

Earth Cover tags

Water

The water layers include polygons that represent water bodies like ocean, seas, rivers, lakes, and other water bodies.

• Group name: water
• Geometry type: polygon

This layer group does not use any additional tags.

Buildings

The building layers represent footprints of buildings.

• Group name: buildings
• Geometry type: polygon

Places

The places layers includes points that can be used for labeling places like countries, states, cities, towns, and villages.

• Group name: places
• Geometry type: point

POI

The POI group consists of layers that represent points of interest. Depending on the type of tile layer in a request, (see Tiles Layers and Styles different layers will be present in the protobuf tile.

• Group name: poi
• Geometry type: point

Point of Interest Categories: basic, hybrid, and labels vector tiles

The Category ID and Subcategory ID in the following table correspond to the ID in poiCategories in the Search API.

Point of Interest Categories: poi vector tiles

The Category ID and Subcategory ID in the following table correspond to the ID in poiCategories in the Search API.

Cartolabels

The cartolabels layers include points that represent cartographic labels. Please note that most of the layers in this group are being replaced by Points of Interest with equivalent categories.

• Group name: cartolabels
• Geometry type: point

Roads

The roads layers include lines that can be used for drawing roads.

• Group name: cartolabels
• Geometry type: line

Each road may have one or more road shields. The shields are indexed from 0, and described by sets of tags.

Shield icon shape types

Shield icon fill and stroke colors

Shield icon countries and states

Possible values of the countryName part of a name are listed in the following table.

• For Canada shields, the stateCode part of the shield's name is either a two-letter province name abbreviation or empty.
• For USA shields, the stateCode may be a two-letter ISO-3166 state name abbreviation, highway, county, or empty.
• For other country shields the stateCode is empty.

Transit

The transit layers include lines that can be used to draw transit lines.

• Group name: transit
• Geometry type: line

This layer group does not use any additional tags.

Boundaries

The boundaries layers include lines that can be used to draw different types of boundaries.

• Group name: boundaries
• Geometry type: line

This layer group does not use any additional tags.