Add a map

Handling the runtime data

The MapTrip SDK requires a set of files as runtime data to be placed on the device's storage. In case you checked our example apps (MiniNaviKotlin & MapTripSDKQuickUI) you might have realized that they do start out of the box. Handling the runtime data can be quite tricky. Starting with MapTrip SDK version 9.4.0 we are happy to provide a helping mechanism. Just wrap your runtime data from the SDK's delivery package external_storage folder excluding the map data (data) in a file called res.zip and place it in your App's assets folder. Check the example Apps' assets folder for reference, you can just use it directly as well.

The MapTrip SDK will then care for extracting the data to your device upon initializing. If newer SDK versions require changed runtime data you will just need to replace your res.zip file. Files in the user folder will not be replaced. The same way works for map data in form of a file called data.zip. However, you should only use it for online mapdata or for small countries. If you want to use the MapTrip SDK with onboard data, we recommend using a data server for downloads or using a mobile device managment for your devices.

Info

Depending on how you want to use the SDK it is important to use the right map data. If you want to use the SDK offline or have a fallback to local map data for navigation you will need the full map data of your desired region on your device's storage. It is provided in your SDK package's runtime data or provided separately by us for you.

Updating the runtime data

Updating to a newer version of the SDK often requires to update single runtime data files. Most frequently we make changes on our mapservices.xml to adjust our map appearance. Take a look on our Changelog what files have changed. If you choose to use the res.zip mechanism, you can simply replace that file when upgrading the SDK.

Initialization

The initialize Method is asynchronous and fires a callback as soon as it is finished. Prior to calling the initialize Method, the SDK needs the locations for the runtime data by calling ApiHelper.initPaths(). The code below shows typical used paths used for the example app. Starting with the MapTrip SDK 9.4.0 you can skip it. The SDK will just assume that your data is placed in your external files directory in a folder called MapTrip SDK, e.g. Android/data/your_package_name/files/MapTripSDK.

ApiHelper.Instance().initPaths(
    appPath,        // Android/data/your package name/files/MapTripSDK
    dataPath,       // appPath + /data/
    resourcePath,   // appPath + /res/
    osUserDataPath, // appPath + /user/
    tempPath,       // appPath + /temp/
    mapservicexml   // appPath + /mapservices.xml
)

// or

ApiHelper.Instance().initPaths(
    appPath)        // Android/data/your package name/files/MapTripSDK

The initialize methods require a Context to access device information about the display and an ApiInitListener instance. This interface provides a set of callbacks that inform about the asynchronous initialization process. You should pass your application's context here. As you can use the MapTrip SDK in an online, offline and hybrid mode you also need to set matching ComputationSiteParameters. Currently, it is only required to set the Geocoder to geocode online (offboard) or offline (onboard) which is the default.

// Different configurations for ComputationSiteParameters

val computationSiteParameters = ComputationSiteParameters()

// Set Geocoder to work online instead of offline
computationSiteParameters.geocoding = ComputationSite.OFFBOARD

ApiHelper.Instance()
    .initialize(
        applicationContext,
                computationSiteParameters,
        object : ApiInitListener {
            override fun onApiInitialized() {
                // successful init
            }

            override fun onApiInitError(err: ApiError?, msg: String?) {
                // init error - maybe datasets missing?
            }

            override fun onApiUninitialized() {
                // uninit complete
            }
        }
    )

How to add a map

To add a map, you can use the MapTrip SDK's IwMapView class. It extends Android's View class so you can simply add it to your layout by using the code below. Therefore, the IwMapView behaves as you would expect from any other Android view.

The IwMapView class can be created via XML and maps can be added without having to write code. The following XML Tag shows how a map can be added.

<de.infoware.android.api.IwMapView
    android:id="@+id/map"
    api:iwId="1"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

You have to distinguish between:

• IwMapView, which brings the rendered image to the androids View architecture. It has a reference to the
• MapViewer, which is the MapTrip SDK's instance that renders the map

As soon as the MapTrip SDK is initialized, the MapViewer will start to render.

If the IwMapView has a unique id assigned to it, it will keep its configuration like zoom height or perspective over configuration changes. User specific items have to be created by yourself in the App. If you don't specify an id, the Mapviewer will use its default configuration from the XML for example.

How to modify the map

There are 3 different ways to modify the map appearence:

• By XML - the simplest way to define an initial configuration e.g. to set the perspective
• By accessing the MapViewer - fastest way for changes at runtime like setting zoom height, map center
• By setting a config object - best way to pass MapViewer configurations via intents or handle life cycle changes.

Modify by XML

The most easy way to modify a Mapviewer is to specify XML attributes. The MapTrip SDK contains xml attributes for the map that can be enabled by adding xmlns:api="http://schemas.android.com/apk/res-auto" to the IwMapView.

<de.infoware.android.api.IwMapView android:id="@+id/map"
        xmlns:api="http://schemas.android.com/apk/res-auto"
        android:id="@+id/map"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

Parameters (paramName=defaultValue):

