Customising The Map Look

1 Overview
2 Getting started
3 Map style folder structure
4 Setting up a test environment
5 Explaining a map color scheme
- 5.1 Screen object
- 5.2 Scheme object
- 5.3 FontFile object
- 5.4 ZoomTableFile object
- 5.5 ColorFile object
  - 5.5.1 High-Dpi, Car, Day color scheme
6 Creating an inherited map colour scheme
- 6.1 Inherited color scheme
7 Customising map colour schemes
- 7.1 Fonts
  - 7.1.1 System Font Aliases (iOS.col)
  - 7.1.2 System Font Aliases (Android.col)
  - 7.1.3 Styling font aliases (Default.col)
- 7.2 Road styling
- 7.3 Waterways, Railways, Ferry routes styling
  - 7.3.1 Water way styling
- 7.4 Border Line styling
  - 7.4.1 Border Line Styling
- 7.5 Bridges and Tunnels styling
  - 7.5.1 Tunnel/Bridge styling example
- 7.6 Ramp and Roundabout styling
  - 7.6.1 RAMP/ROUNDABOUT styling example
- 7.7 Map background styling
  - 7.7.1 LAND styling example
  - 7.7.2 COLOR variables
- 7.8 Areas (Polygons)
  - 7.8.1 AREAS styling example
- 7.9 Direction Arrow
  - 7.9.1 Route Line styling example
- 7.10 Route Line
  - 7.10.1 Route Line styling example
  - 7.10.2 Route Line styling example
- 7.11 Defining various image variables
  - 7.11.1 IMAGE variables
- 7.12 Traffic congestion
  - 7.12.1 Route Line styling example
- 7.13 House numbers rendering
  - 7.13.1 House numbers styling example
- 7.14 Place name labels
  - 7.14.1 City labels styling example
8 Creating a style override
- 8.1 Option 1: Overriding using a text color file (.col)
  - 8.1.1 Resources.json
  - 8.1.2 Default-GBR.col
- 8.2 Option 2: Overriding road style, house numbers and images using a json color file (.json)
  - 8.2.1 Resources.json
  - 8.2.2 Walking.json
  - 8.2.3 Walking-GBR.json
  - 8.2.4 Supported attributes

Overview

Pathway Pro navigation engine (powering both Navmii Applications and Pathway Pro Mobile SDKs) provides a highly customisable map renderer configured by map colour schemes. It is possible to create colour schemes (for example, for day and night driving, pedestrian mode etc.) and switch them dynamically at a runtime.

Each colour scheme allows to customise:

road colours
road widths and road outline
road presence at a particular zoom level
road font style (including font outline)
route number look
city labels font style (per city class)
map background colour
polygon fill colour
water area style
polygons font style
maximum zoom level for house numbers
traffic colour and texture
GPS position cursor image
skybox background image
border line style
ferry route style
tunnels style
bridges style
direction arrow style and colour
various graphic textures (e.g. finish flag)

Most of the items above can be customised per country. E.g. road color may be different for UK and France in the same application.

Map colour schemes are stored in a style set folder and described by a ResourcesSdk2.json file which shall reside in the root of the folder containing the style set.

Getting started

If you're working on the map colour schemes in the Pathway Pro SDK repository, follow this link for further information.

If you're creating a custom map colour scheme as a user of the Pathway Pro SDK, proceed to the next chapter.

Map style folder structure

If you're working on the map colour schemes in the Pathway Pro SDK repository, follow this link for further information.

Map folder structure is flexible: none of the files, except ResourcesSdk2.json are required. Folder structure and file names are defined in ResourcesSdk2.json.

The most primitive SDK core scheme will consist of:

at least one Fonts.col file for font aliases
at least one MyMap.col file for Roads and polygons styling
one MyCities.col file for City/Towns labels
one RouteNumbers.col file for route numbers
two zoom table files for 2D and 3D

The most primitive color scheme you will create may consist of:

one MyStyle.json (or MyStyle.col) override file
other required files will be inherited from the core SDK scheme

Setting up a test environment

If you're working on the map colour schemes in the Pathway Pro SDK repository, follow this link for information on how to set up the test environment.

If you're creating a custom map colour scheme as a user of the Pathway Pro SDK, follow this link for a detailed example of creating a small custom map colour scheme.

Explaining a map color scheme

Important

Each scheme must be added to the ResourcesSdk2.json screens.schemes array for the Pathway Pro SDK to be able to use it.

See an example of the ResourcesSdk2.json file in the end of this chapter for reference. It defines one screen object for screens up to 500 dpi and one colour scheme with id Day-Car@2x.

