Creating Custom Overlays for iOS MapKit Framework

I am part of a team developing an iPhone app for Midwestern State University. I am particularly responsible for developing the map that we are going to use for the app. Because I had a lot of detail I wanted to show on our map – Faculty/Commuter/Resident Parking Lots, �labels for different buildings, key points of interest on campus – I began to look into using custom overlays, a large image laid of top of the Google map tiles.

One of the issues I ran into was a lack of good information on how to integrate custom overlays into an existing�iOS project. What follows is the process used to create and integrate custom overlays into an existing iOS app.

Create Overlay Image

I knew from the beginning that I would need some graphic of Midwestern State University to serve as a foundation for me to build my overlay image. To get the background image, I:

Went go Google Maps
Grabbed the embed code for the location I wanted
Created a quick HTML document with the embed code in it
I changed the size of the iframe to about 4,000 px by 4,000 px
I used a plugin for Google Chrome browser that took a screenshot of the entire�page

This gave me a background image that I could put into Photoshop and then build upon. I used 300 PPI and set my image size to about 3,000 px by 4,000 px. With a smaller image size or lower resolution I noticed that I had very jagged edges. You can tweak these image settings to your project.

Start building your overlay on top of this background image. When you have an overlay image that you are happy with, hide the background, and export your image. I exported my image as a PNG-24 since I had large amounts of blank area on the image.

Find the Corner Coordinates

The best way I found to match the corner pixels of the image to coordinates is to:

Create a copy of your overlay image, this time with a red border
Add your overlay image to Google Earth
Custom overlay with red border added
Stretch/move your image so that it lines up. Below are the result that I had.
Drop a pin on each corner of your image. Be sure to zoom in as close as possible, and get the pin as close to the corner as possible
Close up of pin
Right click on each pin in the left toolbar, and select “Directions from here”

Selecting “directions from here” will put the coordinates for the pin in the search form. Copy these down.

Create Custom Overlay Tiles

MapKit, and Google Maps, works by using map tiles. These are square images that only load if they are viewable in the zoom level that you are looking at. Thankfully, there is a tool called GDAL that will take our overlay image and cut it up into all of the tiles that we need. Take a minute and go download and install GDAL. If you’re on a Mac, I would suggest using Kyng Chaos. I will be giving the Mac commands below, but I assume that they are similar on a PC.

Because we are referencing each corner pixel of our overlay image to a coordinate, we need to know how many pixels wide and tall our image is. To do this, we are going to use the gdalinfo command. Before we can use gdalinfo though, we need to get in the directory of our image/project. Go ahead and navigate to the directory of your project, then use the gdalinfo command followed by your image name. Your commands should look something similar to this:

cd /Users/ericbinnion/Desktop/imgDirectory-Here
gdalinfo imgName.png

This should give us some information that looks like the image below:

A screenshot of the gdalinfo command on Mac.

Next, we will create our VRT file which will reference the coordinates to the corner pixels. To do this, use the following command:

gdal_translate -of VRT -a_srs EPSG:4326 -gcp 0 0 -98.526518119 33.8812011706 -gcp 1055 0 -98.5158112852 33.8811992984 -gcp 1055 1584 -98.5158116258 33.8679003639 -gcp 0 1584 -98.5265176807 33.8679047769  msuMap.png msuMap.vrt

You will of course replace the coordinate points, the image name, and the vrt name that you want create to fit your project. The last step of the project is to actually create the tiles. To do this, we will use the following command.

python gdal2tiles.py -z 14-21  msuMap.vrt

This will create tiles for zoom levels 14-21 using the msuMap.vrt file that we created in the last step. At this point you should see some html files in your project. These will give you a preview of how your custom overlay will look on MapKit for iOS.

Series

This is part 1 of a 2-part series in “How to Create Custom Overlay Tiles for iOS MapKit Framework.” View part 2 here.

11 responses to “Creating Custom Overlays for iOS MapKit Framework”

Adding Custom Overlays to iOS MapKit Framework – Eric Binnion

February 6, 2012 at 2:27 pm

[…] This is part 2 of a 2-part series on how to create customer overlays for the MapKit framework on iOS. View part 1 of this series here. […]

Reply
Jack

March 30, 2012 at 1:53 pm