• iwId=1 The iwId makes the MapTrip SDKs Mapviewer uniquely identifiable over the lifecycle of its IwMapView object.
  • Every IwMapView with a unique Id has its own set of user Pois that are restored when the mapviewer is destroyed and recreated
  • If you don't specify an id, every new created instance of the MapViewer ( e.g. when switching activities ) will not contain any user POI's
  • If you assign an id multiple times, all mapviewers will contain the same user POI and modifications on them (show or hide) will affect all Mapviewers with the same id
• useTextureView=false if true, a texture view is used as container, if false a surface view is used
• perspective="perspective_2d_northward" defines the perspective of the map. Possible values are:
  • perspective_3d: 3D Map, that is always centered at current orientation (rotating)
  • perspective_2d_northward: 2D Map, that is always centered towards north (not rotating)
  • perspective2d_driving_direction: 2D Map, that is always centered at current orientation (rotating)
• showVehicleIcon="false" if true the defined vehicle icon is shown on the map
• enableLocationTracking="false" if true the map is centered and rotated on the current position with every new location update until the map is moved ( touched )
• colorProfile="" set the color profile that the map shall apply. The mapservices.xml and colors.xml files may contain color profiles which can be activated here. The default profile “” refers to the Deluxe color profile. In the default configuration a second color profile (premium) can be applied
• visiblePoiSourceNames="" list all string ids of poi sources that should be visible. Lists are separated by the pipe character. For Example: api:visiblePoiSourceNames="TrafficFlows" To get a list of all possible pois sources use PoiSource.getPoiSources() and PoiSource.getName().
• visiblePoiCategoryNames="" list all string names of poi categories that should be shown on the map. List are separated by the pipe character. For Example: api:visiblePoiCategoryNames="Polizei|Apotheke" To get a list of all possible pois sources use{{ no such element: dict object['getTopLevelCategories'] }} and PoiCategory.getName().

Modify by accessing the map object

The MapViewer object is part of the View and can be accessed by a views getter. This way of modifying the map is intended for dynamic changes during runtime.

// get the Map View
val mapView = findViewById<View>(R.id.map) as IwMapView
// get the map object
val map = mapView.mapviewer
// modify the map
map?.setViewingDistance(1000.0)

As the IwMapView object depends on the lifecycle of the SDK as well as the Views OpenGL preparation which might take a few milliseconds, it is possible that the MapViewer object might be null directly after the view's creation. Therefore, you can register a callback which indicates if the MapViewer object is available:

val mapView = findViewById<View>(R.id.map) as IwMapView
mapView.setOnMapviewerReadyListener {
    val mapViewer = mapView.mapviewer
    mapViewer?.setViewingDistance(1000.0)
}
...

Modify by setting a config object

The Mapviewer state is represented by a config object IwMapviewerConfig that can be accessed at any time by a getter. It is designed to be used if you do not directly have access to your view objects, e.g. via Intents. Therefore, it implements the Parcelable interface.

All Map attributes are represented by the config and can be modified by setters. To apply a config, the IwMapviewerConfig provides the method applyConfig which takes the IwMapView to apply as parameter. A basic config can be created like this:

// create mapconfig with default values
val config = IwMapviewerConfig()
// apply config to a map
config.applyConfiguration(mapView)

Alternatively every IwMapView's config can be requested by a getter method:

val config = mapView.mapviewerConfig

Prepare your map for navigation purposes

We recommend the following settings to prepare your map for navigation purposes:

<de.infoware.android.api.IwMapView
        android:id="@+id/map"
        xmlns:api="http://schemas.android.com/apk/res-auto"
        api:iwId="1"
        api:showVehicleIcon="true"
        api:enableLocationTracking="true"
        api:perspective="perspective_3d"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

These settings will prepare your map to show a vehicle icon and to follow the user's position.

Enable location tracking

There are three different ways to enable location tracking for the MapTrip SDK

• IwLocationManagerGPS to use the location capabilities of your device
• IwLocationManagerLog to mock the location by playing a NMEA-Log
• IwLocationManagerManual to implement your own location engine and pass locations to the MapTrip SDK manually

To develop your own navigation application, we will continue by using the IwLocationManagerGPS Class. Just create a new instance of IwLocationManagerGPS and pass it to the ApiHelper.instance() as shown below, e.g. in the onCreate method of your activity or fragment. You should call it after requesting the permissions.

ApiHelper.Instance().locationManager = IwLocationManagerGPS(applicationContext)

Next, enable the location tracking by calling:

ApiHelper.Instance().locationManager.enableLocationUpdates()

We recommend doing so in your onResume method of your activity or fragment or once the mapviewer is ready. Please make sure to call it from your UI-Thread. If you do not need location tracking when your app is in the background, you can simple pause it by calling:

ApiHelper.Instance().locationManager.disableLocationUpdates()

What's next?

Check out the SDK Concepts guide if you want to learn more about the most important concepts. If you want to know how calculate routes and start route guidance, you should check out the Navigation guide.