Custom style

You can change the appearance of the map by providing a JSON file (style) defining the sources of data to be shown on the map and its appearance. A style has to:

Include all mandatory layer sets (see Table 1).
Contain Maps SDK-specific tags.
More information about TomTom styles is available in the Map Styles Specification.

A basic style is provided as a part of the http[Custom Style Resources] package.

Styles compliant with the Map Styles Specification can be edited using Map Styler. Before a style can be edited in Map Styler:

Service key placeholders have to be replaced with actual service keys.
All service keys included in the style must be valid for the Map Display API product.
Sprite and glyph locations have to be replaced by ones that can be reached by Map Styler. If service key is needed to access these resources, it must be included.
Maps SDK-specific tags have to be removed from tile source links or replaced with default values.
(Optional) Visibility of layers can be altered to your preferences.

All these changes, with the exception of layer visibility, have to be reverted before the modified style can be used with the SDK. Custom Style Resources contain a Python script - convertStyle.py - which simplifies this process. Detailed usage instructions can be found in the following dedicated section.

Layer sets

The SDK uses the concept of a layer set to refer to a group of layers. A layer set consists of all layers using the same source. Layer sets listed in Table 1 are required for the SDK to function. If any of these layer sets are absent or do not meet the requirements mentioned below, they will be replaced with default layer sets created at runtime.

Map view element	Default source name	Required layer type	Required layer count	Source type
Route polyline	tomtom-active-route	line	2	GeoJSON
Route start icon	tomtom-start-route	symbol	1	GeoJSON
Route end icon	tomtom-end-route	symbol	1	GeoJSON
GPS inaccuracy radius	tomtom-gpsradius	circle	1	GeoJSON
Position indicator	tomtom-position	symbol	1	GeoJSON
Vehicle icon	tomtom-chevron	symbol	1	GeoJSON

Two layers for route polyline define the outline and fill styles. Two layers for chevron, GPS radius and position define the styles of two versions of associated objects - normal (active) and dimmed ( inactive).

There is a number of layer sets that are important, but not strictly required. They are responsible for providing style and data sources for maps - vector and raster, traffic flow and incidents as well as hybrid overlay. These sets will not be replaced by default ones at runtime.

Source URIs for map layer sets have a fixed format - they contain placeholders for API keys and optional parameters. It is not recommended to change them.

Raster tile size

The SDK offers 256x256 px and 512x512 px raster tiles. By default, the larger tiles are used. The size of tiles can be modified by setting the tileSize parameter in the url of raster sources to either 256 or 512.

Style API

When your custom style is ready, you can use it in your application in a number of ways:

Provide the URI to a location accessible by your application in setStylePath(…).
Replace the default style:
- Create a data/style directory in your project’s root.
- Rename your file to style.json and place it in data/style.
- Copy glyph and sprite folders from framework to data/style.

Sample use case: You want to display a night-themed map at night or while in a tunnel.

Even though online style locations are supported, glyphs and sprites have to be stored locally.

Basic style

Night custom style

Using convertStyle.py

The convertStyle.py script is distributed as a part of the http[Custom Style Resources] bundle. It can be executed with one of two commands: 'mapstyler' and 'mapssdk'. When executed with the ' mapstyler' command, it replaces Maps SDK-specific elements of the base style (-b|--base parameter) with values provided in script’s parameters or in Info.plist or AndroiManifest.xml. When executed with the 'mapssdk' command, it reverts changes related to Maps SDK-specific elements while leaving user’s modification intact. Because of Map Styler requirement, API key contained in field " OnlineTraffic.key" of Info.plist or AndroidManifest.xml must be valid also for Map Display API product.

For the script to work properly, the same base file has to be used for both conversions.

1python2 convertStyle.py <common parameters> <command=mapstyler|mapssdk> <command-specific parameters>
2
3# All parameters are required unless specified otherwise
4
5common parameters:
6  -w WDIR, --wdir WDIR  Working directory. Root of relative paths.
7                        [optional, default = "."]
8  -S, --silent          Silent mode. No messages will be printed.
9  -b BASE, --base BASE  Path to the base for the new style.
10  -o OUTPUT, --output OUTPUT
11                        Path to the output file.
12
13commands:
14    mapstyler           Convert a base style so that it can be edited in
15                        Map Styler.
16    mapssdk             Convert a style edited in Map Styler so that it works
17                        with your application using Maps SDK.
18
19mapstyler parameters:
20  -k KEYS, --keys KEYS  Path to Info.plist or AndroiManifest.xml.
21  -s SPRITES, --sprites SPRITES
22                        Online location of sprites.
23  -g GLYPHS, --glyphs GLYPHS
24                        Online location of glyphs.
25  -v {all,none,intact,predefined}, --visibility {all,none,intact,predefined}
26                        Change visibility of layers. 'intact' leaves the base
27                        style's settings intact, 'predefined' makes vector
28                        layers visible and all other layers invisible.
29                        [optional, default = "predefined"]
30
31mapssdk parameters:
32  -e EDITED, --edited EDITED
33                        Path to the style edited in Map Styler.

Sample workflow

Upload glyphs and sprites to an online location accessible by Map Styler.
Use convertStyle.py to create a style that can be edited in Map Styler.
```
python2 convertStyle.py -b mapssdk-default-style.json -o my_style_prepared_for_mapstyler.json mapstyler -k path/to/app/AndroiManifest.xml -g http://link.to.glyphs.com -s http://link.to.sprites.com
```
Upload my_style_prepared_for_mapstyler.json to Map Styler.
Edit the style in Map Styler.
Export the style in Map Styler, saving it as my_style_exported_from_mapstyler.json.
Use convertStyle.py to prepare the style edited in Map Styler to for use with Maps SDK.
```
python2 convertStyle.py -b mapssdk-default-style.json -o my_style_prepared_for_sdk.json mapssdk -e my_style_exported_from_mapstyler.json
```