Below you can find description of the objects used in the ResourcesSdk2.json file.

Screen object

Defines set of color schemes (styles) for a certain DPI. Application will pick up style automatically trying to match the closest DPI range from the "screen" array. If only one screen element is available it will be used for all DPI's

Attribute Name	Type	Description	Mandatory?

Attribute Name	Type	Description	Mandatory?
name	string	Friendly name of the screen resolution	Yes
maxDPI	int	Maximum screen DPI the style set will be used for	Yes
schemes	array	List of styles (color schemes)	Yes (at least one)

Scheme object

Defines parameters of map style. ResourcesSdk2.json has to have at least one scheme added.

Attribute Name	Type	Description	Mandatory?

Attribute Name	Type	Description	Mandatory?
id	string	ID which will be used in API to load the scheme	Yes
vehicleType	enum	Type of vehicle this scheme will be load for. Use "*" to use the scheme with all vehicle types.	Yes
isNight	array	Night or Day scheme. In case night scheme is missing in the list, day scheme will be loaded	Yes
fontFiles	array	Defines set of fonts used for map styling. You can add one file per operating system plus one default. See "FontFile" object also.	Yes
routeNumberPaths	array	List of paths to RouteNumber.col files defining look of Route Shields	No
zoomTableFiles	array	List of ZoomTableFiles defining Road Rending layers. Use default one unless advised by Pathway Pro developers. See also "ZoomTableFile" object	Yes
colorFiles	array	List of color files defining your map style. See "ColorFile" object also. In case you have more than one, files will override each other following the order they appear in configuration.	Yes

FontFile object

Defines set of fonts used for map styling for a given Operating System

Attribute Name	Type	Description	Mandatory?

Attribute Name	Type	Description	Mandatory?
platform	string	Name of the OS they file used for. Use "*" for a default entry.	Yes
path	string	Path to the font configuration file.	Yes

ZoomTableFile object

Defines set of roads selected from map db for rendering for each zoom level for a given map projection.

Attribute Name	Type	Description	Mandatory?

Attribute Name	Type	Description	Mandatory?
type	enum	Either 2D or 3D	Yes
path	string	Path to the configuration file.	Yes

ColorFile object

Defines location of color file used for styling

Attribute Name	Type	Description	Mandatory?

Attribute Name

Type

Description

Mandatory?

id

string

Unique file id for the scheme

Yes

path

string

Path to the configuration file.

.col file for default style
.json or .col file for style overrides
.col file for localities labels configuration file

Yes

countries

array

List of territory ID's the color file will be applied to. Use "*" for default entry

Yes

High-Dpi, Car, Day color scheme

{
	"file": "Pathway Pro Map Rasteriser Config",
	"version": "2.0.0",
	"screens": [
		{
			"name": "High DPI Screens",
			"maxDPI": 500,
			"schemes": [
				{
					"id": "Day-Car@2x",
					"vehicleType": "PASSENGER_CAR",
					"isNight": false,
					"fontFiles": [
						{
							"platform": "*",
							"path": "screen@2x/fonts/Default.col"
						},
						{
							"platform": "ANDROID",
							"path": "screen@2x/fonts/Android.col"
						},
						{
							"platform": "IOS",
							"path": "screen@2x/fonts/iOs.col"
						}
					],
					"routeNumberPaths": [
						"screen@2x/RouteNumbers.col"
					],
					"zoomTableFiles": [
						{
							"type": "2D",
							"path": "screen@2x/zoomTables/Default-2D.col"
						},
						{
							"type": "3D",
							"path": "screen@2x/zoomTables/Default-3D.col"
						}
					],
					"colorFiles": [
						{
							"id": "day-2x-main",
							"path": "screen@2x/schemes/day/Default.col",
							"countries": [
								"*"
							]
						},
						{
							"id": "day-2x-cities",
							"path": "shared/day/Cities.col",
							"countries": [
								"*"
							]
						},
						{
							"id": "day-2x-gbr",
							"path": "screen@2x/schemes/day/Default-GBR.json",
							"countries": [
								"GBR"
							]
						},
												{
							"id": "day-2x-closed",
							"path": "screen@2x/schemes/day/closed.json",
							"countries": [
								"*"
							]
						}
					]
				}
			]
		}
	]
}

Creating an inherited map colour scheme

It is possible to re-use an existing color scheme with overrides to create a new color scheme. A good example would be a pedestrian color scheme which is overriding GPS position cursor icon and road colours without defining every required scheme attribute.

