Introduction to NaviGenie SDK Client API for Android

Introduction to NaviGenie™ SDK Client API

for Android

Overview ... 3

Data access solutions ... 3

Use your own data in a highly optimized form ... 3  

Hardware acceleration support ... 3

Package contents ... 4

Development with the SDK ... 5

SDK prerequisites ... 5  

Creating the Android project with a data source ... 5

Create an Android Java project ... 6

Create the Java code ... 7  

DataSource handling ... 10

Adding an NGUMapView to the project ... 12

Init map view ... 12  

Change orientation ... 13

Overview

NaviGenie SDK revolutionizes location based application development providing optimized, scalable data services and high performance hardware accelerated map visualization engine. The NaviGenie SDK enables developers to implement or adapt most enjoyable applications with better user experience.

Data access solutions

The NaviGenie Client API provides on-board, off-board and mixed mode data handling solutions. Thanks to the NaviGenie compression technology you can save hundreds of megabytes and store larger data sets on wide spread mobile devices equipped with limited storage capacity.

NaviGenie can also be used in mixed mode environments where the network facility is only used for the regular map updates which are cached on the navigation device. Using our advanced technology map updates will be faster and cheaper for users and manufacturers as well.

Use your own data in a highly optimized form

NaviGenie Data Conversion Server provides unique technologies to convert; optimize and compress standard 2D and 3D vector based map formats for low-bandwidth mobile use based on a standard Oracle database backend. The currently supported formats include Collada, GDF, OBJ, ODF, SHP, VRML, X3D; additional formats can be added easily. The server is fully compatible with Navteq, OpenStreetMap and Tele Atlas 2D and 3D map formats.

Hardware acceleration support

NaviGenie client supports hardware accelerated graphics in order to give a better user experience - faster frame rates, anti-aliased lines and polygons, geographically correct shadows, enhanced visual effects - and to save power and bandwidth. Power is saved by the graphic accelerator chip (GPU) as it uses less power to calculate a frame than the generic embedded CPU. In addition to this most GPUs support efficient texture compression technologies - which are automatically used by NaviGenie - to decrease the size of texture data downloaded to the handset.

Package contents

The table summarizes the contents of the developer package:

Directory Description

data Contains the configuration files.

NGAPI SDK Include directory

NGUtils Utility classes

platforms/android/doc API documentation (HTML format) platforms/android/lib NaviGenie SDK binaries

platforms/android/Tutorial/HelloWorld The instantly buildable version of the tutorial application we’ll describe in this document.

platforms/android/NGApiDemos Low level API demo

platforms/android/NGUApiDemos API demo of the Utility classes.

platforms/android/InstantMap Navigation application which demos the Android Java API

platforms/android/Tutorial/NaviGenie_T utorial_android.pdf

This document.

Libraries

The lib directory contains the following binary packages:

Library Description

NGBase (libNGBase.a) Common base classes. MapFolderDatabase (libMapFolderDatabase.a),

NGBuilder (libNGBuilder.a),

NGDataSource (libNGDataSource.a), NGFormat(libNGFormat.a),

NGEngine (libNGEngine.a)

Engine of the SDK and auxiliary modules. Representation of a data source. The module hides the on-board, off-board functionality, providing a standard interface for collecting the needed map data for other modules. NGMap (libNGMap.a, NGMapView.jar) OpenGL based map view component. Does

map rendering and provides interfaces to manipulate built-in and user created map data and related events to them.

NGMapSearch (libNGMapSearch.a) Provides search services.

NGRoute (libNGRoute.a) Provides routing services, find directions between multiple waypoints.

NGGeocode (libNGGeocode.a) Provides geocoding services based on address hierarchy levels.

NGGpsFilter (libNGGpsFilter.a) Provides location handling services. NGReverseGeocode (libNGReverseGeocode.a) Provides reverse geocoding services. NGUtils (libNGUtils.a) Utility classes. Platform independent layer

that wraps the low level API. NGJUtils (libNGJUtils.so, NGJUtils.jar) Android Java API.

NGApiDemos

The NGApiDemos Android application introduces the NaviGenie SDK Client API. You can find several examples for the modules.

NGUApiDemos

The NGUApiDemos Android application introduces the NaviGenie Utility classes. It contains an API with more userfriendly classes. You can find several examples for the modules.

InstantMap

The InstantMap Android application introduces the NaviGenie Java SDK Client API. It is a more complex demo, which uses only the Java API.

Supported platforms

The SDK is written in C++, and contains user interface support for iOS, Android and Qt (Win32 MinGW) platforms.

Development with the SDK

This document helps you getting started with the NaviGenie SDK as a first project, we would like to create a simple map view with NaviGenie to see the mentioned performance.

In the tutorial code samples we will highlight the new code lines / snippets with italic bold font style.

SDK prerequisites

• Eclipse (3.7 Indigo recommended) • ADT for Eclipse

• Android NDK r7

• Android SDK (API level 8 or newer) • SDK Tools r14

Creating the Android project with a data source

We will start with the simplest Android application template. The first step to achieve our goal is to create an application which is able to handle the NaviGenie map data. It will be done by the following steps:

• Create the Android Java project. • Copy the SDK data to the device. These steps are explained below.

Create an Android Java project

Create a new project by selecting New -> Android project... from the File menu.

Figure 1. Create new project

Figure 3. Set target API level

Figure 4. Android project settings

Create the Java code

The MapActivity.java source file will be generated automatically, which contains the following code: MapActivity.java

public class MapActivity extends Activity {

/** Called when the activity is first created. */ @Override

public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState);

setContentView(R.layout.main); }

}

Copy the following native libraries and jar files to the proper place from the package (<package_location>/platforms/android/lib):

