Tutorial 5 — Dynamic Marker

Adding an own-ship marker to show GPS location and orientation

---

Most apps that implement GPS functionality show some kind of marker on the screen. The marker shows current location and current orientation. In this tutorial we will build off of Tutorial 4 and add an own-ship marker to the app we have been building.

Step 1

We are going to start here by checking out tutorial5:

git reset --hard
git checkout tutorial5

The reason we need to do this is because the project now contains two new files named blueplane.png and [email protected] in the project's images directory. These are ordinary png files and they contain the marker we will be using (a blue airplane). The larger 2x version is needed for retina displays. You can easily create two png files like these to implement any marker shape and color you would like in your app.

Step 2

Run the app. The app should work identically to the one shown in Tutorial 4, but the marker should now be visible when you click the button to turn the GPS on. In the iOS Simulator menu bar, choose the Debug menu and then choose the Location item. Choose one of the options that show motion, like "Freeway Drive" or "City Bicycle Ride". Look in the console window of Xcode and you will see the speed and course changing. The map should pan to the new location so that the new location is centered on the screen and rotate the map to demonstrate Track-Up mode if you click the buttons to turn on the GPS and turn on Track-Up. The marker should appear and disappear when you tap the GPS button.

Step 3

Let's look at the code that was added to make the marker work.

Looking in ViewController.h, there is a new entry for MEMarkerMapDelegate in the interface.

Looking in ViewController.m, in the initializeGPS class, there are two lines of code to add and remove the own-ship marker depending on the state of the GPS.

In the didUpdateToLocation function, there is now a new call to updateOwnShipMarkerLocation to move/rotate the marker when necessary.

Then there are these new functions to manage the marker:

All of this functionality is described in the Documentation, but let's look at what is happening here because it is pretty straightforward.

The general theory we are using to create an own-ship marker is to create a new marker layer in the mapping engine and then add a single marker to it that acts as the own-ship marker. This marker needs to be able to rotate when Track-Up is off, and the BA3 Altus Mapping Engine is happy to do marker rotation.

The addOwnShipMarker function starts by creating an array of markers. This array will contain the single blueplane marker. The it creates a marker annotation and adds it to the array. Then it creates a marker map info object and adds it to the map view controller. Note that the z order is 999, so the marker is always visible. All other layers we create will have a lower z order number (the base map is currently set to a z order of 1, for example).

The updateMarkerInfo function is called by the mapping engine to get the marker information. We send back the blueplane icon and an anchorpoint located at the center of the icon.

Step 4

If the current view is complicated with multiple layers and markers, it can be easy for the user to "lose" the GPS marker in the clutter. You can solve this problem for the user by adding an animated beacon to the GPS marker. See "Is there any way to make the GPS marker in Tutorial 5 more obvious to the user?" in the FAQ for full explanation.

Step 5

Now we would like to add a real map to the BA3 Altus Mapping Engine. It will cover the default base map we have been using and provide detail all the way down to street level. To do this we will use a tile provider like MapBox. This is explained in Tutorial 6.