Tutorial 1 — Hello World Map

Build the simplest possible Android application

---

NOTE: All of these tutorials assume you will be using an actual hardware device, not the Android device emulator. It is possible to use the Android device emulator, but you must enable use of the computer’s GPU in the emulator settings and we have found this path to be time consuming. If at all possible, test on an actual hardware device.

In this tutorial we will build the simplest possible Android application that uses the Altus Mapping Engine to display satellite imagery for the entire planet Earth. Just follow along and you’ll be up and running in no time. In this tutorial, we intentionally walk through everything step-by-step. In future tutorials we’ll move at a faster pace.

If you get stuck, you can view all of the code for this tutorial here: https://github.com/ba3llc/AltusMappingEngineAndroid/tree/master/HelloWorldMap.

Step 1 - Create a new Android Application

Start the Android ADT and create a new Android application project by selecting File / New / Android Application Project:

You will be prompted to supply some attributes about your project. Choose the same ones as shown below:

Click Next several times and accept the defaults for everything else until the Finish button is enabled. Then, click the Finish button.

You should see something like this:

Step 2 - Add Altus Mapping Engine files

In a file explorer, locate your new application’s libs folder:

Note that it contains only 1 file, android-support-v4.jar.

Copy and paste the files from the AltusAndroid.zip file into this libs folder such that it now looks like this:

This adds:

altusmappingengine.jar and commons-io-2.4.jar to the libs folder, and it adds a sub-folder, armbeabi-v7a with libAltusMappingEngine.so in it.

Now, back in the ADT, right click on the libs folder and refresh it:

You should now see the newly added libraries in your project:

If you don’t see the files laid out like this, then go back and work through this step again.

Step 3 - Add a MapView

Modify the text view of activity_main.xml to look like this:

Now, plug in your favorite Android device (it should have developer mode enabled and you should have turned on USB-debugging) and then click the debug button which looks like this:

You will be prompted with a dialog something like this when you do this the first time:

Choose “Android Application” and click OK.

After a few moments, you should see your HelloWorldMap application running on your device. It should look something like this:

You should be able to pan and zoom around this grid-covered sphere. The next step is to cover the sphere with a map. Many different types of maps are possible with the Altus Mapping Engine. For this tutorial we will use satellite imagery.

Step 4 - Display a Map

Find and open MainActivity.java. It’ll be somewhere in your src folder under com.example.helloworldmap.

Modify it to look like this:

Now, this next bit is very critical. You need to make Android aware that your application will want internet access. This is so it can download files for the internet map. The simplest way to do this is to find and edit the text of AndroidManifest.xml and add this line:

It should look something like this:

Now, debug your application again, and you should see something like this on your device:

Feel free to explore the planet by panning and zooming ...

Step 5 - Supporting Device Rotation

There’s one final bit of housekeeping to do if you want to make your map a little more polished: support rotating the device. By default, Android will destroy and recreate the map view which is problematic. So, let’s tell Android not to do that. Find and edit the AndroidManifest.xml file again.

Locate the section that starts with:

Right after the line that reads:

Insert this:

When you’re done it should look something like this:

Now, when you run your application again, it will support device rotation:

Notes and Things to Try

This simple application will download and cache data in your application’s cache area. If you delete the application from the device, these files will be destroyed.

You can try loading a completely different map, here are a few map tile URLs, but you can find many more online:

Map Provider	Map tiles URL starting point
MapQuest - Street map	http://otile1.mqcdn.com/tiles/1.0.0/osm
MapBox - Satellite Imagery	http://c.tiles.mapbox.com/v3/examples.map-qfyrx5r8
MapBox - Street map with land	http://a.tiles.mapbox.com/v3/examples.map-4l7djmvo

NOTE: if you try different maps, be sure to give each one a different name, otherwise, the mapping engine may ‘mix’ tiles together in your cache.