• libNGJUtils.so • libxml2.so • NGJUtils.jar • NGMapView.jar

The project directory should look like this, listing the dynamic libraries and jar files:

Figure 5. Project tree showing the native libraries and java packages Set the location of the native libraries and add jar files to the project:

à Project à Properties à Java Build Path à Libraries

à add External JARs…, and browse .jar files in the platforms/android/libs directory. Click on “Native library location“ and browse .so files.

Figure 6. Project properties window for adding libraries

To make native libraries available for the java application in runtime, let’s load them dinamically adding the following code snippet to the code of the MapActivity class.

MapActivity.java

package com.example.navigenie; import android.app.Activity; import android.os.Bundle;

public class MapActivity extends Activity { ... static { System.loadLibrary("xml2"); System.loadLibrary("NGJUtils"); } ... }

DataSource handling

There are required permissions for authorization. These should be set in the manifest xml file.

Create NGUDataSource object for data source handling in the MapActivity.java, and place the method calls in onCreate and onDestroy:

MapActivity.java package com.example.navigenie; import android.app.Activity; import android.os.Bundle; import com.navigenie.sdk.NGUAuthResult; import com.navigenie.sdk.NGUDataSource; import com.navigenie.sdk.NGUDataSource.OnAuthFinishedListener; import android.util.Log;

public class MapActivity extends Activity {

private final String MY_CID = "PUT_YOUR_CID_HERE";

private final String MY_AID = "PUT_YOUR_AID_HERE";

private NGUDataSource mDataSource = null; // Data source (engine)

...

@Override

public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState);

// Init data source

mDataSource = new NGUDataSource();

String datasourcePath = "/sdcard/navigenie_sdk/data/";

mDataSource.open( datasourcePath, datasourcePath, MY_CID, MY_AID, this, AndroidManifest.xml <?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.navigenie" android:versionCode="1" android:versionName="1.0" >

<uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<uses-permission android:name="android.permission.GET_ACCOUNTS" />

<uses-sdk android:minSdkVersion="8" /> ...

new OnAuthFinishedListener() {

@Override

public void onAuthFinished(NGUAuthResult result) { Log.d("helloWorld", "Authorization result: " + result.getAuthStatusText()); } }); setContentView(R.layout.main); } @Override

protected void onDestroy() { mDataSource.close(); }

... }

The open method of the NGUDataSource object will initialize the Engine of the SDK. This object is used for initializing of all main modules of Navigenie SDK. For initializing of this object you should set the location of a readable and a writeable storage which will be used by the SDK. You should set the CID and AID strings for authorization process, a Java context and a listener, which will handle the result of authorization. In this case we only log the status of the authorization.

Note: You should replace PUT_YOUR_CID_HERE and PUT_YOUR_AID_HERE strings to your own CID and AID strings got at registration. These identifiers are used for authorization.

Testing the data source

To run the test, we have to copy the data of the SDK to the device, under the /sdcard/navigenie_sdk/data folder.

Note: The location must be the same as the value of the datasourcePath variable in the code.

Let’s test what we have done.

After starting the application we will see the log in the logcat:

Adding an NGUMapView to the project

In this section we will add an NGUMapView to the activity and set it up to use the previously initialized data source.

Init map view

Add an NGUMapView object as a member variable to the MapActivity class. This object is responsible for showing the map.

Let’s add an NGUMapView member to MapActivity and complete the onResume, onPause and onDestroy methods with the mapview lifecycle method calls. After it, the Activity’s code looks like:

The map context is initialized by the previously created data source object and set this object as map context to the map view.

MapActivity.java

package com.example.navigenie; ...

import com.navigenie.sdk.NGUMapContext;

import com.navigenie.sdk.NGUMapView;

public class MapActivity extends Activity { ...

private NGUMapView mMapView = null; // Map view object // Called when the activity is first created.

@Override

public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState);

// Init data source ...

// Init map view with context mMapView = new NGUMapView(this);

NGUMapContext mapContext = new NGUMapContext(); mapContext.init(mDataSource);

mMapView.setMapContext(mapContext);

setContentView(mMapView); }

@Override

protected void onResume() { super.onResume(); mMapView.onResume();

}

@Override

protected void onPause() { mMapView.onPause();

super.onPause(); }

@Override

protected void onDestroy() { mMapView.onDestroy();

mDataSource.close(); super.onDestroy(); }

Change orientation

When user changes the orientation of the device, the activity is destroyed and created again. It makes the working of the application slower. One can handle this event manualy. In this case the activity is not released. For this behavior add the following line to the AndroidManifest.xml:

AndroidManifest.xml

<activity android:name=".MapActivity" android:label="@string/app_name"

android:configChanges="orientation|keyboardHidden"> ...

Set the map view

Next step is to initializing the map view. Set the visibility of POIs, set camera position and other camera properties and behaviors.

MapActivity.java ...

import com.navigenie.sdk.NGUPosition;

...

public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState);

// Init data source ...

// Init map view with context ...

// Set map properties

// Default is all POIs are visible. Switch them off. mMapView.setAllPoiVisibility(false);

// Show petrol stations (for valid POI IDs see data/im_init/pois.xml). mMapView.setPoiVisibility(5540, true);

// Set camera position.

mMapView.setCameraPosition(new NGUPosition(-0.1179, 51.5031));

// Set camera distance.

mMapView.setCameraDist(1000.0);

// Camera rotation is enabled. mMapView.setNorthLock(false);

// Zooming is enabled.

mMapView.setZoomEnabled(true);

setContentView(mMapView); }

...

Now we can test our map application. Start the application. Your first Navigenie based application is applicable for browsing on the map by touching on the screen.