Use BaseSchemeID to reference base scheme.
Define a new ID for the inherited scheme
Add overriding .col or .json files to the corresponding blocks

Inherited color scheme

{
	"file": "Pathway Pro Map Rasteriser Config",
	"version": "2.0.0",
	"screens": [
		{
			"name": "High DPI Screens",
			"maxDPI": 500,
			"schemes": [
				{
					"id": "Day-Car@2x",
					"vehicleType": "PASSENGER_CAR",
					"isNight": false,
					"fontFiles": [
						{
							"platform": "*",
							"path": "screen@2x/fonts/Default.col"
						},
						{
							"platform": "ANDROID",
							"path": "screen@2x/fonts/Android.col"
						},
						{
							"platform": "IOS",
							"path": "screen@2x/fonts/iOs.col"
						}
					],
					"routeNumberPaths": [
						"screen@2x/RouteNumbers.col"
					],
					"zoomTableFiles": [
						{
							"type": "2D",
							"path": "screen@2x/zoomTables/Default-2D.col"
						},
						{
							"type": "3D",
							"path": "screen@2x/zoomTables/Default-3D.col"
						}
					],
					"colorFiles": [
						{
							"id": "day-2x-main",
							"path": "screen@2x/schemes/day/Default.col",
							"countries": [
								"*"
							]
						},
						{
							"id": "day-2x-cities",
							"path": "shared/day/Cities.col",
							"countries": [
								"*"
							]
						},
						{
							"id": "day-2x-gbr",
							"path": "screen@2x/schemes/day/Default-GBR.json",
							"countries": [
								"GBR"
							]
						},
												{
							"id": "day-2x-closed",
							"path": "screen@2x/schemes/day/closed.json",
							"countries": [
								"*"
							]
						}
					]
				}
			]
        },
        {
            "baseSchemeID": "Day-Car@2x",
            "id": "Day-Pedestrian@2x",
            "vehicleType": "PEDESTRIAN",
            "colorFiles": [
                {
                    "id": "day-2x-walking",
                    "path": "screen@2x/schemes/day/Walking.json",
                    "countries": [
                        "*"
                    ]
                },
                {
                    "id": "day-2x-walking-gbr",
                    "path": "screen@2x/schemes/day/Walking-GBR.json",
                    "countries": [
                        "GBR"
                    ]
                }
            ]
        }
	]
}

Customising map colour schemes

Fonts

You may use default font styling from SDK core scheme if you don't want to change font styles on your map

Each font configuration file contains list of font aliases which can be used in main styling files you will create for color schemes.

Fonts file format

Each meaningful line has to start with FONT or SYSTEM_FONT tag.
Lines starting with "//" are treated as comment lines and will be ignored.
Empty lines are ignored
Line values are separated by either [SPACE] or [TAB]

System Font Mapping

TAG: SYSTEM_FONT

Defines system font aliases for each locale and font type (bold, italic etc)

Attribute	Description	Example

Attribute	Description	Example
TAG	Line identifier	SYSTEM_FONT
Font Face	System Font Alias	Road-Font
Locale	Specific locale this font should be used for. Possible options are: default Chinese Thai Cyrillic NearEast	Cyrillic
Italic	Font style	Yes/No
Bold	Font Weight	Yes/No
System Font	OS font mapping	HelveticaNeue

System Font Aliases (iOS.col)

//------------------------------------------------------------------------------------------------------------
//	Pathway Pro Map Renderer System Font Mapping
//
//	 - FileVer: Version of the color file
//	 - Dpi: DPI (1x, 2x, 3x)
//------------------------------------------------------------------------------------------------------------
//	TAG  	Date           	FileVer	Dpi    	ColorSchemeType	VehicleType
//------------------------------------------------------------------------------------------------------------
	VERSION	27/12/2016     	2.0    	2x     	n/a            	n/a

