SDK for Android Developer's Guide

Map Customization

Whether you want to optimize your map for a certain display size, use case, branding, or highlight objects which are important to your users, the HERE SDK map customization feature allows a high degree of customization freedom so that you can achieve fine control of your map view's rendering characteristics.

This section presents the components and concepts which you need to create your own map look-and-feel.

Map Schemes

Map customization starts by using one of the predefined schemes (such as "Normal Day" and "Normal Night") to serve as a starting point. These predefined schemes are not customizable themselves, but provide the initial values that a custom scheme derives from.

The following screenshots show examples of pre-defined schemes available in HERE SDK.

To customize the map, the first step is to obtain a Customizable Scheme object from the map view. With this object you can then set properties to modify the map. You can change color, icon size, width, length, and other properties of almost all map objects such as buildings, land features, and roads. Whether property changes are visible depends on if the map you are customizing is currently at the affected zoom level, and the map scheme is active.

Note: A custom scheme is not permanently saved, but it lives as long as the map view object is in memory.

Map Customization Example on GitHub

You can find an example that demonstrates this feature at https://github.com/heremaps/.

Creating Your First Map Scheme Customization

After you decide on which scheme to base on, create a Customizable Scheme object with the map view method:

CustomizableScheme scheme = map.createCustomizableScheme("newCustomScheme", Map.Scheme.NORMAL_DAY);

After creating the customizable scheme, you can retrieve it again with the following method, as long as the map view object was not destroyed. Customizable Schemes are created and valid only to the specific Map View from which they were obtained:

CustomizableScheme scheme = map.getCustomizableScheme("newCustomScheme");

You can then get map attributes for a particular zoom level. To set attributes, specify a zoom range. A helper ZoomRange class is provided which takes a minimum and maximum zoom level value.

ZoomRange range = new ZoomRange (0, 20);

HERE SDK has a class called CustomizableVariables which lists all the attributes that HERE SDK supports for customization.

Note that in the CustomizableVariables class map attributes are wrapped in their respective types to identify their type. For example, CustomizableVariables.CountryBoundary.WIDTH is of SchemeFloatProperty type which means that it is holding float value. The same applies for the others.

The SDK provides the following helper classes to handle different types of properties:

CustomizableColorProperty - specify color type (In Android Color is represented as ARGB integer color value)
SchemeFloatProperty - specify float type
CustomizableIntegerProperty - specify int type

To change map attributes for color, float, and integer types, perform the following:


// change 0M water color
 CustomizableScheme.ErrorCode errorCode = scheme.setVariableValue(CustomizableVariables.Water.COLOR_0M, Color.RED, range);
// get water color for zoom level 10
int waterColor0M = scheme.getVariableValue(CustomizableVariables.Water.COLOR_0M, 10.0f);

// change 3d landmark
 CustomizableScheme.ErrorCode errorCode = scheme.setVariableValue(CustomizableVariables.Landmark3d.ALPHA, 1, range);
// get 3d landmark for zoom level 10
int waterColor0M = scheme.getVariableValue(CustomizableVariables.Landmark3d.ALPHA, 10.0f);

// change CountryBoundary WIDTH
 CustomizableScheme.ErrorCode errorCode = scheme.setVariableValue(CustomizableVariables.CountryBoundary.WIDTH, 2.0f, range);
// get CountryBoundary WIDTH for zoom level 10
float countryBoundaryWidth = scheme.getVariableValue(CustomizableVariables.CountryBoundary.WIDTH, 10.0f);

After customizing you should activate your scheme by calling one of following methods:


Map.setMapScheme(CustomizableScheme customizableScheme);


Map.setMapScheme(String scheme)

Note: You can customize the current activated custom scheme but changes are not automatically applied. Remember to call one of the above methods to refresh the map scheme.

The following is a more complete example:


// create a new scheme
CustomizableScheme scheme = map.createCustomizableScheme("newCustomScheme", Map.Scheme.NORMAL_DAY);

// change water color 0m
int lightYellow = Color.argb(0, 255,255,224);
CustomizableScheme.ErrorCode err = scheme.setVariableValue(CustomizableVariables.Water.COLOR_0M, lightYellow , range);
Log.i(TAG, "Error: " + err);

// change water color 3000m
err = scheme.setVariableValue(CustomizableVariables.Water.COLOR_3000M, Color.YELLOW, range);
Log.i(TAG, "Error: " + err);

// activate scheme
map.setMapScheme(scheme);