Sunday, 4 November 2012

Exploring the MapBox stack: MBTiles, TileJSON, UTFGrids and Wax

In my last blog post, we created a population density map of New Zealand using QGIS, SQLite and TileMill. Today, we’re going to publish this map to the web using various MapBox inventions. I'll also show you how to publish an interactive TileMill map on your own web server using some PHP and JavaScript wizardry.

The tooltip shows when the user hovers over or clicks on the map. It allows us to show dynamic content - additional data, images, charts - for each map feature. I want to show the name, total population, area and population density for each feature:

The data fields for the layer are wrapped in curly Mustache tags. These tags will be replaced by data when you interact with the map. You can use the full Mustache template language.

The easy way to publish this map is to upload it to MapBox Hosting, and use the embed code provided. If you want to publish your map on your own web server, this is an alternative route:

To export an interactive map from TileMill, you need to use the MBTiles format. This is an innovative SQLite-based format specification capable of storing millions of map tiles in a single file. The format is also supported by various 3rd-party applications, and I'm sure we'll see a greater adoption in the future.

Within the MBTiles file, the map legend, the tooltip template and information about map extent, zoom levels etc. is stored in a format named TileJSON. This is also an open specification, providing a consistent way of describing a map, making it easier to load and display a map the way it’s meant to be seen. The TileJSON for my map looks like this:

If you add interactivity to your map (tooltips), your MBTiles file will also include the most impressing part of the MapBox specifications: UTFgrids. This JSON-format allows us to add thousands of interactive points or polygons through interactivity data grids, and it will even work in older browsers with limited support for vector data.

So how do we turn our MBTiles file into an interactive map? Previously, I've used MBUtil to extract the contents from MBTiles into a directory structure. But by doing this, we loose the benefits of the MBTiles format, like storing a map in a single file and dealing with redundant images. What we need is a script on our web server that will extract content from our MBTiles file on demand. I decided to try a PHP script from infostreams (this is probably not the most scaleable solution). The script supports the full MBTiles specification, including TileJSON and UTFGrids. Installation is simple: just put the .php file and the .htaccess file in the same directory as your .mbtiles files. The .htaccess file includes a rule that rewrites requested URLs on the fly, so the map data is available un URLs like:

So when we have our backend sorted, how can we recreate our interactive map with Leaflet or other JavaScript mapping libraries? This is way the MapBox team created Wax, which is a client implementation of the MBTiles interaction specification. You just include the wax script together with your mapping library of choice, and then you can add interactivity with a few lines of code:

I've also done some extra JavaScript coding to allow switching between various interactive map layers. I'll save that for a later blog post.

13 comments:

Thank you! I had played with TileMill and Leaflet before, but was unsure how I was supposed to use them (and other parts of the MapBox family) together. This is the first time I've seen someone describe how to do this!

Hi there, thx for the post. There is an issue with the wax.leaf.interaction, if you position NZ to the right side of the map, then hover over NZ you will see that it does not render the teaser, but if you hover in the center of the map the teaser is rendered, it's as if the map had never move. I wanted to make a map with similar components and also wanted to use leaflet, but using wax and modestmaps instead solves the issue.

Hello Bjorn,Thank you for sharing. I have a question for you regarding the legend. If you would like to move your legend to the top left corner of your map, how would you do this?I am new to MapBox and can't find any comments on this topic, so your answer would very appreciated.Dorothy

Thanks for sharing this. I'm trying to get my own .mbtiles online for a project. Implementing Wax is going wrong I think.

In the same folder:- tileserver.php- .mbtiles- index.html (with the script you've written and the sources for leaflet)

I've downloaded Wax, but this folder is full of stuff, so I don't know what to use.In the script you've written, you're calling for a 'wax.tilejson('URL', function)....etc. I don't know what URL to put there and where is the tilejson file that I need to get from the .php script you told about?

do you know how I can do the exact same thing (switch or remove legend when baselayer is on/off), but with the overlay layers instead.

I've tried moving your "population" tilelayer from the base layers to the overlay layers, the "population" legend appears when the layer is checked, but does not disapear when the layer is unchecked...