Build vector tilesets from large collections of GeoJSON features.
C++ C Other
Latest commit b3847c1 Jan 17, 2017 @ericfischer ericfischer committed on GitHub Merge pull request #350 from mapbox/c++-readme
Add instructions for upgrading g++ on Linux
Permalink
Failed to load latest commit information.
catch Make UTF-8 checking into a unit test with Catch Oct 5, 2016
jsonpull More careful JSON parsing thanks to http://seriot.ch/parsing_json.html Oct 27, 2016
man Add instructions for upgrading g++ on Linux Jan 17, 2017
mapbox Upgrade Wagyu to cfc895 and use its Sutherland-Hodgman implementation Jan 11, 2017
protozero Use protozero for tile decoding Apr 23, 2016
tests Upgrade Wagyu to bfbf2893 Jan 5, 2017
.gitignore Create .gitignore Nov 16, 2016
.travis.yml Add libstdc++ packages Jun 7, 2016
CHANGELOG.md Upgrade Wagyu to cfc895 and use its Sutherland-Hodgman implementation Jan 11, 2017
LICENSE.md Add license Feb 8, 2014
MADE_WITH.md Punctuation and capitalization Jun 1, 2015
Makefile Upgrade Wagyu to cfc895 and use its Sutherland-Hodgman implementation Jan 11, 2017
README.md Add instructions for upgrading g++ on Linux Jan 17, 2017
decode.cpp Support feature IDs for decoding Jul 15, 2016
enumerate.cpp There should be a test of tippecanoe-enumerate Oct 12, 2016
geojson.cpp Associate attributes with the right layer when explicitly tagged (#342) Jan 3, 2017
geojson.hpp Don't spend geometry space on index or extent unless it is needed Nov 12, 2016
geometry.cpp Upgrade Wagyu to cfc895 and use its Sutherland-Hodgman implementation Jan 11, 2017
geometry.hpp Option to snap low zooms to a stairstep grid Nov 28, 2016
main.cpp Choose a deeper initial tile than 0/0/0 if one contains all the features Dec 16, 2016
main.hpp Tests of the three current strategies for reducing tile size Oct 24, 2016
mbtiles.cpp Fix some compiler warnings about signed comparisons Oct 15, 2016
mbtiles.hpp Getting ready for multithreaded tile-joining Sep 20, 2016
memfile.cpp Make sure memfile growth gets tested Oct 26, 2016
memfile.hpp Drag header files into C++ Apr 27, 2016
mvt.cpp Encode the "id" field of GeoJSON objects as vector tile feature ID Jul 15, 2016
mvt.hpp Support feature IDs for decoding Jul 15, 2016
options.hpp Option to snap low zooms to a stairstep grid Nov 28, 2016
pool.cpp Use std::set to track the layer-wide feature attribute types. Apr 28, 2016
pool.hpp Use std::set to track the layer-wide feature attribute types. Apr 28, 2016
projection.cpp Add the ability to tippecanoe-decode into EPSG:3857 instead of WGS84 Jun 28, 2016
projection.hpp Add the ability to tippecanoe-decode into EPSG:3857 instead of WGS84 Jun 28, 2016
serial.cpp Save another byte in features that have no metadata Nov 17, 2016
serial.hpp Add an option to drop the smallest features to make tiles small enough Nov 10, 2016
text.cpp Fix some compiler warnings about signed comparisons Oct 15, 2016
text.hpp Make UTF-8 checking into a unit test with Catch Oct 5, 2016
tile-join.cpp Don't allow two attributes with the same name, and strip \r from CSV. Dec 13, 2016
tile.cpp Fix warnings identified by g++ Dec 14, 2016
tile.hpp Remove unused layer count and layer name list Aug 30, 2016
unit.cpp Forgot to test the emoji case Oct 5, 2016
vector_tile.proto Add vector tile boilerplate Sep 22, 2014
version.hpp Upgrade Wagyu to cfc895 and use its Sutherland-Hodgman implementation Jan 11, 2017

README.md

tippecanoe

Builds vector tilesets from large (or small) collections of GeoJSON features, like these.

Build Status Coverage Status

Intent

The goal of Tippecanoe is to enable making a scale-independent view of your data, so that at any level from the entire world to a single building, you can see the density and texture of the data rather than a simplification from dropping supposedly unimportant features or clustering or aggregating them.

If you give it all of OpenStreetMap and zoom out, it should give you back something that looks like "All Streets" rather than something that looks like an Interstate road atlas.

If you give it all the building footprints in Los Angeles and zoom out far enough that most individual buildings are no longer discernable, you should still be able to see the extent and variety of development in every neighborhood, not just the largest downtown buildings.

If you give it a collection of years of tweet locations, you should be able to see the shape and relative popularity of every point of interest and every significant travel corridor.

Installation

The easiest way to install tippecanoe on OSX is with Homebrew:

$ brew install tippecanoe

Usage

$ tippecanoe -o file.mbtiles [file.json ...]

If no files are specified, it reads GeoJSON from the standard input. If multiple files are specified, each is placed in its own layer.

The GeoJSON features need not be wrapped in a FeatureCollection. You can concatenate multiple GeoJSON features or files together, and it will parse out the features and ignore whatever other objects it encounters.

Options

Naming

  • -l name or --layer=name: Layer name (default "file" if source is file.json or output is file.mbtiles). If there are multiple input files specified, the files are all merged into the single named layer, even if they try to specify individual names with -L.
  • -L name:file.json or --named-layer=name:file.json: Specify layer names for individual files. If your shell supports it, you can use a subshell redirect like -L name:<(cat dir/*.json) to specify a layer name for the output of streamed input.
  • -n name or --name=name: Human-readable name for the tileset (default file.json)
  • -A text or --attribution=text: Attribution (HTML) to be shown with maps that use data from this tileset.

File control

  • -o file.mbtiles or --output=file.mbtiles: Name the output file.
  • -f or --force: Delete the mbtiles file if it already exists instead of giving an error
  • -F or --allow-existing: Proceed (without deleting existing data) if the metadata or tiles table already exists or if metadata fields can't be set
  • -t directory or --temporary-directory=directory: Put the temporary files in directory. If you don't specify, it will use /tmp.
  • -P or --read-parallel: Use multiple threads to read different parts of each input file at once. This will only work if the input is line-delimited JSON with each Feature on its own line, because it knows nothing of the top-level structure around the Features. Spurious "EOF" error messages may result otherwise. Performance will be better if the input is a named file that can be mapped into memory rather than a stream that can only be read sequentially.

Zoom levels and resolution

  • -z zoom or --maximum-zoom=zoom: Maxzoom: the highest zoom level for which tiles are generated (default 14)
  • -Z zoom or --minimum-zoom=zoom: Minzoom: the lowest zoom level for which tiles are generated (default 0)
  • -B zoom or --base-zoom=zoom: Base zoom, the level at and above which all points are included in the tiles (default maxzoom). If you use -Bg, it will guess a zoom level that will keep at most 50,000 features in the densest tile. You can also specify a marker-width with -Bgwidth to allow fewer features in the densest tile to compensate for the larger marker, or -Bfnumber to allow at most number features in the densest tile.
  • -d detail or --full-detail=detail: Detail at max zoom level (default 12, for tile resolution of 4096)
  • -D detail or --low-detail=detail: Detail at lower zoom levels (default 12, for tile resolution of 4096)
  • -m detail or --minimum-detail=detail: Minimum detail that it will try if tiles are too big at regular detail (default 7)
  • -b pixels or --buffer=pixels: Buffer size where features are duplicated from adjacent tiles. Units are "screen pixels"--1/256th of the tile width or height. (default 5)
  • -s projection or --projection=projection: Specify the projection of the input data. Currently supported are EPSG:4326 (WGS84, the default) and EPSG:3857 (Web Mercator).
  • -M bytes or --maximum-tile-bytes=bytes: Use the specified number of bytes as the maximum compressed tile size instead of 500K.

All internal math is done in terms of a 32-bit tile coordinate system, so 1/(2^32) of the size of Earth, or about 1cm, is the smallest distinguishable distance. If maxzoom + detail > 32, no additional resolution is obtained than by using a smaller maxzoom or detail.

Properties

  • -x name or --exclude=name: Exclude the named properties from all features
  • -y name or --include=name: Include the named properties in all features, excluding all those not explicitly named
  • -X or --exclude-all: Exclude all properties and encode only geometries

Point simplification

  • -r rate or --drop-rate=rate: Rate at which dots are dropped at zoom levels below basezoom (default 2.5). If you use -rg, it will guess a drop rate that will keep at most 50,000 features in the densest tile. You can also specify a marker-width with -rgwidth to allow fewer features in the densest tile to compensate for the larger marker, or -rfnumber to allow at most number features in the densest tile.
  • -g gamma or --gamma=gamma: Rate at which especially dense dots are dropped (default 0, for no effect). A gamma of 2 reduces the number of dots less than a pixel apart to the square root of their original number.

Line and polygon simplification

  • -S scale or --simplification=scale: Multiply the tolerance for line and polygon simplification by scale. The standard tolerance tries to keep the line or polygon within one tile unit of its proper location. You can probably go up to about 10 without too much visible difference.

Doing more

  • -ac or --coalesce: Coalesce adjacent line and polygon features that have the same properties. Note that when overlapping polygons are coalesced, the overlapping region is treated as a hole, which may not be what you want.
  • -ar or --reverse: Try reversing the directions of lines to make them coalesce and compress better
  • -ao or --reorder: Reorder features to put ones with the same properties in sequence, to try to get them to coalesce
  • -al or --drop-lines: Let "dot" dropping at lower zooms apply to lines too
  • -ap or --drop-polygons: Let "dot" dropping at lower zooms apply to polygons too
  • -ag or --calculate-feature-density: Add a new attribute, tippecanoe_feature_density, to each feature, to record how densely features are spaced in that area of the tile. You can use this attribute in the style to produce a glowing effect where points are densely packed. It can range from 0 in the sparsest areas to 255 in the densest.
  • -ab or --detect-shared-borders: In the manner of TopoJSON, detect borders that are shared between multiple polygons and simplify them identically in each polygon. This takes more time and memory than considering each polygon individually.
  • -aG or --increase-gamma-as-needed: If a tile is too large, try to reduce it to under 500K by increasing the -g gamma. The discovered gamma applies to the entire zoom level.
  • -as or --drop-densest-as-needed: If a tile is too large, try to reduce it to under 500K by increasing the minimum spacing between features. The discovered spacing applies to the entire zoom level.
  • -ad or --drop-fraction-as-needed: Dynamically drop some fraction of features from each zoom level to keep large tiles under the 500K size limit. (This is like -pd but applies to the entire zoom level, not to each tile.)
  • -an or --drop-smallest-as-needed: Dynamically drop the smallest features (physically smallest: the shortest lines or the smallest polygons) from each zoom level to keep large tiles under the 500K size limit. This option will not work for point features.
  • -aL or --grid-low-zooms: At all zoom levels below maxzoom, snap all lines and polygons to a stairstep grid instead of allowing diagonals. You will also want to specify a tile resolution, probably -D8. This option provides a way to display continuous parcel, gridded, or binned data at low zooms without overwhelming the tiles with tiny polygons, since features will either get stretched out to the grid unit or lost entirely, depending on how they happened to be aligned in the original data.

Doing less

  • -ps or --no-line-simplification: Don't simplify lines
  • -pS or --simplify-only-low-zooms: Don't simplify lines at maxzoom (but do simplify at lower zooms)
  • -pf or --no-feature-limit: Don't limit tiles to 200,000 features
  • -pk or --no-tile-size-limit: Don't limit tiles to 500K bytes
  • -pd or --force-feature-limit: Dynamically drop some fraction of features from large tiles to keep them under the 500K size limit. It will probably look ugly at the tile boundaries. (This is like -ad but applies to each tile individually, not to the entire zoom level.)
  • -pi or --preserve-input-order: Preserve the original input order of features as the drawing order instead of ordering geographically. (This is implemented as a restoration of the original order at the end, so that dot-dropping is still geographic, which means it also undoes -ao).
  • -pp or --no-polygon-splitting: Don't split complex polygons (over 700 vertices after simplification) into multiple features.
  • -pc or --no-clipping: Don't clip features to the size of the tile. If a feature overlaps the tile's bounds or buffer at all, it is included completely. Be careful: this can produce very large tilesets, especially with large polygons.
  • -pD or --no-duplication: As with --no-clipping, each feature is included intact instead of cut to tile boundaries. In addition, it is included only in a single tile per zoom level rather than potentially in multiple copies. Clients of the tileset must check adjacent tiles (possibly some distance away) to ensure they have all features.
  • -pt or --no-tiny-polygon-reduction: Don't combine the area of very small polygons into small squares that represent their combined area.
  • -q or --quiet: Work quietly instead of reporting progress

Example

$ tippecanoe -o alameda.mbtiles -l alameda -n "Alameda County from TIGER" -z13 tl_2014_06001_roads.json
$ cat tiger/tl_2014_*_roads.json | tippecanoe -o tiger.mbtiles -l roads -n "All TIGER roads, one zoom" -z12 -Z12 -d14 -x LINEARID -x RTTYP

GeoJSON extension

Tippecanoe defines a GeoJSON extension that you can use to specify the minimum and/or maximum zoom level at which an individual feature will be included in the vector tileset being produced. If you have a feature like this:

{
    "type" : "Feature",
    "tippecanoe" : { "maxzoom" : 9, "minzoom" : 4 },
    "properties" : { "FULLNAME" : "N Vasco Rd" },
    "geometry" : {
        "type" : "LineString",
        "coordinates" : [ [ -121.733350, 37.767671 ], [ -121.733600, 37.767483 ], [ -121.733131, 37.766952 ] ]
    }
}

with a tippecanoe object specifiying a maxzoom of 9 and a minzoom of 4, the feature will only appear in the vector tiles for zoom levels 4 through 9. Note that the tippecanoe object belongs to the Feature, not to its properties. If you specify a minzoom for a feature, it will be preserved down to that zoom level even if dot-dropping with -r would otherwise have dropped it.

You can also specify a layer name in the tippecanoe object, which will take precedence over the filename or name specified using --layer, like this:

{
    "type" : "Feature",
    "tippecanoe" : { "layer" : "streets" },
    "properties" : { "FULLNAME" : "N Vasco Rd" },
    "geometry" : {
        "type" : "LineString",
        "coordinates" : [ [ -121.733350, 37.767671 ], [ -121.733600, 37.767483 ], [ -121.733131, 37.766952 ] ]
    }
}

Point styling

To provide a consistent density gradient as you zoom, the Mapbox Studio style needs to be coordinated with the base zoom level and dot-dropping rate. You can use this shell script to calculate the appropriate marker-width at high zoom levels to match the fraction of dots that were dropped at low zoom levels.

If you used -B or -z to change the base zoom level or -r to change the dot-dropping rate, replace them in the basezoom and rate below.

awk 'BEGIN {
    dotsize = 2;    # up to you to decide
    basezoom = 14;  # tippecanoe -z 14
    rate = 2.5;     # tippecanoe -r 2.5

    print "  marker-line-width: 0;";
    print "  marker-ignore-placement: true;";
    print "  marker-allow-overlap: true;";
    print "  marker-width: " dotsize ";";
    for (i = basezoom + 1; i <= 22; i++) {
        print "  [zoom >= " i "] { marker-width: " (dotsize * exp(log(sqrt(rate)) * (i - basezoom))) "; }";
    }

    exit(0);
}'

Geometric simplifications

At every zoom level, line and polygon features are subjected to Douglas-Peucker simplification to the resolution of the tile.

For point features, it drops 1/2.5 of the dots for each zoom level above the point base zoom (which is normally the same as the -z max zoom, but can be a different zoom specified with -B if you have precise but sparse data). I don't know why 2.5 is the appropriate number, but the densities of many different data sets fall off at about this same rate. You can use -r to specify a different rate.

You can use the gamma option to thin out especially dense clusters of points. For any area where dots are closer than one pixel together (at whatever zoom level), a gamma of 3, for example, will reduce these clusters to the cube root of their original density.

For line features, it drops any features that are too small to draw at all. This still leaves the lower zooms too dark (and too dense for the 500K tile limit, in some places), so I need to figure out an equitable way to throw features away.

Unless you specify --no-tiny-polygon-reduction, any polygons that are smaller than a minimum area (currently 4 square subpixels) will have their probability diffused, so that some of them will be drawn as a square of this minimum size and others will not be drawn at all, preserving the total area that all of them should have had together.

Any polygons that have over 700 vertices after line simplification will be split into multiple features so they can be rendered efficiently, unless you use -pp to prevent this.

Features in the same tile that share the same type and attributes are coalesced together into a single geometry if you use --coalesce. You are strongly encouraged to use -x to exclude any unnecessary properties to reduce wasted file size.

If a tile is larger than 500K, it will try encoding that tile at progressively lower resolutions before failing if it still doesn't fit.

Development

Requires sqlite3 and zlib (should already be installed on MacOS). Rebuilding the manpage uses md2man (gem install md2man).

Linux:

sudo apt-get install build-essential libsqlite3-dev zlib1g-dev

Then build:

make

and perhaps

make install

Tippecanoe now requires features from the 2014 C++ standard. If your compiler is older than that, you will need to install a newer one. On MacOS, updating to the lastest XCode should get you a new enough version of clang++. On Linux, you should be able to upgrade g++ with

sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
sudo apt-get update -y
sudo apt-get install -y g++-5
export CXX=g++-5

Examples

Check out some examples of maps made with tippecanoe

Name

The name is a joking reference to a "tiler" for making map tiles.

tile-join

Tile-join is a tool for joining new attributes from a CSV file to features that have already been tiled with tippecanoe. It reads the tiles from an existing .mbtiles file, matches them against the records of the CSV, and writes out a new tileset.

If you specify multiple source mbtiles files, they are all read and their combined contents are written to the new mbtiles output. If they define the same layers or the same tiles, the layers or tiles are merged.

The options are:

  • -o out.mbtiles: Write the new tiles to the specified .mbtiles file
  • -f: Remove out.mbtiles if it already exists
  • -c match.csv: Use match.csv as the source for new attributes to join to the features. The first line of the file should be the key names; the other lines are values. The first column is the one to match against the existing features; the other columns are the new data to add.
  • -x key: Remove attributes of type key from the output. You can use this to remove the field you are matching against if you no longer need it after joining, or to remove any other attributes you don't want.
  • -i: Only include features that matched the CSV.
  • -pk: Don't skip tiles larger than 500K.

Because tile-join just copies the geometries to the new .mbtiles without processing them (except to rescale the extents if necessary), it doesn't have any of tippecanoe's recourses if the new tiles are bigger than the 500K tile limit. If a tile is too big and you haven't specified -pk, it is just left out of the new tileset.

Example

Imagine you have a tileset of census blocks:

curl -O http://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl_2010_06001_tabblock10.zip
unzip tl_2010_06001_tabblock10.zip
ogr2ogr -f GeoJSON tl_2010_06001_tabblock10.json tl_2010_06001_tabblock10.shp
./tippecanoe -o tl_2010_06001_tabblock10.mbtiles tl_2010_06001_tabblock10.json

and a CSV of their populations:

curl -O http://www2.census.gov/census_2010/01-Redistricting_File--PL_94-171/California/ca2010.pl.zip
unzip -p ca2010.pl.zip cageo2010.pl |
awk 'BEGIN {
    print "GEOID10,population"
}
(substr($0, 9, 3) == "750") {
    print "\"" substr($0, 28, 2) substr($0, 30, 3) substr($0, 55, 6) substr($0, 62, 4) "\"," (0 + substr($0, 328, 9))
}' > population.csv

which looks like this:

GEOID10,population
"060014277003018",0
"060014283014046",0
"060014284001020",0
...
"060014507501001",202
"060014507501002",119
"060014507501003",193
"060014507501004",85
...

Then you can join those populations to the geometries and discard the no-longer-needed ID field:

./tile-join -o population.mbtiles -x GEOID10 -c population.csv tl_2010_06001_tabblock10.mbtiles

tippecanoe-enumerate

The tippecanoe-enumerate utility lists the tiles that an mbtiles file defines. Each line of the output lists the name of the mbtiles file and the zoom, x, and y coordinates of one of the tiles. It does basically the same thing as

select zoom_level, tile_column, (1 << zoom_level) - 1 - tile_row from tiles;

on the file in sqlite3.

tippecanoe-decode

The tippecanoe-decode utility turns vector mbtiles back to GeoJSON. You can use it either on an entire file:

tippecanoe-decode file.mbtiles

or on an individual tile:

tippecanoe-decode file.mbtiles zoom x y
tippecanoe-decode file.vector.pbf zoom x y

If you decode an entire file, you get a nested FeatureCollection identifying each tile and layer separately. Note that the same features generally appear at all zooms, so the output for the file will have many copies of the same features at different resolutions.

Options

  • -t projection: Specify the projection of the output data. Currently supported are EPSG:4326 (WGS84, the default) and EPSG:3857 (Web Mercator).