Creating a custom colour scheme

Owned by Andrey Trifonov
Last updated: Apr 24, 2024 by Dmitry Lykov

This example explains how to create a custom map style overriding base styles supplied by Navmii. The custom style in this example overrides GPS position cursor for car mode (night & day) and also illustrates some other visual changes which can be applied to map view appearance.

Step 1: prepare base resources

  • Create a folder which will contain your style resources
  • Copy your GPS position icon images into this folder.
  • Copy ResourcesSdk2.json (attached to this page) into the root of your resources folder


ResourcesSdk2.json provided in this example describes 4 map colour schemes overriding the corresponding schemes preinstalled in the SDK bundle. The schemes are Custom-Day-Car@1x, Custom-Day-Night@1x, Custom-Day-Car@2x, Custom-Day-Night@2x for 1x and 2x screens correspondingly. If some scheme in the file overrides another scheme specified in the same ResourcesSdk2.json file, it have to be declared below its base scheme.

Here is an example of ResourcesSdk2.json file:

ResourcesSdk2.json with custom schemes
{
    "file": "Navmii Map Rasteriser Config",
    "version": "2.0.0",
    "screens": [
        {
            "name": "Single DPI Screens",
            "maxDPI": 134,
            "schemes": [
                {
                    "baseSchemeID": "Day-Car@1x",
                    "id": "Custom-Day-Car@1x",
                    "vehicleType": "PASSENGER_CAR",
                    "colorFiles": [
                        {
                            "id": "day-1x-custom",
                            "path": "Custom-Day-Car@1x.json",
                            "countries": [
                                "*"
                            ]
                        }
                    ]
                },
                {
                    "baseSchemeID": "Night-Car@1x",
                    "id": "Custom-Night-Car@1x",
                    "vehicleType": "PASSENGER_CAR",
                    "colorFiles": [
                        {
                            "id": "night-1x-custom",
                            "path": "Custom-Night-Car@1x.json",
                            "countries": [
                                "*"
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "name": "High DPI Screens",
            "maxDPI": 500,
            "schemes": [
                {
                    "baseSchemeID": "Day-Car@2x",
                    "id": "Custom-Day-Car@2x",
                    "vehicleType": "PASSENGER_CAR",
                    "colorFiles": [
                        {
                            "id": "day-2x-custom-json",
                            "path": "Custom-Day-Car@2x.json",
                            "countries": [
                                "*"
                            ]
                        },
                        {
                            "id": "day-2x-custom-col",
                            "path": "Custom-Day-Car@2x.col",
                            "countries": [
                                "*"
                            ]
                        }
                    ]
                },
                {
                    "baseSchemeID": "Night-Car@2x",
                    "id": "Custom-Night-Car@2x",
                    "vehicleType": "PASSENGER_CAR",
                    "colorFiles": [
                        {
                            "id": "night-2x-custom",
                            "path": "Custom-Night-Car@2x.json",
                            "countries": [
                                "*"
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}


Step 2: create scheme overrides

Create 4 files in the resources folder obtained on step 1: Custom-Day-Car@1x.json, Custom-Night-Car@1x.json, Custom-Day-Car@2x.json and Custom-Night-Car@2x.json. Below you can find an example of the contents for those files. These will be your .json overrides.
Custom-Day-Night@2x.json
{
    "road":
    [
      {
        "fc": [0,1,2,3,4,5,6,7],
        "zoom": [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18],
        "color": "000000FF",
        "borderColor": "00FF0000"
      }
    ],
    "image":[
         {
             "name": "PositionArrowImage",
             "path": "$userRoot\\<RELATIVE_PATH_TO_CUSTOM_GPS_POSITION_ICON_IN_2D_MODE>"
         },
         {
             "name": "PositionArrowImage3D",
             "path": "$userRoot\\<RELATIVE_PATH_TO_CUSTOM_GPS_POSITION_ICON_IN_3D_MODE>"
         },
         {
             "name": "PositionArrowLowZoomLevel",
             "path": "$userRoot\\<RELATIVE_PATH_TO_CUSTOM_GPS_POSITION_ICON_ON_HIGH_ZOOM_LEVELS>"
         },
         {
             "name": "PositionArrowImageNoRoute",
             "path": "$userRoot\\<RELATIVE_PATH_TO_CUSTOM_GPS_POSITION_ICON>"
         }
     ]
}
In the example above the following overrides will be applied:
  • roads of all the functional classes (0-7) on all the zoom levels (1-18) will have blue colour with red stroke;
  • custom images will be specified for GPS icon in the corresponding modes: PositionArrowImage, PositionArrowImage3D, PositionArrowLowZoomLevel and PositionArrowImageNoRoute. 

Replace values in angle brackets (<>) with the corresponding image file path relative to "userRoot" path which you will specify in the code on Step 3 as customResourcesPath property of the NMConfigurationSettings class. Make sure that all the contents of the CustomMapResources folder will be copied in the application bundle during the build process.


To apply overrides in .col file, create Custom-Day-Car@2x.col file in the resources folder obtained on step 1. Below you can find an example of the contents for col file.

Custom-Day-Car@2x.col
//-----------------------------------------------------------------------------------------------------------------------------------------------------
//	Map Backround Color (LAND)
//-----------------------------------------------------------------------------------------------------------------------------------------------------
//	TAG  	Zoom	Color   	BorderColor	LabelCol	LabelOutlineCol	FontID         	MaxZoomLevel	TextureName         
//-----------------------------------------------------------------------------------------------------------------------------------------------------
	LAND 	0   	00A00000	00E6E0D5   	003B5E33	00FFFFFF       	AreasFont      	19          	null                
	LAND 	1   	00FF0000	00F0ECE5   	003B5E33	00FFFFFF       	AreasFont      	19          	null                
	LAND 	2   	00A00000	00F0ECE5   	003B5E33	00FFFFFF       	AreasFont      	19          	null                
	LAND 	3   	00A00000	00F0ECE5   	003B5E33	00FFFFFF       	AreasFont      	19          	null                
	LAND 	4   	00A00000	00F0ECE5   	003B5E33	00FFFFFF       	AreasFont      	19          	null                

	LAND 	15  	0000A000	00F0ECE5   	003B5E33	00FFFFFF       	AreasFont      	19          	null                
	LAND 	16  	0000A000	00F0ECE5   	003B5E33	00FFFFFF       	AreasFont      	19          	null                
	LAND 	17  	0000A000	00F0ECE5   	003B5E33	00FFFFFF       	AreasFont      	19          	null                
	LAND 	18  	0000A000	00F0ECE5   	003B5E33	00FFFFFF       	AreasFont      	19          	null                
	LAND 	19  	0000A000	00F0ECE5   	003B5E33	00FFFFFF       	AreasFont      	19          	null   

//----------------------------------------------------------------------------------------------------------------------------------------------------------------
//	Areas (Polygons) on map
//
//	 - MaxZoomLevel: Area will not be rendered after this zoom level
//----------------------------------------------------------------------------------------------------------------------------------------------------------------
//	TAG  	Type           	Color   	BorderColor	LabelCol	LabelOutlineCol	FontID         	MaxZoomLevel	TextureName         
//----------------------------------------------------------------------------------------------------------------------------------------------------------------
	AREA 	AREAWATERWAY   	00FF00FF	0098CAED   	0012507B	00FFFFFF       	AreasFont      	12          	null                
	AREA 	PARK           	0000FFFF	00CBDFAD   	00678660	00FFFFFF       	AreasFont      	11          	"texturesPDA\day_park.png"

For more details on what can be overriden in a .col file check out the following article: Customising The Map Look.

 

Step 3: define custom resources root path (iOS)

Now you need to specify the path to CustomMapResources folder to the SDK. To achieve this you need to pass configuration settings in startWithSettings: method of NMSdk. You can also specify the map colour scheme the SDK will load on start by setting its identifier to the mapSchemeId property of the configuration settings: 


NSURL *externalMapResourcesUrl = [[NSBundle mainBundle] URLForResource:@"CustomMapResources" withExtension:nil];

configurationSettings.customResourcesPath = externalMapResourcesUrl.path;
configurationSettings.mapSchemeId = @"Custom-Day-Car@2x";

[navmiiSDK startWithSettings:configurationSettings];
If you're supporting devices with single DPI screens, you need to create another 2 schemes in the "Single DPI Screens" screen (in ResourcesSdk2.json) and inherit them from Day-Default@1x and Night-Car@1x.
Please note that you can also load a colour scheme using the -(void)loadMapScheme:(NSString *)schemeId method of NMMapView. To get the list of map schemes appropriate for current screen use availableMapSchemes property of NMMapView.
  
  

Step 3: define custom resources root path (Android)

To set a path to CustomResources folder in the SDK, you need to use setCustomResourcesPath method in ConfigurationSettings.Builder() and init Sdk with the settings :


final String customResourcesPath = context.getFilesDir().getAbsolutePath()
        + File.separator + "assets" + File.separator + "schemes";

Sdk.ConfigurationSettings settings = new Sdk.ConfigurationSettings.Builder()
        .setCustomResourcesPath(customResourcesPath)
		.build()

sdk.initSdkAsync(getActivity(), settings);

The next step is loading your scheme to map with loadMapScheme method:

String customMapScheme = "Custom-Day-Car@2x";
mapView.loadMapScheme(customMapScheme);

 

Step 4: verify scheme is loaded

Compile your project and check that GPS icon for car mode is now using your custom icon.