HERE SDK for Android Developer's Guide Hybrid Plus Version 2.1
Contents 2 Contents Legal Notices...5 Document Information... 6 Service Support... 7 Chapter1:Overview... 8 What is the HERE SDK for Android?...9 Feature List... 9 Chapter2:Quick Start... 12 Creating a Simple Application... 13 Extending the Application... 18 Adding Route Calculation... 22 Adding Extruded Buildings... 25 Adding LiveSight... 27 Adding a LiveSight Radar... 34 Chapter3:User Guide... 37 Authenticating Applications... 38 Obfuscating Applications...38 Embedding the Map Service... 39 Maps...39 Gestures... 46 Map Schemes... 50 MapEngine Class... 54 Objects and Interaction... 54 Transit... 66 Positioning... 77 MapActivity Class... 81
Contents 3 Offline Maps (MapLoader)... 82 Shared Map Resources... 84 Traffic Information... 84 Extruded Buildings... 87 3D Landmarks... 92 Custom Raster Tiles... 92 Specialized HERE Raster Tiles... 95 Venue Maps... 99 Places... 105 Geocoding and Reverse Geocoding... 105 Search and Discovery... 108 Custom Locations... 114 Directions... 117 Calculate routes... 118 Transit Routing... 123 Truck Routing... 124 Offline Routing... 126 Street-level... 126 Street-level Imagery... 126 Street-level Objects... 135 Turn-by-Turn Navigation... 139 Voice Instructions... 145 Traffic-aware Navigation... 149 LiveSight... 152 Starting and Stopping LiveSight... 154 Adding and Interacting with LiveSight Content... 155 Customizing LiveSight... 160 Chapter4:Supplemental Information...164 Creating a Simple HERE SDK Application in Android Studio... 165 Compatibility Fragments... 171 Size Management...171
Contents 4 Development Tips... 173 Chapter5:API Reference... 174
Legal Notices 5 Legal Notices 2014 HERE. All rights reserved. This material, including documentation and any related computer programs, is protected by copyright controlled by HERE. All rights are reserved. Copying, including reproducing, storing, adapting or translating, any or all of this material requires the prior written consent of HERE. This material also contains confidential information, which may not be disclosed to others without the prior written consent of HERE. Trademark Acknowledgements HERE and Nokia are trademarks or registered trademarks of Nokia Corporation in the United States and other countries. Other trade names are trademarks or registered trademarks of their owners. Disclaimer This content is provided "as-is" and without warranties of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, satisfactory quality and non-infringement. Nokia does not warrant that the content is error free and Nokia does not warrant or make any representations regarding the quality, correctness, accuracy, or reliability of the content. You should therefore verify any information contained in the content before acting on it. To the furthest extent permitted by law, under no circumstances, including without limitation Nokia's negligence, shall Nokia be liable for any damages, including, without limitation, direct, special, indirect, punitive, consequential, exemplary and/ or incidental damages that result from the use or application of this content, even if Nokia or an authorized representative has been advised of the possibility of such damages.
Document Information Document Information Product Name: HERE SDK for Android Version: Hybrid Plus Version 2.1 Document Name: Id: 63abd45-1417795824 Status: DRAFT Date: 2014-Dec-05, 16:13 (GMT) 6
Service Support Service Support If you need assistance with this or other HERE products, please contact your HERE representative or Technical Customer Support via email at tcsplatform@here.com. 7
Overview Chapter 1 Overview Topics: What is the HERE SDK for Android? The articles that follow introduce the HERE SDK for Android, explain essential concepts and describe the common features it Feature List supports. 8
Overview 9 What is the HERE SDK for Android? The HERE SDK for Android provides a set of programming interfaces that enable developers to build immersive, geographically-aware Android applications by leveraging a powerful and flexible mapping platform. Through this SDK, developers can add rich location features such as routing, interactive maps, and global place search to their applications. The powerful client-side HERE SDK for Android also includes a sophisticated engine for rendering map data and calculated routes. In addition to dynamically downloading map data, the SDK also supports offline maps using previously cached map data or downloaded map packages. Vector Maps The HERE SDK delivers vector-based map data, in contrast to most mapping SDKs that only provide APIs to display map data using raster tiles. With raster tiles, panning to a new location or moving to a new zoom level requires additional raster tiles must be downloaded, leading to a negative impact on application fluidity and the overall user experience. Vector map data used by the HERE SDK consists of many data layers that are rendered based on rules describing what to display and how to display it. This enables use cases typically not possible with raster tiles, such as: dynamically altering the look and style of the map (for example: changing to night mode) without downloading new map data zooming the map smoothly rather than in discrete zoom steps rotating the map while maintaining correct label and icon orientation tilting the map to show textured 3D landmarks Moreover, vector map data requires significantly less storage space than raster map tiles, enabling map data to be downloaded for offline use. The result is a powerful hybrid solution where map data can be downloaded over a wireless data connection as needed, or maps for countries and regions can be preloaded for later use, eliminating the need for an always-present wireless data connection. The HERE SDK uses vector data for all normal maps. Raster tiles are used when satellite, terrain, and custom maps are being displayed. Feature List The main features offered by the HERE SDK for Android are listed below:
Overview 10 Mapping Dynamically download vector maps for more than 190 countries in over 50 languages Preload maps for offline usage Map styles: normal street map, satellite map, transit map, and more Textured 3D landmarks Street level imagery Touch gestures (including pan, flick, pinch zoom, rotate, and tilt) Overlay objects on the map such as polylines, polygons, icons, and routes Overlay 3D map objects Overlay custom raster tiles on the map (for example, to display heat maps) Ability to render raster tiles and map objects interleaved within different map layers Venue maps Show real-time traffic flow and incidents 3D Extruded Buildings 3D Landmarks Transit object interaction Traffic object interaction Search Search through a broad set of geographical content, including 25 million streets, 200 million address points, and over 60 million categorized places across the globe Search for a specific place or explore by categories Get rich details for a Point of Interest (including images, ratings, reviews, and editorials) Perform geocoding and reverse geocoding lookups Offline places search, offline geocoding/reverse geocoding lookups Directions Get driving or pedestrian directions Public Transit directions for more than 950 cities in 44 countries Public Transit directions using online timetables for more than 400 cities Specify preferred route type (fastest/shortest) and attributes to avoid (toll roads, motorways, parks, and more) Alternate routes Offline route calculation Driving directions that take traffic into account Directions for commercial vehicles
Overview 11 Turn-by-turn Navigation: Online and offline turn-by-turn navigation Natural-sounding guidance instructions, such as "turn left at the gas station" and "at the next light, turn right" Audio or text-to-speech voices Approximate user coordinates to the nearest road or navigation route Approximate user tunnel position, even when there is no GPS signal Dynamic information including signposts, the driver's current street lane, and speed Realistic previews of certain junctions and lanes LiveSight: Track position of device in space and animate view accordingly Seamless transitions from Map to LiveSight and back again Gesture support allows the user to interact with content, custom gestures can also be defined Content transitions and interaction are animated using hardware acceleration "Radar" UI support, which provides the user with more context regarding their position relative to content Highly configurable LiveSight engine allows the user experience to be customized Other Features Custom Location search by using location attributes, proximity, area, or corridor radius Specialized raster tiles that show information for fleet vehicles and trucks Specialized raster tiles showing congestion toll zones and the typical traffic patterns for a given time of the week
Quick Start Chapter 2 Quick Start Topics: Creating a Simple Application Using the HERE SDK Extending the Simple Application Adding Route Calculation to the Simple Application Adding Tappable Extruded Buildings to the Simple Application Adding LiveSight Functionality to the Simple Application The articles in this section provide information to help you start using the HERE SDK for Android. 12
Quick Start 13 Creating a Simple Application Using the HERE SDK This tutorial provides instructions on how to create a simple application that uses the HERE SDK for Android to render a map on an Android device. With this application, users will be able to: Pan around the map to view different geographical regions Center the map on a specific part of the viewable area using standard Android single-tap gestures Zoom in and out using standard Android pinch-to-zoom, double-tap, or two-finger tap Rotate the map using standard Android two-finger rotate gestures Tilt the map using standard Android two-finger tilt gestures Note: This tutorial applies to Eclipse and Android Developer Tools. For information on how to perform the same tasks in Android Studio, refer to Creating a Simple HERE SDK Application in Android Studio on page 165. Development tasks for this basic application include: Create a new Eclipse project Add necessary resources, permissions and map fragment(s) to the project properties and application manifest Acquire credentials from HERE for accessing map services Initialize the map fragment such that a map instance is created and associated with the map fragment for rendering on the client device Note: The HERE Map Service must be embedded with the application. For more information on this requirement, see Embedding the Map Service on page 39. Create a New Eclipse Project The first stage of developing an application using the HERE SDK is to create a new project in Eclipse as follows: 1. From the Eclipse File menu, select New> Android Application Project to open the New Android App dialog (or click from the toolbar) 2. In the New Android Application dialogue, under Application Name, specify an appropriate application name (The remainder of this tutorial will refer the application name as HelloHEREMaps) 3. Under Project Name, specify an appropriate project name
Quick Start 14 4. Under Package Name, specify an appropriate package name (For example, com.mapstutorial.helloheremaps. This is the package name that this tutorial will use) 5. Under Minimum Required SDK, select the lowest version of the Android SDK you wish to support. For this sample application, we will use Android 4.0 6. Under Target SDK, select your target Android SDK version with API level 14 (Ice Cream Sandwich 4.0.1) or above 7. Click Next 8. Click Next to use the default icons 9. On the Create Activity dialog box, select Blank Activity and click Next 10. Click Finish Result: A new project will appear within the Eclipse Package Explorer, which will expand to show the location of the activity_main.xml file. The file itself will be opened in the main editor view, in Graphical Layout mode for adding and editing UI elements. Add HERE SDK Libraries to Your Project After creating the skeleton of your new application, add the HERE SDK resources as follows: 1. From the directory where you installed the HERE SDK, copy the contents of the HERE-sdk/libs/ folder, except HERE-sdk-javadoc.jar, to your project's libs/ folder. 2. In your Eclipse project's libs/ folder, right-click the HERE-sdk.jar file and select Build Path> Add to Build Path. 3. Optional: If you plan on extending this application with HERE Places functionality, add the googlegson library (release 2.2.4 or a compatible version) into your project. One way to do this is to download the google-gson-*-release.zip file from https://code.google.com/p/googlegson/, unzip the ZIP archive, and copy the gson-*.jar (not gson-*-sources.jar or gson*-javadoc.jar) into your project libs/ folder, then right-click on it in Eclipse, and select Build Path> Add to Build Path. The google-gson library is required for all HERE Places operations. For more information on using HERE Places, please see Places on page 105. Result: Your project will be able to make use of APIs from the HERE SDK. Note: Performing these steps should also link Javadoc files to the SDK library. If Javadoc does not appear in Eclipse, please close and re-open your Eclipse project. If you would like to change the location of the docs folder, update thehere-sdk.jar.properties file in the libs folder to match the docs folder location. Edit AndroidManifest.xml With resources added to your project, the next stage of creating an application with the HERE SDK is to edit the project's AndroidManifest.xml file to specify Android permissions as follows: 1. From the Package Explorer, double-click your project's AndroidManifest.xml file to open it for editing.
Quick Start 15 2. At the bottom of the editor view that displays the manifest, click the AndroidManifest.xml tab to switch the file's view to text editor mode. 3. Add the following markup beneath the <uses-sdk/> tag: <uses-permission android:name="android.permission.access_fine_location"/> <uses-permission android:name="android.permission.write_external_storage"/> <uses-permission android:name="android.permission.access_network_state"/> <uses-permission android:name="android.permission.change_network_state"/> <uses-permission android:name="android.permission.internet"/> <uses-permission android:name="android.permission.access_wifi_state"/> 4. Within the <application></application> block of tags, add the following markup directly beneath the <activity></activity> tag: <meta-data android:name="com.here.android.maps.appid" android:value="your APP ID"/> <meta-data android:name="com.here.android.maps.apptoken" android:value="your APP CODE"/> 5. Replace the YOUR APP ID and YOUR APP CODE strings with appropriate credentials for your application, which you can acquire by contacting your HERE account representative. Note: All users of the HERE SDK are required to register for a HERE App_Id and App_Code, and to specify those values in their Android manifest XML file. Failure to do so will result in blocked access to certain features and could lead to degradation in the quality of other services. 6. Within the same <application></application> section in your AndroidManifest.xml file, add the following lines: <service android:name="com.here.android.mpa.service.mapservice" android:label="heremapservice" android:process="global.here.map.service.v2" android:exported="true" > <intent-filter> <action android:name="com.here.android.mpa.service.mapservice" > </action> </intent-filter> </service> Result: Your application is now configured to use the minimum Android device permissions that are required by HERE Maps
Quick Start 16 Edit activity_main.xml Along with permissions and credentials, you must add an Android <fragment /> tag to set up the map fragment that your application activity will be associated with. In this section, we will display a text label (generated as part of the default new application) and a map right below label as follows: 1. From the Package Explorer, under the res/layout/ folder of your project, double-click the activity_main.xml file to open it for editing. 2. At the bottom of the editor view that displays the layout for MainActivity, click the activity_main.xml tab to switch the file's view to text editor mode. 3. Ensure that the XML file has <LinearLayout></LinearLayout> as its root element. Depending on your version of Eclipse, this may be a RelativeLayout instead. If that is the case, replace the contents of the file with the following: <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools" android:layout_width="fill_parent" android:layout_height="fill_parent" android:orientation="vertical" > <TextView android:id="@+id/title" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="@string/hello_world" tools:context=".mainactivity" /> </LinearLayout> 4. Add the following markup beneath the <TextView/> tag: <!-- Map Fragment embedded with the map object --> <fragment class="com.here.android.mpa.mapping.mapfragment" android:id="@+id/mapfragment" android:layout_width="match_parent" android:layout_height="match_parent"/> Result: When MapFragment is initialized, your application's MainActivity will contain a MapFragment UI element (with the ID mapfragment) that owns a Map object. Initializing the Map Fragment When you have defined the basic layout of the application and acquired necessary permissions, the final step is to initialize the instance of the MapFragment class, thus creating and associating a Map with the MapFragment declared in the activity_main.xml file: From the Package Explorer, under the src/ folder of your project, double-click the MainActivity.java file to open it for editing.
Quick Start 17 Revise the import statements and functional logic of the MainActivity to look like the following: package com.mapstutorial.helloheremaps; import android.app.activity; import android.os.bundle; import import import import com.here.android.mpa.common.geocoordinate; com.here.android.mpa.common.onengineinitlistener; com.here.android.mpa.mapping.map; com.here.android.mpa.mapping.mapfragment; public class MainActivity extends Activity { // map embedded in the map fragment private Map map = null; // map fragment embedded in this activity private MapFragment mapfragment = null; @Override public void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); setcontentview(r.layout.activity_main); // Search for the map fragment to finish setup by calling init(). mapfragment = (MapFragment)getFragmentManager().findFragmentById( R.id.mapfragment); mapfragment.init(new OnEngineInitListener() { @Override public void onengineinitializationcompleted( OnEngineInitListener.Error error) { if (error == OnEngineInitListener.Error.NONE) { // retrieve a reference of the map from the map fragment map = mapfragment.getmap(); // Set the map center to the Vancouver region (no animation) map.setcenter(new GeoCoordinate(49.196261, -123.004773, 0.0), Map.Animation.NONE); // Set the zoom level to the average between min and max map.setzoomlevel( (map.getmaxzoomlevel() + map.getminzoomlevel()) / 2); else { System.out.println("ERROR: Cannot initialize Map Fragment"); ); Result: You can run your simple application by pressing the key combination Ctrl + F11 from within Eclipse (if prompted, run the project as an "Android Application"). The application will render a map retrieved from the HERE servers. When you are running your application on a device, make sure a dataconnection is enabled. See folder BasicMapSolution for a completed example. You will need to add your own App_Id and App_Code for this completed example to work.
Quick Start 18 Extending the Simple Application Beyond creating a basic application, you can extend your application with the use of features from the HERE SDK for Android. This tutorial introduces methods to change map attributes such as map center, tilt angle, orientation, daytime/nighttime map schemes, and zoom levels. Getting Started You can import the Android project from the BasicMapSolution folder as a starting point for this exercise. (Please note that MainActivity is changed to BasicMapActivity in this version of the project.) Note: The tasks presented on this page assume that you gave the name "HelloHEREMaps" to your Eclipse project and the name com.mapstutorial.helloheremaps to your application package. Add a "Go Home" Button This task introduces the following HERE SDK for Android class methods: com.here.android.mpa.mapping.map.setorientation() com.here.android.mpa.mapping.map.settilt() Within a map-based application, users can pan around the map to different regions, zoom in and out, even rotate or tilt the map itself. A user-friendly app might, in turn, offer users a UI element that allows them to reset the initial map view. Add a "Go Home" Button element to the HelloHEREMaps application as follows: 1. From the Package Explorer, double-click the HelloHEREMaps/res/values/strings.xml file to open it for editing. 2. At the bottom of the editor view that displays the string resources, click the strings.xml tab to switch the file's view to text editor mode. 3. Add the following line to the group of <string></string> tags: <string name="label_button_gohome">go Home</string> 4. From the Package Explorer, double-click the HelloHEREMaps/res/layout/activity_main.xml file to open it for editing.
Quick Start 5. 19 Add the following markup directly above the <fragment /> tag: <!-- UI element declaration for "Go Home" button --> <android.widget.button android:id="@+id/homebutton" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="@string/label_button_gohome" android:onclick="gohome" /> 6. From the Package Explorer, double-click the HelloHEREMaps/src/ com.mapstutorial.helloheremaps/mainactivity.java file to open it for editing. 7. Add the following lines to the import statements near the top of the source file: import android.view.view; import java.util.list; 8. Add the following method to the end of the class: // Functionality for taps of the "Go Home" button public void gohome(view view) { if (map!= null) { // Change map view to "home" coordinate and zoom level, plus // eliminate any rotation or tilt map.setcenter(new GeoCoordinate(49.196261, -123.004773, 0.0), Map.Animation.NONE); map.setzoomlevel((map.getmaxzoomlevel() + map.getminzoomlevel()) / 2); map.setorientation(0); map.settilt(0); // Reset the map scheme to the initial scheme map.setmapscheme(initial_scheme); 9. Press the key combination Ctrl + F11 within Eclipse to run this extended basic HERE SDK for Android application. Result: Your HERE SDK for Android application displays a map centered initially on the Vancouver municipal region, plus a "Go Home" button near the top-left corner that allows users to reset the map to its initial view. Add a "Change Map Scheme" Button This task introduces the following HERE SDK for Android class methods: com.here.android.mpa.mapping.map.getmapscheme() com.here.android.mpa.mapping.map.getmapschemes() com.here.android.mpa.mapping.map.setmapscheme()
Quick Start 20 There are numerous map schemes available from HERE SDK for Android. You can add a UI element to your application that allows users to change the scheme of the map they are viewing. Add a "Change Map Scheme" Button element to the HelloHEREMaps application as follows: 1. From the Package Explorer, double-click the HelloHEREMaps/res/values/strings.xml file to open it for editing. 2. Add the following lines to the group of <string></string> tags: <string name="label_button_changescheme">change Map Scheme</string> 3. From the Package Explorer, double-click the HelloHEREMaps/res/layout/activity_main.xml file to open it for editing. 4. Add the following markup directly beneath the homebutton tag but above the <fragment /> tag: <!-- UI element declaration for "Change Map Scheme" button --> <android.widget.button android:id="@+id/schemebutton" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="@string/label_button_changescheme" android:onclick="changescheme" /> 5. From the Package Explorer, double-click the HelloHEREMaps/src/ com.mapstutorial.helloheremaps/mainactivity.java file to open it for editing. 6. Add the following to the import statements near the top of the source file: import java.util.list; 7. Add variable declarations for initial_scheme to the top of the MainActivity class, immediately beneath the declaration for map, as follows: public class MainActivity extends Activity { // map embedded in the map fragment private Map map = null; // map fragment embedded in this activity private MapFragment mapfragment = null; // Initial map scheme, initialized in oncreate() and accessed in gohome() private static String initial_scheme = ""; @Override public void oncreate(bundle savedinstancestate) {...
Quick Start 8. 21 Create function private void onmapfragmentinitializationcompleted() and move all the existing text within OnEngineInitListener's onengineinitializationcompleted() into it: private void onmapfragmentinitializationcompleted() { // retrieve a reference of the map from the map fragment map = mapfragment.getmap(); // Set the map center coordinate to the Vancouver region (no animation) map.setcenter(new GeoCoordinate(49.196261, -123.004773, 0.0), Map.Animation.NONE); // Set the map zoom level to the average between min and max (no // animation) map.setzoomlevel((map.getmaxzoomlevel() + map.getminzoomlevel()) / 2); 9. Update the OnEngineInitListener's onengineinitializationcompleted() implementation as follows: mapfragment.init(new OnEngineInitListener() { @Override public void onengineinitializationcompleted(onengineinitlistener.error error) { if (error == OnEngineInitListener.Error.NONE) { onmapfragmentinitializationcompleted();... 10. Add the following method to the end of the class: // Functionality for taps of the "Change Map Scheme" button public void changescheme(view view) { if (map!= null) { // Local variable representing the current map scheme String current = map.getmapscheme(); // Local array containing string values of available map schemes List<String> schemes = map.getmapschemes(); // Local variable representing the number of available map schemes int total = map.getmapschemes().size(); if (initial_scheme.isempty()) { //save the initial scheme initial_scheme = current; // If the current scheme is the last element in the array, reset to // the scheme at array index 0 if (schemes.get(total - 1).equals(current)) map.setmapscheme(schemes.get(0)); else { // If the current scheme is any other element, set to the next // scheme in the array for (int count = 0; count < total - 1; count++) { if (schemes.get(count).equals(current)) map.setmapscheme(schemes.get(count + 1));
Quick Start 22 11. To ensure that a tap of the "Go Home" button resets the map scheme while it is resetting everything else (coordinates, zoom level, etc.), add the following lines to the end of the gohome() method: // Reset the map scheme to the initial scheme if (!initial_scheme.isempty()) { map.setmapscheme(initial_scheme); 12. Press the key combination Ctrl + F11 within Eclipse to run this extended basic HERE SDK for Android application. Result: Your HERE SDK for Android application displays a map centered initially on the Vancouver municipal region, plus a "Go Home" button near the top-left corner that allows users to reset the map to its initial view, followed by a "Change Map Scheme" button that allows users to cycle through available map schemes. See folder ExtendedBasicMapSolution for a completed example. You will need to add your own App_Id and App_Code for this completed example to work. Adding Route Calculation to the Simple Application An important feature of many map-based applications is offering directions to users by calculating a route that can be rendered on the map. This tutorial lesson introduces the addition of such functionality to applications developed using the HERE SDK for Android. Getting Started You can import the Android project from the BasicMapSolution folder as a starting point for this exercise. (Please note that MainActivity is changed to BasicMapActivity in this version of the project.) Note: The tasks presented on this page assume that you gave the name "HelloHEREMaps" to your Eclipse project and the name com.mapstutorial.helloheremaps to your application package. Add a "Get Directions" Button Add a "Get Directions" Button element to the HelloHEREMaps application as follows: 1. From the Package Explorer, double-click the HelloHEREMaps/res/values/strings.xml file to open it for editing.
Quick Start 2. 23 Add the following lines to the existing group of strings <string name="label_button_getdirections"> Get Directions </string> <string name="textview_routecoordinates_2waypoints"> Press "Get Directions" button to calculate a route:\nstart: Nokia, Burnaby\nEnd: Airport, YVR </string> 3. From the Package Explorer, double-click the HelloHEREMaps/res/layout/activity_main.xml file to open it for editing. 4. Add the following markup directly beneath the LinearLayout tag: <!-- UI element declaration for "Get Directions" button --> <android.widget.button android:id="@+id/directionsbutton" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="@string/label_button_getdirections" android:onclick="getdirections" /> 5. Next, change the <TextView/> tag to the following: <TextView android:id="@+id/title" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="@string/textview_routecoordinates_2waypoints" tools:context=".mainactivity" /> 6. From the Package Explorer, double-click the HelloHEREMaps/src/ com.mapstutorial.helloheremaps/mainactivity.java file to open it for editing. 7. Add the following lines to the import statements near the top of the source file: import import import import import import import import import import 8. java.util.enumset; java.util.list; android.view.view; android.widget.textview; com.here.android.mpa.common.geoboundingbox; com.here.android.mpa.mapping.maproute; com.here.android.mpa.routing.routemanager; com.here.android.mpa.routing.routeoptions; com.here.android.mpa.routing.routeplan; com.here.android.mpa.routing.routeresult; Add the declaration of these private member variables above the oncreate function: // TextView for displaying the current map scheme private TextView textviewresult = null; // MapRoute for this activity private MapRoute maproute = null;
Quick Start 24 and to set up the member variables for use later, add these lines at the end of the oncreate function: textviewresult = (TextView) findviewbyid(r.id.title); textviewresult.settext(r.string.textview_routecoordinates_2waypoints); 9. Add code to handle the click of the "Get Directions" button at the end of the class: First, create an implementation of the RouteManagerEventListener: private RouteManager.Listener routemanagerlistener = new RouteManager.Listener() { public void oncalculateroutefinished(routemanager.error errorcode, List<RouteResult> result) { if (errorcode == RouteManager.Error.NONE && result.get(0).getroute()!= null) { // create a map route object and place it on the map maproute = new MapRoute(result.get(0).getRoute()); map.addmapobject(maproute); // Get the bounding box containing the route and zoom in GeoBoundingBox gbb = result.get(0).getroute().getboundingbox(); map.zoomto(gbb, Map.Animation.NONE, Map.MOVE_PRESERVE_ORIENTATION); textviewresult.settext( String.format("Route calculated with %d maneuvers.", result.get(0).getroute().getmaneuvers().size())); else { textviewresult.settext( String.format("Route calculation failed: %s", errorcode.tostring())); public void onprogress(int percentage) { textviewresult.settext( String.format("... %d percent done...", percentage)); ; Next, add the implementation of getdirections() below: // Functionality for taps of the "Get Directions" button public void getdirections(view view) { // 1. clear previous results textviewresult.settext(""); if (map!= null && maproute!= null) { map.removemapobject(maproute); maproute = null; // 2. Initialize RouteManager RouteManager routemanager = RouteManager.getInstance(); // 3. Select routing options via RoutingMode RoutePlan routeplan = new RoutePlan(); RouteOptions routeoptions = new RouteOptions(); routeoptions.settransportmode(routeoptions.transportmode.car); routeoptions.setroutetype(routeoptions.type.fastest); routeplan.setrouteoptions(routeoptions);
Quick Start 25 // 4. Select Waypoints for your routes // START: Nokia, Burnaby routeplan.addwaypoint(new GeoCoordinate(49.1966286, -123.0053635)); // END: Airport, YVR routeplan.addwaypoint(new GeoCoordinate(49.1947289, -123.1762924)); // 5. Retrieve Routing information via RouteManagerListener routemanager.calculateroute(routeplan, routemanagerlistener); ; 10. Save all files in the HelloHEREMaps project by selecting File> Save All or by pressing the key combination Shift + Ctrl + S (within Eclipse). 11. Press the key combination Ctrl + F11 within Eclipse to run this HERE SDK for Android application with route calculation functionality. Result: your HERE SDK for Android application displays a map centered initially on the Vancouver municipal region, with a "Get Directions" button and a text box reflecting current status. Tapping on the button will trigger a route calculation for the hard-coded set of waypoints between Burnaby and Airport, YVR and render, and have the route displayed on map if successful. See the SimpleRoutingSolution folder for a completed example. You will need to add your own App_Id and App_Code for this completed example to work.) Adding Tappable Extruded Buildings to the Simple Application Another way to add a level of immersion and interactivity to your application is to use the Extruded Buildings feature. This tutorial provides instructions on displaying extruded buildings in your app, as well as adding logic to allow users to tap on a building in order to highlight it in a blue color. Getting Started You can import the Android project from the BasicMapSolution folder as a starting point for this exercise. (Please note that MainActivity is changed to BasicMapActivity in this version of the project.) Note: The tasks presented on this page assume that you gave the name "HelloHEREMaps" to your Eclipse project and the name com.mapstutorial.helloheremaps to your application package.
Quick Start 26 Modify MainActivity to Show Extruded Buildings You can modify the MapFragment in MainActivity to show extruded buildings by performing the following steps: 1. From the Package Explorer, double-click the HelloHEREMaps/src/ com.mapstutorial.helloheremaps/mainactivity.java file to open it for editing. 2. Add the following lines to the import statements near the top of the source file: import import import import import import import import import import 3. java.util.enumset; java.util.list; android.graphics.color; android.view.menu; com.here.android.mpa.common.viewobject; com.here.android.mpa.mapping.map; com.here.android.mpa.mapping.mapbuildinggroup; com.here.android.mpa.mapping.mapbuildingobject; com.here.android.mpa.mapping.mapfragment; com.here.android.mpa.mapping.mapgesture; Replace the call to mapfragment.init() with the following: mapfragment.init(new OnEngineInitListener() { @Override public void onengineinitializationcompleted(onengineinitlistener.error error) { if (error == OnEngineInitListener.Error.NONE) { // retrieve a reference of the map from the map fragment map = mapfragment.getmap(); // Set the map center coordinate to the San Francisco region (no animation) map.setcenter(new GeoCoordinate(37.77493, -122.419416, 0.0), Map.Animation.NONE); // Set the map zoom level to close to street level map.setzoomlevel(18); else { System.out.println("ERROR: Cannot initialize Map Fragment"); ); 4. Save all files in the HelloHEREMaps project by selecting File> Save All or by pressing the key combination Shift + Ctrl + S (within Eclipse). 5. Press the Ctrl + F11 key combination within Eclipse to run this HERE SDK for Android application. Inspect that the app shows a map of San Francisco with visible extruded buildings. 6. In Eclipse, add the buildinggroup private member variable above the oncreate function: private MapBuildingGroup buildinggroup = null; 7. Add an OnGestureListener to this class: private MapGesture.OnGestureListener gesturelistener = new MapGesture.OnGestureListener.OnGestureListenerAdapter() { @Override public boolean onmapobjectsselected(list<viewobject> objects) { for (ViewObject vo : objects) { if (vo instanceof MapBuildingObject) {
Quick Start 27 // Remove currently selected building buildinggroup.removeallbuildings(); // Add this building to the group. // This will highlight the building. MapBuildingObject building = (MapBuildingObject) vo; buildinggroup.addbuilding(building.getidentifier()); return false; ; 8. Add the following lines to the end of onfragmentinitializationcompleted() within the if condition block to create a building group so that when the user taps on a building, building is added to this group: // Create a custom building group buildinggroup = map.getmapbuildinglayer().createnewbuildinggroup(); // Set the buildinggroup's color to "blue" buildinggroup.setcolor(color.blue, EnumSet.allOf(MapBuildingGroup.BuildingFace.class)); // Listen for gesture events. For example tapping on buildings mapfragment.getmapgesture().addongesturelistener(gesturelistener); 9. Press the Ctrl + F11 key combination within Eclipse to run this HERE SDK for Android application tappable buildings. Result: your HERE SDK for Android application displays a map centered initially on the San Francisco municipal region. Tapping on a building will cause the building to turn blue. See folder ExtrudedMapSolution for a completed example. You will need to add your own App_Id and App_Code for this completed example to work. Adding LiveSight Functionality to the Simple Application This tutorial introduces the addition of LiveSight functionality to applications developed using the HERE SDK for Android. It covers several basic use cases including transitioning from Map to LiveSight mode and adding and removing LiveSight objects. By adding LiveSight functionality to your application, you can create new and unique user experiences which utilize the real world as an interface.
Quick Start 28 Getting Started You can import the Android project from the BasicMapSolution folder as a starting point for this exercise. (Please note that MainActivity is changed to BasicMapActivity in this version of the project.) Note: The tasks presented on this page assume that you gave the name "HelloHEREMaps" to your Eclipse project and the name com.mapstutorial.helloheremaps to your application package. Update the AndroidManifest.xml with New Permissions LiveSight makes use of the devices camera. As a result of this, the camera permission needs to be added to the AndroidManifest.xml for LiveSight to work. Additionally, this tutorial makes use of setalternativecenter(). When using this method, the mock location permission is required, but this is optional and not required for LiveSight to function. 1. From the Package Explorer, double-click the HelloHEREMaps/AndroidManifest.xml file to open it for editing. 2. Add the following permissions: <uses-permission android:name="android.permission.access_mock_location" /> <uses-permission android:name="android.permission.camera" /> Add "Start LiveSight", "Stop LiveSight" and "Add Object" Buttons This task introduces the following HERE SDK for Android class methods: com.here.android.mpa.ar.compositefragment.getarcontroller() com.here.android.mpa.ar.arcontroller.start() com.here.android.mpa.ar.arcontroller.stop() com.here.android.mpa.ar.arcontroller.setusedowniconsonmap() com.here.android.mpa.ar.arcontroller.setalternativecenter() com.here.android.mpa.ar.arcontroller.addarobject() com.here.android.mpa.ar.arcontroller.removearobject() com.here.android.mpa.ar.ariconobject() Add the "Start LiveSight", "Stop LiveSight" and "Add Object" Buttons to the HelloHEREMaps application as follows: 1. From the Package Explorer, double-click the HelloHEREMaps/res/values/strings.xml file to open it for editing.
Quick Start 29 2. At the bottom of the editor view that displays the string resources, click the strings.xml tab to switch the file's view to text editor mode. 3. Add the following line to the group of <string></string> tags: <string name="label_button_stoplivesight">stop LiveSight</string> <string name="label_button_startlivesight">start LiveSight</string> <string name="label_button_addobject">add Object</string> 4. From the Package Explorer, double-click the HelloHEREMaps/res/layout/activity_main.xml file to open it for editing. 5. Change the Layout type from a LinearLayout to a RelativeLayout to better accommodate our desired UI: <LinearLayout>... </LinearLayout> becomes <RelativeLayout>... </RelativeLayout> 6. Now, change the Fragment type from a MapFragment to a CompositeFragment. The CompositeFragment allows us to seamlessly switch between Map mode and LiveSight mode, whereas the MapFragment only provides Map functionality: <fragment class="com.here.android.mpa.mapping.mapfragment" android:id="@+id/mapfragment"... becomes <fragment class="com.here.android.mpa.ar.compositefragment" android:id="@+id/compositefragment"... 7. Next, add the buttons to the layout. Add the following markup below the <fragment /> tag: <Button android:id="@+id/startlivesight" android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_alignparentbottom="true" android:layout_alignparentleft="true" android:onclick="startlivesight" android:text="@string/label_button_startlivesight" /> <Button android:id="@+id/stoplivesight"
Quick Start 30 android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_alignparentbottom="true" android:layout_alignparentright="true" android:onclick="stoplivesight" android:text="@string/label_button_stoplivesight" android:visibility="gone" /> <Button android:id="@+id/toggleobject" android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_alignparentleft="true" android:layout_alignparenttop="true" android:onclick="toggleobject" android:text="@string/label_button_addobject" /> 8. From the Package Explorer, double-click the HelloHEREMaps/src/ com.mapstutorial.helloheremaps/mainactivity.java file to open it for editing. 9. Add the following lines to the import statements near the top of the source file: import java.io.ioexception; import android.view.view; import android.widget.button; import android.widget.toast; import import import import import com.here.android.mpa.ar.arcontroller; com.here.android.mpa.ar.arcontroller.error; com.here.android.mpa.ar.ariconobject; com.here.android.mpa.ar.compositefragment; com.here.android.mpa.common.image; 10. Remove the "import com.here.android.mpa.mapping.mapfragment" import statement. 11. Find and replace all instances of "MapFragment" with "CompositeFragment" and "mapfragment" with "compositefragment" 12. Add the following member variables near the top of the class: // ARController is a facade for controlling LiveSight behavior private ARController arcontroller; // buttons which will allow the user to start LiveSight and add objects private Button startbutton; private Button stopbutton; private Button toggleobjectbutton; // the image we will display in LiveSight private Image image; // ARIconObject represents the image model which LiveSight accepts for display private ARIconObject ariconobject;
Quick Start 31 private boolean objectadded; 13. Modify the "oncreate()" method as follows: @Override public void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); setcontentview(r.layout.activity_main); // Search for the composite fragment to finish setup by calling init(). compositefragment = (CompositeFragment) getfragmentmanager().findfragmentbyid( R.id.compositefragment); compositefragment.init(new OnEngineInitListener() { @Override public void onengineinitializationcompleted( OnEngineInitListener.Error error) { if (error == OnEngineInitListener.Error.NONE) { // retrieve a reference of the map from the composite fragment map = compositefragment.getmap(); // Set the map center to the Vancouver Downtown region map.setcenter(new GeoCoordinate(49.279483, -123.116906, 0.0), Map.Animation.NONE); // Set the map zoom level to the average between min and max map.setzoomlevel((map.getmaxzoomlevel() + map.getminzoomlevel()) / 2); // LiveSight setup should be done after fragment init is complete setuplivesight(); else { System.out.println("ERROR: Cannot initialize Composite Fragment"); ); // hold references to the buttons for future use startbutton = (Button) findviewbyid(r.id.startlivesight); stopbutton = (Button) findviewbyid(r.id.stoplivesight); toggleobjectbutton = (Button) findviewbyid(r.id.toggleobject); 14. Add the following methods to the end of the class: private void setuplivesight() { // ARController should not be used until fragment init has completed arcontroller = compositefragment.getarcontroller(); // tells LiveSight to display icons while viewing the map (pitch down) arcontroller.setusedowniconsonmap(true);
Quick Start 32 // tells LiveSight to use a static mock location instead of the devices GPS fix arcontroller.setalternativecenter(new GeoCoordinate(49.279483, -123.116906, 0.0)); public void startlivesight(view view) { if (arcontroller!= null) { // triggers the transition from Map mode to LiveSight mode Error error = arcontroller.start(); if (error == Error.NONE) { startbutton.setvisibility(view.gone); stopbutton.setvisibility(view.visible); else { Toast.makeText(getApplicationContext(), "Error starting LiveSight: " + error.tostring(), Toast.LENGTH_LONG); public void stoplivesight(view view) { if (arcontroller!= null) { // exits LiveSight mode and returns to Map mode Error error = arcontroller.stop(true); if (error == Error.NONE) { startbutton.setvisibility(view.visible); stopbutton.setvisibility(view.gone); else { Toast.makeText(getApplicationContext(), "Error stopping LiveSight: " + error.tostring(), Toast.LENGTH_LONG); public void toggleobject(view view) { if (arcontroller!= null) { if (!objectadded) { if (ariconobject == null) { image = new com.here.android.mpa.common.image(); try { image.setimageresource(r.drawable.icon); catch (IOException e) { e.printstacktrace(); // creates a new icon object which uses the same image in up and down views ariconobject = new ARIconObject(new GeoCoordinate(49.276744, -123.112049, 2.0), (View) null, image);
Quick Start 33 // adds the icon object to LiveSight to be rendered arcontroller.addarobject(ariconobject); objectadded = true; toggleobjectbutton.settext("remove Object"); else { // removes the icon object from LiveSight, it will no longer be rendered arcontroller.removearobject(ariconobject); objectadded = false; toggleobjectbutton.settext("add Object"); Result: Your HERE SDK for Android application displays a map centered initially on the Downtown Vancouver municipal region, with a "Start LiveSight" button near the bottom-left corner that allows users to start LiveSight. Also, there is an "Add Object" button in the top-left hand corner which allows users to add an object to be viewed in LiveSight mode. See folder LiveSightSolution for a completed example. You will need to add your own App_Id and App_Code for this completed example to work.
Quick Start 34 Adding a Radar to the LiveSight Sample Application The HERE SDK provides LiveSight APIs that allow for you to add "radar" information about the augmented reality surroundings. For example, you can retrieve a list of all LiveSight objects and draw them in a mini-map. Figure 1: LiveSightRadarSolution A sample project that demonstrates this LiveSight radar functionality can be found in the tutorial/ LiveSightRadarSolution folder. In this example (which is based on the LiveSightSolution sample project), a resolution-independent radar widget is drawn at the top right corner of the Camera View. This radar widget contains a North-direction indicator and a gray area that represents the current cone of vision. When the user moves the LiveSight Camera View by moving their device, this radar widget is also updated immediately. The user can tap on the "Add Objects" button to add LiveSight objects onto the Camera View, and these objects will then show up as white dots on the radar widget. The following sections of this tutorial highlight a few key areas in this sample project.
Quick Start 35 LiveSightRadarActivity.java A key section in the LiveSightRadarActivity class is the setuplivesight() method. This method contains a call to arcontroller.addonradarupdatelistener(onradarupdate). ARController.OnRadarUpdateListener contains a single callback method, onradarupdate(), which is triggered continuously while LiveSight is enabled. This callback provides a populated ARRadarProperties object that you can use to retrieve radar-related information in order to update the radar widget. // Radar logic private ARController.OnRadarUpdateListener onradarupdate = new ARController.OnRadarUpdateListener() { @Override public void onradarupdate(arradarproperties radar) { if (m_radar!= null && radar!= null) { m_radar.update(radar); ; ARRadar.java The ARRadar class is responsible for drawing the radar widget. The radar widget is comprised of a few components, including: a semi-transparent black circle a border the letter "N" a black background surrounding the letter "N" a green circle, indicating the user a border around the user circle a light gray sector, indicating the current cone-of-vision optional white dots, indicating LiveSight objects Most of the ARRadar class contains logic to draw the radar widget. However, the UpdateRadarDots(ARRadarProperties) method also contains a few calls to read information from the ARRadarProperties object, including the list of ARRadarItem used for the white dots. Please note that the ARRadarProperties.getDimmingLimit() method returns a distance for calculating the distance where objects are too close for your current cone of vision. When objects are