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 Libraries. 4 NGApiDemos.. 5 NGUApiDemos.. 5 InstantMap 5 Supported platforms 5 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 Set the map view 13 2

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. 3

Package contents The table summarizes the contents of the developer package: Directory data NGAPI NGUtils platforms/android/doc platforms/android/lib platforms/android/tutorial/helloworld platforms/android/ngapidemos platforms/android/nguapidemos platforms/android/instantmap platforms/android/tutorial/navigenie_t utorial_android.pdf Description Contains the configuration files. SDK Include directory Utility classes API documentation (HTML format) NaviGenie SDK binaries The instantly buildable version of the tutorial application we ll describe in this document. Low level API demo API demo of the Utility classes. Navigation application which demos the Android Java API This document. Libraries The lib directory contains the following binary packages: Library NGBase (libngbase.a) MapFolderDatabase (libmapfolderdatabase.a), NGBuilder (libngbuilder.a), NGDataSource (libngdatasource.a), NGFormat(libNGFormat.a), NGEngine (libngengine.a) NGMap (libngmap.a, NGMapView.jar) NGMapSearch (libngmapsearch.a) NGRoute (libngroute.a) NGGeocode (libnggeocode.a) NGGpsFilter (libnggpsfilter.a) NGReverseGeocode (libngreversegeocode.a) NGUtils (libngutils.a) NGJUtils (libngjutils.so, NGJUtils.jar) Description Common base classes. 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. 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. Provides search services. Provides routing services, find directions between multiple waypoints. Provides geocoding services based on address hierarchy levels. Provides location handling services. Provides reverse geocoding services. Utility classes. Platform independent layer that wraps the low level API. Android Java API. 4

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. 5

Create an Android Java project Create a new project by selecting New -> Android project from the File menu. Figure 1. Create new project Figure 2. Set project name 6

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 package com.example.navigenie; import android.app.activity; import android.os.bundle; 7

public class MapActivity extends Activity { /** Called when the activity is first created. */ 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. 8

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"); Now we have a simple Activity which loads the required native libraries. 9

DataSource handling There are required permissions for authorization. These should be set in the manifest xml file. 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" /> 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) 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, 10

new OnAuthFinishedListener() { public void onauthfinished(nguauthresult result) { Log.d("helloWorld", "Authorization result: " + result.getauthstatustext()); ); setcontentview(r.layout.main); 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: Figure 7. Logcat showing the helloworld application log 11

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. 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); protected void onresume() { super.onresume(); mmapview.onresume(); protected void onpause() { mmapview.onpause(); super.onpause(); protected void ondestroy() { mmapview.ondestroy(); mdatasource.close(); super.ondestroy(); 12

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. 13

Figure 8. HelloWorld application screenshot 14