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.

Creating Custom Overlay in iOS

Everything we have done up to this point has been to create the tiles we will use in our project. Now that we have created those tiles, we need to add them to our project.

For this, we will use a sample project from Apple called Tile Map. I have a working iOS project that uses custom overlay at Github. We are going to copy a few classes from this project, so go ahead and grab the zip-ball and open it in Xcode.

You will need to copy the following files into your own project:

• TileOverlay.h
• TileOverlay.m
• TileOverlayView.h
• TileOVerlayView.m

Be sure to select the box to “Copy items into destination group’s folder.” At this point I am going to assume that you have already created a View Controller for your map. If not, go ahead and create one. In the .m (implementation) file of your map View Controller, we are going to import the TileOverlay.h and TileOverlayView.h files. Your map View Controller should now look something like this:

#import "mapViewController.h"
#import "TileOverlay.h"
#import "TileOverlayView.h"
@implementation mapViewController
- (void)viewDidLoad
{
    NSString *tileDirectory = [[[NSBundle mainBundle] resourcePath] stringByAppendingPathComponent:@"Tiles"];
    TileOverlay *overlay = [[TileOverlay alloc] initWithTileDirectory:tileDirectory];
    [map addOverlay:overlay];
    map.mapType = MKMapTypeSatellite;
    MKCoordinateRegion CSC;
    // Defines the center point of the map
    CSC.center.latitude = 33.874809;
    CSC.center.longitude = -98.521129;
    // Defines the view,able area of the map. Lower numbers zoom in!
    CSC.span.latitudeDelta = .003;
    CSC.span.longitudeDelta = .003;
    [map setRegion:CSC animated:YES];
}
- (MKOverlayView *)mapView:(MKMapView *)mapView viewForOverlay:(id )overlay
{
    TileOverlayView *view = [[TileOverlayView alloc] initWithOverlay:overlay];
    view.tileAlpha = 0.6;
    return [view autorelease];
}

The only other change that we have to make at this point is to add some code to our app delegate file. In the delegate header file you will need to add some code (highlighted below):

#import
@class mapViewController;
@interface msuAppDelegate : NSObject {
    UIWindow *window;
    mapViewController *viewController;
}
@property (strong, nonatomic) UIWindow *window;
@property (strong,nonatomic) mapViewController *viewController;
@end

We still don’t have tiles in our project at this point, so go ahead and create a directory on your Desktop named “Tiles”. Copy all of the tile sub-directories and the tilemapresource.xml into the “Tiles” folder that you created on the desktop. Now, drag the “Tiles” folder into your iOS project. Be sure to select “Copy items into destinations group’s folder” and “Create folder references for any added folders.”

Copying Tiles folder into iOS Project

The last step is to connect your Mk Map View in storyboard to delegate. Once we do that, the Custom Overlay for MapKit should be working. Click the Mk Map View in storyboard, use control + click, then drag, to the Map View Controller Icon. View the screenshots below.

Mk Map View Screenshot

Connect Mk Map View Screenshot

Map View Controller Delegate

At this point go ahead and run your program to see if everything is working. If you have any problems, please leave me a comment below, and I will modify this tutorial. You can reference the iMustangs project  on Github for an example of integrating custom overlays into an iOS project.

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 is the result that I had.
  

  Close up of overlay image

• 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”

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.