Custom Map Styles

The HERE SDK for Flutter provides a flexible solution to customize the map by loading custom map schemes.

If you are looking for predefined map styles, see the Quick Start guide for an introduction. The HERE SDK already includes a set of pre-configured map styles such as .normalDay or .satellite.

Create and Load Custom Map Styles

The most flexible solution to customize the map is to create your own map styles using a configuration file generated with the WYSIWYG HERE Style Editor.

As soon as you are satisfied with your custom map style, export it via File -> Export -> Here Rendering Engine Configuration. Please unzip the resulting file. You will find a few JSON files.

Copy all JSON files into the "assets" directory of your project. If not already added, you can add that folder via Android Studio (Right-click on the project: New -> Folder -> Assets folder). You can also manually generate the folder: /your_app/assets. This folder also needs to be included into your pubspec.yaml:

# The following section is specific to Flutter.
flutter:

  # Here we store our custom map styles.
  assets:
    - assets/

For this example, we use the path_provider plugin to use the File class to get the required file path to our main style file.

The main style file always ends with *.scene.json.

Load the style into a map scene as follows:

import 'dart:io';

import 'package:flutter/services.dart' show rootBundle;
import 'package:here_sdk/core.dart';
import 'package:here_sdk/mapview.dart';
import 'package:path_provider/path_provider.dart';

...

void loadCustomMapStyle() async {
  // From this file other style files can be referenced.
  String filePath = await loadCustomStyle('omv-traffic-traffic-normal-night.scene.json');

  // We also need to load referenced style files into the application directory.
  await loadCustomStyle('omv-traffic-traffic-normal-night.jss');
  await loadCustomStyle('omv-traffic-traffic-normal-night-MapOmvVisibilityRanges.json');
  await loadCustomStyle('omv-traffic-traffic-normal-night-layer.properties.json');

  _hereMapController.mapScene.loadSceneFromConfigurationFile(filePath, (MapError? error) {
    if (error == null) {
      // Scene loaded.
    } else {
      print("Map scene not loaded. MapError: " + error.toString());
    }
  });
}

// Copies a file from assets folder to application directory from where we can retrieve the file path.
Future<String> loadCustomStyle(String assetFile) async {
  // This allows to read the file, but does not provide a path to the file.
  var fileAsBytes = await rootBundle.load("assets/" + assetFile);
  String applicationDirectory = (await getApplicationDocumentsDirectory()).path;

  final buffer = fileAsBytes.buffer;
  File file = File('$applicationDirectory/$assetFile');

  // We need to copy all style files to app directory as the main scene.json style file expects
  // other style files in same folder.
  file.writeAsBytes(buffer.asUint8List(fileAsBytes.offsetInBytes, fileAsBytes.lengthInBytes));
  return file.path;
}

With the main *.scene.json file the HERE SDK will find the other referenced style files - as exported from the editor, so we only need to get the file path for this file, but we have to make sure that all style files are kept together at the same folder level.

Using custom map styles can be very effective to differentiate your app from other map applications. In addition, it is possible to change map styles on-the-fly, for example, to shift the user's attention to certain map elements based on the current state of your app.