Great article! Just have one question. Which GDAL Framework do I need for a similar project? The site you referenced shows two links, just the framework itself and one with additional tools. I plan on using this in my own project and have been looking for a good reference. Thanks!

Reply
1. Eric Binnion
  
  March 30, 2012 at 1:59 pm
  
  Which framework you use mainly depends on which operating system you are using. I am currently using Mac OS Lion, and the Kyng Chaos framework worked perfectly fine for me. If you are using another OS (such as Ubuntu or Windows) then you can search for other frameworks, or you can grab a copy of the GDAL source and compile it yourself.
  
  I hope that helps 😉 If you’re using another OS and find a good framework/installation process, shoot me an email and I’ll update the article with your recommendation and a link to your site.
  
  Reply
2. Eric Binnion
  
  March 30, 2012 at 2:02 pm
  
  I revisited the link to Kyng Chaos and now I understand what you’re asking. This article was created using the Gdal 1.8 Complete framework at Kyng Chaos. You may try the newer 1.9 version, but the commands may be slightly different. I have not yet tried it myself.
  
  Reply
Ben Workman

May 14, 2012 at 10:28 pm

Awesome post!! For anyone who runs into the problem with the final python command in Mac OS 10.7 Lion (I did), you’ll likely see something like “python: can’t open file ‘gdal2tiles.py’: [Errno 2] No such file or directory”

try, instead:

PYTHONPATH=”/Library/Frameworks/GDAL.framework/Versions/1.6/Python/site-packages/” python /Library/Frameworks/GDAL.framework/Programs/gdal2tiles.py -z 14-21 campus.vrt

where campus.vrt is, of course, your vrt file. Also, you have to cd into the folder containing your image and vrt also.

Awesome post!! For anyone who runs into the problem with the final python command in Mac OS 10.7 Lion (I did), you’ll likely see something like “python: can’t open file ‘gdal2tiles.py’: [Errno 2] No such file or directory”

try, instead:

PYTHONPATH=”/Library/Frameworks/GDAL.framework/Versions/1.6/Python/site-packages/” python /Library/Frameworks/GDAL.framework/Programs/gdal2tiles.py -z 14-21 campus.vrt

where campus.vrt is, of course, your vrt file. Also, you have to cd into the folder containing your image and vrt also.

Again, great tutorial! Thanks!

Reply
1. Eric Binnion
  
  April 27, 2013 at 9:47 pm
  
  Hey Ben, thanks for leaving this comment! I’m certain your comment helped several people.
  
  Reply
David

June 12, 2012 at 9:47 pm

Thanks for this Eric. This is for the newbies like myself:

1) Google Earth coordinates does not follow the X, Y format. It’s reversed. After dropping the pin and selecting �directions from here�, note the first set of numbers are your North South coordinates and the next set of numbers after comma is your West East numbers.

2) Confusion arise when it comes to the gdal_translate command. Note you now have to enter your coordinates in X, Y format. Meaning you have to enter your West East numbers first then North South numbers.

Dave

Reply
John G

July 22, 2012 at 7:53 pm

Eric, thinks for posting these steps. Good work on figuring this out. I was able to get my tile overlay to work fine with one exception: no matter how precise I seem to be with my corners in Google Earth, my overlay always seems to be shifted to the right of where it should be by what appears to be a 100ft or so when I view the map in the IOS5 emulator. May overlay in Google Earth is very precise. Did you run into any issues like this? Do you have an suggestions?

Reply
1. Eric Binnion
  
  August 1, 2012 at 9:03 am
  
  My tiles showed up fine in the iOS emulator. You could hack it by trying to move your overlay about 100ft left… but I don’t know if that’s a great solution. That’s more of a push code now solution. Let me know what you find out.
  
  Reply
Mark B

August 25, 2012 at 9:26 am

Wow, Great article. I wonder, how did the app turn out? Can we download it from the App Store? I am learning this right now and can not wait to spend some time trying your solution. I will post back and let you know how it goes.

Thanks for the article. I am sure it will save me many hours. I will use those hours to spend with my 3 kids. Yea!!!!

Reply
1. Eric Binnion
  
  August 25, 2012 at 7:40 pm
  
  It turned out OK for a first app. You can download the app in the app store. It is called MSU2U I believe. This was a multi-person project, of which I was primarily responsible for the maps and the design. Let me know what you think. There’s definitely plenty of room for improvement!
  
  Reply