//-------------------------------------------------------------------------------------------------------------------------------
//       		     Font Face	    Locale		Bold	Italic      System Font
//-------------------------------------------------------------------------------------------------------------------------------
    SYSTEM_FONT  	"Road-Font"	    default 	No		No			"HelveticaNeue"
    SYSTEM_FONT		"Road-Font"	    default    	Yes		No			"HelveticaNeue-Medium"
    SYSTEM_FONT		"Road-Font"	    default    	No		Yes			"HelveticaNeue-Italic"
    SYSTEM_FONT		"Road-Font"	    default    	Yes		Yes			"HelveticaNeue-BoldItalic"

    SYSTEM_FONT		"Road-Number"	default		No		No			"HelveticaNeue-CondensedBold"
    SYSTEM_FONT		"Road-Number"	default		Yes		No			"HelveticaNeue-CondensedBold"
    SYSTEM_FONT		"Road-Number"	NearEast   	No		No			"ArialMT"
    SYSTEM_FONT		"Road-Number"	NearEast   	Yes		No			"Arial-BoldMT"
    SYSTEM_FONT		"Road-Number"	Chinese    	No		No			"STHeitiSC-Medium"
    SYSTEM_FONT		"Road-Number"	Thai    	No		No			"Thonburi"
    SYSTEM_FONT		"Road-Number"	Thai    	Yes		No			"Thonburi-Bold"

    SYSTEM_FONT		"City-Font"     default		No		No			"AvenirNext-DemiBold"
    SYSTEM_FONT		"City-Font"     default		Yes		No			"AvenirNext-Bold"
    SYSTEM_FONT		"City-Font"	    default		Yes		Yes			"AvenirNext-DemiBoldItalic"
    SYSTEM_FONT		"City-Font"	    default		No		Yes			"AvenirNext-Italic"
//  SYSTEM_FONT		"City-Font"	    Thai    	No		No			"Thonburi"
//  SYSTEM_FONT		"City-Font"	    Thai    	Yes		No			"Thonburi-Bold"

System Font Aliases (Android.col)

//------------------------------------------------------------------------------------------------------------
//	Pathway Pro Map Renderer System Font Mapping
//
//	 - FileVer: Version of the color file
//	 - Dpi: DPI (1x, 2x, 3x)
//------------------------------------------------------------------------------------------------------------
// TAG Date FileVer Dpi ColorSchemeType VehicleType
//------------------------------------------------------------------------------------------------------------
VERSION 27/12/2016 2.0 1x n/a n/a

//-------------------------------------------------------------------------------------------------------------------------------
// Font Face Locale Bold Italic System Font
//-------------------------------------------------------------------------------------------------------------------------------
SYSTEM_FONT "Road-Font" default No No "Roboto-Regular"
SYSTEM_FONT "Road-Font" default No Yes "Roboto-Italic"
SYSTEM_FONT "Road-Font" default Yes No "Roboto-Bold"
SYSTEM_FONT "Road-Font" default Yes Yes "Roboto-BoldItalic"

SYSTEM_FONT "Road-Number" default No No "RobotoCondensed-Bold"

SYSTEM_FONT "City-Font" default No No "RobotoCondensed-Bold"
// SYSTEM_FONT "City-FontThin" default No No "RobotoCondensed-Regular"

Styling Fonts mapping

TAG: FONT

Defines mapping between system aliases and styling aliases

Attribute	Description	Example

Attribute	Description	Example
TAG	Line identifier	FONT
Font ID	Styling Font alias (or ID) unique per OS font file	RoadFont-24; MyFontForRoads
Font Face	System Font Alias from Default.col	Road-Font
Font Size	Font size in pixels	24.0
Border Size	Font outline (border) width in pixels	1.0
Feather Size	Blurred outline size (shadow)	0.0
Font Weight	1.0 for normal, 2.0 for bold
Italic	Font style	Yes/No
Feather offset	Shadow direction	{1.0, 1.0}

Styling font aliases (Default.col)

//-------------------------------------------------------------------------------------------------------------------------------
// Roads
//-------------------------------------------------------------------------------------------------------------------------------
//        Font ID        Font Face						Font Size   Border Size   Feather Size   Font Weight  Italic   Feather Offset
//-------------------------------------------------------------------------------------------------------------------------------
    FONT  RoadFont-24   "Road-Font"						24.0        1.0           0.0            1.0          No       {0.0, 0.0}
    FONT  RoadFont-22   "Road-Font"						22.0        1.0           0.0            1.0          No       {0.0, 0.0}
    FONT  RoadFont-20   "Road-Font"						20.0        1.0           0.0            1.0          No       {0.0, 0.0}
    FONT  RoadFont-18   "Road-Font"						18.0        1.0           0.0            1.0          No       {0.0, 0.0}
    FONT  RoadFont-16   "Road-Font"						16.0        1.0           0.0            1.0          No       {0.0, 0.0}
    FONT  RoadFont-14   "Road-Font"						14.0        1.0           0.0            1.0          No       {0.0, 0.0}
//-------------------------------------------------------------------------------------------------------------------------------

