The Dark Art of Vector Map Tiling

If you’ve tried making map tiles and you’re anything like me, you probably feel a lot like Ron. Thanks to the incredible work from people like Erica Fischer at Mapbox and Felt, there is great open source tooling that magically takes geospatial data files and turns them into small files for highly performant beautiful maps. But as your needs get more specific the magic starts to get more complicated and before you know it, you’re feeling like a muggle wrestling with your terminal hoping that you get the right combination of spells that create a dataset that turns out just right.

Today, I’m sharing a new tool that makes this process a little bit easier for us muggles as well as some tricks of the trade that I’ve picked up along the way. Check out the tool and let me know what you think!

A young wizard’s introduction to Tippecanoe

Tippecanoe is the powerful spell book for transforming geospatial data into vector tiles. Tippecanoe can process enormous datasets — millions of features — and intelligently simplify them at different zoom levels while preserving their essential characteristics.

Unlike other methods that might simply discard features when things get crowded, Tippecanoe offers a remarkable array of enchantments — options like feature dropping, attribute filtering, and clever clustering — that maintain the visual integrity of your maps even at low zoom levels. Knowing what to use when may feel daunting at first (with commands like --drop-densest-as-needed and--extend-zooms-if-still-dropping), but once mastered, you can create tilesets that render quickly and beautifully across platforms, making you the cartographic equivalent of a Defense Against the Dark Arts professor, but hopefully with a longer career.

If you aren’t familiar with Tippecanoe, go install it following the instructions here.

Introducing Tippecanoe GUI

Tippecanoe has great documentation in its ReadMe with all the info you need to get started, but I’ve often found that half the battle is finding the commands, deciding which ones to use and stringing them together into a coherent command you can actually run in your terminal. I’ve made this a little easier by taking many of the Tippecanoe features and converting them into an interface you can use to generate your commands. The premise of this tool is you select all the options you want from the dashboard and a command is generated below you can copy and paste in your terminal. Check it out and let me know what you think!

Tips and Tricks I’ve learned along the way

I’ve got to say here, the whole reason I’m writing this is because I am not an expert. There are people and companies that specialize in just making map tiles. That said, I’ve wrestled through making enough map tiles that I’ve learned strategies to make this as painless as possible.

Off the bat know that there are currently two major types of map tiles

• mbtiles: these are meant to interface nicely with Mapbox maps and are the OG map tiles format. The downside is they need a server to serve them to your app. You can upload these into you Mapbox account to serve them for you, but if your file is bigger than 300mb you will likely need to go through the Mapbox Tile Service.
• pmtiles: this is a newer map tiles filetype built for open source maps through MapLibre. They can also be added to Mapbox maps pretty easily with this cool node package.

Get a Map Tile Viewer

Do yourself a favor and get a local map tiles viewer. If you’re planning to make mbtiles I really like this no nonsense viewer developed by GitHub user Akylas. If you’re working with pmtiles this is a great online viewer. If you try to view your map tiles using something like QGIS you can view your data, but it doesn’t display correctly based on zoom level

Lower zoom levels are the hardest

Based on how map tiling works, lower zoom levels (the map is more zoomed out) will have tiles with larger geographic areas than the higher zoom levels (the map is more zoomed in). The first thing you should do is run some tests to figure out what the lowest zoom level is where none of your data is dropped. The brute force way to do this is to run a command like the one below that attempts to generate a tileset with one zoom level without dropping anything.

tippecanoe -o output.mbtiles -z12 -Z12 -r1 input.geojson

• -z12: Sets the maximum zoom level to 12
• -Z12: Sets the minimum zoom level to 12 (together with -z12, this means only level 12 will be generated)
• -r1: Prevents any automatic dropping of points at zoom levels below the base zoom

There are much more elegant ways to do this, but this, but something like the above is a great foolproof way to learn about your data; if this command fails, it’s too big for that zoom level. Keep trying this until you get a minimum zoom that works. Once you know this, ask yourself how you want your data to display between zoom 0 and whatever that zoom level is. This is where you will use all the magic commands like--drop-smallest-as-needed or --drop-smallest-as-needed to control what the data looks like at these zoom levels. Note that just not writing these zoom levels is a totally acceptable solution if you don’t plan on making this data visible at these zoom levels.

Use -zg for max zoom

Unless precision is extremely important for your data, just use the -zg flag for max zoom. This flag guesses the maximum needed zoom to show your data with decent precision. The lower zoom tiles will be what most inflate your map tiles file size. -zg does a good job of making sure that you don’t create tiles that are overly zoomed.

Drop the details

Before you even start trying to make map tiles, try to reduce your file size. I am almost always working in geopandas manipulating data before I write a geojson file that I convert to map tiles. When creating your data set:

• Get rid of columns you don’t need
• Reduce precision of your floats as much as possible or even better use integers
• Can you convert any string columns to integers

One trick I’ve used is to write a tiny geojson file with just geometry and a feature id. I write this at lower zoom levels and then have a fully detailed file that I write to map tiles visible at lower zoom levels. This makes data visible at all zoom levels and you can design a UI that work with your data constraints.

Make a directory and convert this to map tiles

This is a somewhat advanced method, but one output option for tippecanoe is a “directory.” What this will do is write each zoom level to a directory. This isn’t necessarily best practice, but you can granularly write each zoom level you want with different options. You’ll end up with folders for each zoom level that you can move into a single folder with subfolders showing each zoom. Once you’ve done this, take one of the metadata files that was written and change the metadata to reflect the zoom levels you’ve used. Once you have this directory, you can create a map tiles file with tile-join.

Big tile energy

If all else fails and you just want to show your data on a map forget about tile size limits using the -pf and -pk flags. This will decrease the performance of your map and you will not be able to upload these tiles to your Mapbox account, but you can write to a pmtiles file and host this in an s3 bucket on AWS. I used this trick for our vector waterways data in this web app. It’s not ideal, and the performance lags at low zoom levels, but it shows all the data and sometimes that’s all you care about.

Run your scripts in Jupyter notebooks

This is coming from a guy that just recently learned that option click will move your cursor anywhere on your terminal (you’re welcome if you didn’t know that already). I’m usually manipulating data in Jupyter notebooks. You still need to write a geojson file first, but you can run terminal commands in Jupyter notebooks by putting ! before the command. This is cool as you can also use curly brackets to reference python {variables} in your scripts. It’s a nicer user interface and sometimes easier to just run this in the notebook where you are working with your data.

Wrapping up

Tippecanoe may seem like advanced magic at first, but with practice and the right tools, you’ll soon be conjuring beautiful, performant maps. Give the Tippecanoe GUI a try; hopefully this tool will help make your mapping journey less of a Chamber of Secrets. Now go forth and create maps so magical even the Marauders would be impressed!