So for the past three months, I have completely annoyed the great mapbox team trying to set up probably the most complicated mapping system I have ever done in my young life. This all started when a client at work came to us and said they wanted to create a map. Of course I foolishly said yes, until I found out they wanted to create a map from an image. Let’s just say I had no idea that you could even do such a thing.


So we’re going to be creating some maps from images today, these are super useful for maps that are of places that don’t exist, like an MMO, or Middle Earth, or Hogwarts. We are going to go a little more in depth and stretch the usability of a tutorial I found before here because the amount of research I had to use to make a map before was disgusting.

So before you dive into making the map from an image you have to get GDAL running on your machine which is a lot harder than I thought it would ever be. I installed this on a Mac so we’re going to go with that from now on (sorry everyone else). Make sure you have XCode installed and from the Extras menu, install GCC as for some inexplicable reason newer macs don’t come with a compiler.

Before you even get close to installing GDAL on a mac you need a whole slew of other things, download and install the following programs

UnixImageIO Framework:
PROJ Framework:
GEOS Framework:

These all worked for me on Mountain Lion, so if you’re also running mountain lion you should be good.

After these are installed, you need to grab and compile it from source using the following commands after you cd into the source directory:

./configure --mandir=/usr/local/share/man \
CFLAGS="-Os -arch i386 -arch x86_64"
sudo make install

If that runs successfully we can move to the next step, compile GDAL using these instructions but change the config line to the following

./configure --with-threads --disable-static --without-grass --with-jasper=/Library/Frameworks/UnixImageIO.framework/unix \
--with-libtiff=/Library/Frameworks/UnixImageIO.framework/unix --with-jpeg=/Library/Frameworks/UnixImageIO.framework/unix \
--with-gif=/Library/Frameworks/UnixImageIO.framework/unix --with-png=/Library/Frameworks/UnixImageIO.framewok/unix \
--with-geotiff=/Library/Frameworks/UnixImageIO.framework/unix --with-sqlite3=/Library/Frameworks/SQLite3.framework/unix --with-odbc \
--with-pcraster=internal --with-geos=/Library/Frameworks/GEOS.framework/unix/bin/geos-config --with-static-proj4=/Library/Frameworks/PROJ.framework/unix\
--with-expat=/usr/local --with-curl --with-python --with-macosx-framework --with-pg=/Library/PostgreSQL/9.1/bin/pg_config \
CFLAGS="-Os -arch i386 -arch x86_64" CXXFLAGS="-Os -arch i386 -arch x86_64" LDFLAGS="-arch i386 -arch x86_64"

Did GDAL work? We’re about to find out.

Formatting the Image

Some up front things about the image:

  1. If it’s too large the script will choke and die
  2. The Script Accepts PNG & JPG (and works with transparency)
  3. If The Image is small, it will become fuzzy on zoom

If you want layers on your map, the way I did it was I created each layer I wanted to turn off and on in a separate png. I compiled the pngs in a large photoshop document and made sure that they aligned exactly as they would on the map when I was finished and saved each layer individually as a png. This assured me later after all the formatting that the map layers would align and look perfect in the final product

Grab the script from this gist: Download it and rename it to and run it on one of your images with the following command

python imagename.png

If it ran successfully your terminal output will be something like Converting: 10…20…30, if it fails on any line you didn’t install GDAL correctly so go back and try again. If it just flat out fails without saying some python error, the image is too large. This is the moment of truth! When you’re done you’ll get a imagname.png.tiff file. This is called a geotiff and can be used directly with Tilemill! Hooray!

Download tilemill and install it, start a new project.

Mapbox attempts to try and help you out here but adds an unnecessary step IMHO, you don’t have to add a projection, it never freaking works, just forget about it. Import your raw GDAL geotiff into tilemill by selecting add a new layer and you’ll get this screen.


make sure you select the SRS-900913 projection and click save and style, this should load your map into tilemill. The last thing you need to do is change something in the mss file on the side of tilemill

make sure your layer style is the following

#base {
raster-scaling: bilinear;

This helps it not look choppy when people zoom in and out on your maps. Save and Export as mbtiles (set your zoom levels to like 4 at the most, test your best zoom levels before you export), as they’re the most useful file format for this kind of stuff. If you’re feeling lazy and won’t have a lot of hits, go ahead and create a free account and upload your mbtiles to mapbox and use them for hosting them. However in the next part of this tutorial, we’re going to take the road less traveled and set it up without any mapbox help by using Tilestream