//-------------------------------------------------------------------------------------------------------------------------------
// Areas
//-------------------------------------------------------------------------------------------------------------------------------
//        Font ID           Font Face				Font Size   Border Size   Feather Size   Font Weight  Italic   Feather Offset
//-------------------------------------------------------------------------------------------------------------------------------
    FONT  AreasFont         "Road-Font"				12.0        0.0          0.0            0.0        Yes       {0.0, 0.0}
    FONT  LandFont          "Road-Font"				10.0        0.0          0.0            0.0         No       {0.0, 0.0}
    FONT  AeroportFont      "City-Font"             22.0        0.0          0.0            2.0        Yes       {0.0, 0.0}
    FONT  RiverFont         "Road-Font"             12.0        0.0          0.0            0.0        Yes       {0.0, 0.0}
    FONT  RailwayFont_High  "Road-Font"             14.0        1.0          0.0            0.0        Yes       {0.0, 0.0}
    FONT  RailwayFont_Low   "Road-Font"             20.0        1.0          0.0            0.0        Yes       {0.0, 0.0}
//-------------------------------------------------------------------------------------------------------------------------------

Customising POI labels font

POI labels font can be defined using tag POI.

In the example below it is specified that POI labels should have red color, white outline color and use font id named CustomPoiFont.

//---------------------------------------------------------------------------------------------
// Style of POI items on map
//---------------------------------------------------------------------------------------------
// TAG   LabelColor    LabelOutlineColor   FontID
//---------------------------------------------------------------------------------------------
   POI   00000000      00FFFFFF            CustomPoiFont
//---------------------------------------------------------------------------------------------

Below you can see the definition of CustomPoiFont.

//-------------------------------------------------------------------------------------------------------------------------------
// POI Fonts
//--------------------------------------------------------------------------------------------------------------------------------------------
// TAG   Font ID        Font Face    Font Size   Border Size   Feather Size   Font Weight  Italic   Feather Offset
//--------------------------------------------------------------------------------------------------------------------------------------------
   FONT  CustomPoiFont  "Road-Font"  10          5.5           0.0            10.0         No       {0.0, 0.0}
//--------------------------------------------------------------------------------------------------------------------------------------------

Below you can see an example of POI font customisation setting the size to 16 and color to red.

//---------------------------------------------------------------------------------------------
// Style of POI items on map
//---------------------------------------------------------------------------------------------
// TAG  LabelColor  LabelOutlineColor  FontID
//---------------------------------------------------------------------------------------------
   POI  00FF0000    00FFFFFF           CustomPoiFont
//---------------------------------------------------------------------------------------------

//-------------------------------------------------------------------------------------------------------------------------------
// POI Fonts
//--------------------------------------------------------------------------------------------------------------------------------------------
// TAG   Font ID        Font Face    Font Size   Border Size   Feather Size   Font Weight  Italic   Feather Offset
//--------------------------------------------------------------------------------------------------------------------------------------------
   FONT  CustomPoiFont  "Road-Font"  16          5.5           0.0            10.0         No       {0.0, 0.0}
//--------------------------------------------------------------------------------------------------------------------------------------------

Road styling

Road styling is defined in one of the color files you added in "colorFiles" array of your scheme. One color file may contain different types of styling defined by "TAG" attribute of each line. Each color file may cover just a certain territory overriding default road styles. Further information about style overrides is described in "Creating territory styling" section.

TAG: ROAD

Defines styles and visibility of road classes at every zoom level.

Road Class Visibility

It is not recommended to change visibility of road class at zoom levels as it may affect rendering engine performance. If you decide to amend visibility you should be aware that:

Commented line ("//") is ignored by renderer and in case road functional class presents in zoom table, road styling will be defaulted (red in debug, light grey in release).
To actually hide (not to render) certain type of road at a particular zoom level, set its width to 0.

Attribute		Description	Example

Attribute		Description	Example
TAG	string	Line identifier	ROAD	always "ROAD"
FC	int	Road functional class. 0 - motorways 1 - A-class roads 2 - B-class roads 3 - Major roads 4 - Major city roads 5,6 - Other roads 7 - pedestrian roads	0-7
Zoom Level	int	Map zoom level the style is for. 0 - more details (closer to the ground), 25 - less details (farther from the ground)	0-25
Color	string	Road color in ARGB format	00E65929
Border Color	string	Road outline color in ARGB format	00B1181C
Label Colour	string	Road name label font color	00000000
Label Outline Colour	string	Road name outline font color	4DFFFFFF
Width	double	Road width, including border	52.0
Border Width	double	Road outline width in pixels. 0 - no border.	2.0
Road Name	bool	Render road name or not	Yes/No
Arrow Colour	string	One-way arrow colour in ARGB format	00FFFFFF
Arrow Outline Colour