Custom Map Tiles (Part 3 - TileStache)

Part 1 - MapCruncher
Part 2 - TileMill
Part 3 - TileStache
Part 4 - Programmatically
Part 5 - Offline maps on iOS

In my previous post all the map tiles were pre-rendered and stored in the filesystem. Although that approach brings more flexibility it also has some disadvantages: storage and time.

Imagine that we want to store tiles for every zoom level covering the whole world. We would be talking probably about Pentabytes of information. Even if we just stored all the zoom levels for some countries it would be probably lots of Terabytes. Space is cheap, but we're talking about a whole new level here.

Probably even worse than the storage, it would take ages to render all of the required tiles. Without enough computational power we could be looking at months (or more) to render all the tiles. 

So, in this post, I'm going to present a realistic alternative: using a Tile Server to generate and cache map tiles on-the-fly. I'm going to use TileStache for this.

I like to consider TileStache as the spiritual successor of TileCache, probably the most famous tile server around. Anyway, I prefer TileStache because it's easier to use and more modern, supporting for instance the MBTiles/UTFGrid specs that I've shown previously.

So, in this post I'll:

• Install Python 2.7
• Install Mapnik
• Install TileStache
• Configure the server
• Replace the URLs in the client (from my previous post)
• Try it out

Install Python 2.7

Install the 32 bit version of Python 2.7. Although you may install other versions I strongly advise against it. Direct link to the installer here.


Installing  mapnik:

TileMill uses Mapnik to render the map images, and we'll also use it with TileStache.

To install Mapnik 2.0 in Windows just follow this post to the letter. It includes a direct link to the binaries and installation steps.

The last step of the installation is to try out the map generation. The following output should be generated.

If this is what you see, all is well. Otherwise, Houston we have a problem.

PS: Don't forget to add all the environment variables/paths described in the page. In my case I've added:

PATH
c:\mapnik-2.0.1rc0\lib;
C:\Python27;
C:\Python27\Scripts

PYTHONPATH
c:\mapnik-2.0.1rc0\python\2.7\site-packages


Installing  TileStache

We could do this the hard way or easy way. I'll opt for the easy way.

Download and install Python Setup tools from here:

This includes a tool called "easy_install". We'll eventually run:

easy_install tilestache

But we need to previously install the TileStache dependencies. According to the "easy install" package page for TileStache it depends on ModestMaps, PIL and SimpleJSON so a :

easy_install PIL
easy_install ModestMaps
easy_install SimpleJSON

should do the trick.


UPDATE: 08/07/2012
I forgot to mention a dependency on Werkzeug. It's a web-server included with TileStache that's required for this example. Thanks Bashton :)




After installing TileStache is run using the "tilestache-server.py" script, inside the scripts folder. Run it in the TileStache main folder using a command window.





Then open a browser window on "http://localhost:8080" and it should display a welcome message.




TileStache by default searches for a "tilestache.cfg" file. The default one has a "osm" layer defined as a proxy for the OpenStreetMap tiles.

"osm":
{
    "provider": {"name": "proxy", "provider": "OPENSTREETMAP"}
},

If we place a url on the browser as:
"http://localhost:8080/osm/0/0/0.png" a tile with the whole world should be displayed.

Remember, we're not generating anything (yet). We're just using a proxy to OpenStreetMap own tiles.

Now we want to generate our own tiles. As I said previously we'll render the tiles using Mapnik and thus create a new .cfg file named "Test.cfg" with the following content:

{
  "layers": 
  {
    "freguesias":
    {
        "provider": {"name": "mapnik", "mapfile": "C:\\tilestachedemo\\style.xml"}
    }
  }
}

The layer name will be used on the url to fetch the tiles. I've named it "freguesias" because of my previous post but name it as you please.

Couldn't get any simpler than this. The map info itself will be provided by the style.xml file used by Mapnik. To create the style.xml file we could read the whole spec and write the file by hand, which could be tedious. Fortunately TileMill allows use to export the Carto language to a working Mapnik XML.

I'll export the project from my previous post using the "Mapnik XML" option from the top right menu of TileMill. Create a "style.xml" file with this content in some folder (the same referenced from the .cfg file).

Now, let's run the server in the folder of our "test.cfg" like:

Now I'll change the javascript from my previous post so that the tilelayers are directed to TileStache.

The tiles property will thus be modified from:

tiles: ['http://localhost/tiles/freguesias/1.0.0/Freguesias/{z}/{x}/{y}.png']

to

tiles: ['http://localhost:8080/freguesias/{z}/{x}/{y}.png']

If we now open the webpage the output should be the same as before. The main difference is that the tiles are now generated on the fly, and we're not limited to the zoom levels that we've exported previously. The disadvantage is that it takes some time to render each tile and, although the browser might cache them, each new client will make the tilestache server compute tiles. So, it's essential that we cache the tiles at the server. TileStache supports many different type of caches but I'll use one of the simplest: "Disk".

Inside the .cfg let's add a cache section (before "layers")

"cache":
  {
    "name": "Disk",
    "path": "file://C:/temp/cache"
  },

Pretty simple, the cache will be at the filesystem. It will be pretty easy to check if it's working or not. Before starting we can create the "c:\temp\cache folder. Then, while we navigate the map, the tiles will be computed and stored in the filesystem at the path that we supplied. For example:

Now, we're just missing something that we had previously: support for UTFGrids. TileStache supports them and we just have to create a specific section for it. The full .cfg will be:

{
  "cache":
  {
    "name": "Disk",
    "path": "file://C:/temp/cache"
  },

  "layers": 
  {
    "freguesias":
    {
        "provider": {"name": "mapnik", "mapfile": "C:\\tilestachedemo\\style.xml"}
    },

    "freguesias_utfgrid":
    {
        "provider": {
            "class": "TileStache.Goodies.Providers.MapnikGrid:Provider",
            "kwargs":
            {
                "mapfile": "C:\\tilestachedemo\\style.xml",
                "fields":["DICOFRE", "FREGUESIA"],
                "layer_index": 1,
                "scale": 4
            }
        }
    }
  }
}

Now, change the map client so that the initialization is:

var tilejson = {
        tilejson: '1.0.0',
        tiles: ['http://localhost:8080/freguesias/{z}/{x}/{y}.png']
        grids: ['http://localhost:8080/freguesias_utfgrid/{z}/{x}/{y}.json'],
        formatter: function (options, data) { return "CODE: " + data.DICOFRE }

    map = new L.Map('map');
    map.addLayer(new wax.leaf.connector(tilejson));
    map.setView(new L.LatLng(39.5,-5.0), 6);

    wax.leaf.interaction(map, tilejson);

Lets try the demo again. The code of the parish should appear on the top left corner when the mouse is over the layer.

For now this post will end this series on Custom Map Tiles. I'll probably revisit this topic later to show how to create tiles programatically using C# and GDI+ without resorting to any tool.