tippecanoe

tippecanoe

使用 GeoJSON数据创建 矢量瓦片

目的

根据你的数据创造一个可自由缩放的视图

安装

最简单的安装方式是在OSX使用 Homebrew:

$ brew install tippecanoe

用法

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

如果没有指定GeoJSON文件，它将会从标准输入读取。
如果指定了多个文件，每个文件都会创建一个对应的图层。

选项

tippecanoe提供了众多选项。大多数时候不需要指定额外的选项参数，只需要通过 -o output.mbtiles 指定输出文件名，或者 -f 来删除已经存在的文件。

如果你不确定所使用数据的最大级别，可以使用 -zg 来根据数据密度自动估算一个级别。

如果你的数据包含点状要素，通常需要使用-Bg来自动计算一个基准级别做数据抽稀。如果这种方式对你无效，可以尝试使用-r1 --drop-fraction-as-needed 关闭传统的抽稀方法，而仅仅在瓦片太大时才做抽稀。

如果你的数据包含点状要素或面状要素，你可能需要使用--drop-densest-as-needed 来舍弃一些要素，让其可以在低级别显示。

如果你的数据包含大量的属性信息，可以使用-y 来指定你需要的属性。

瓦片输出

• -o file.mbtiles 或者 --output=file.mbtiles： 指定输出文件名称
• -e directory 或者 --output-to-directory=directory： 将瓦片文件输出到指定的directory 文件夹，而不是mbtiles
• -f 或者 --force： 如果指定的mbtiles已存在，则删除，否则抛出错误
• -F 或者 --allow-existing： 忽略元数据或瓦片已存在的情况，一般不推荐使用

瓦片描述和权属信息

• -n name 或者 --name=name：瓦片集的名称
• -A text 或者 --attribution=text：使用瓦片数据时，显示在地图上的权属信息 (HTML格式)
• -N description 或者 --description=description： 瓦片集的描述信息 (默认 file.mbtiles)

输入文件和图层名

• name.json 或者 name.geojson： 读取指定的文件到一个名为name的图层
• -l name 或者 --layer=name：使用指定的图层名，如果输入的有多个文件，则这些文件将会被合并到一个图层
• -L name:file.json 或者 --named-layer=name:file.json： 为每一个单独的文件指定一个图层名

输入文件的并行处理

• -P 或者 --read-parallel: 使用多线程读取一个文件的不同部分
  该选项只对新行分隔（每个要素为一行）的json文件有效。否则将会返回一个“EOF”错误。

输入文件的投影

• -s projection 或者 --projection=projection：为输入的数据指定一个投影。目前仅支持 EPSG:4326 (WGS84, 默认) 和 EPSG:3857 (Web墨卡托)。

缩放级别

• -z zoom 或者 --maximum-zoom=zoom：切片的最大级别（默认14）
• -zg 或者 --maximum-zoom=g： 根据要素分布自动估算最大级别
• -Z zoom 或者 --minimum-zoom=zoom：切片的最小级别（默认0）

瓦片分辨率

• -d detail 或者 --full-detail=detail： 在最大级别时的“详细程度” (默认 12, 对应的分辨率为4096)
• -D detail 或者 --low-detail=detail：在最大级别时的“详细程度”(默认 12, 对应的分辨率为4096)
• -m detail 或者 --minimum-detail=detail： “详细程度”下限，如果在标准“详细程度”下瓦片太大将会尝试的最小“详细程度” (默认 7，对应的分辨率为128)

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.

过滤要素属性

• -x name 或者 --exclude=name： 剔除的属性字段
• -y name 或者 --include=name： 包含的属性字段，其他字段都将被剔除
• -X 或者 --exclude-all: 剔除所有字段，仅仅编码“geometry”字段
• -Tattribute:type 或者 --attribute-type=attribute:type: 强制将要素的 attribute 属性类型转换为指定的 type 类型。
  type 的取值范围： string, float, int, 或 bool。 如果是 bool，那么原始属性中的0、 false、 null、或者空字符串都会被转为false，其它都被转为 true。 如果是 float 或 int 并且原始数据为非数字，则会被转为0。如果是 int 并且原始数据为浮点型，将会被转为与其最接近的整数。

根据缩放级别舍弃部分要素

• -r rate 或者 --drop-rate=rate： 在基准级别以下的瓦片中被舍弃的点的比例(默认 2.5)。 如果使用 -rg，将会估算一个弃置比，保持瓦片中最多包含50,000个要素。同时也可以使用-rgwidth 指定一个注记宽度来允许瓦片中保持较少的要素，以适应较大的注记或标记，也可以使用-rfnumber 来设置瓦片中最多包含的要素数量。
• -B zoom 或者 --base-zoom=zoom：基准级别，基准级别及以上的瓦片将不做点状数据的抽稀 (默认为最大级别）。 如果使用了 -Bg， 将会根据最大要素数50,000估算基准级别。同时也可以使用-Bgwidth 指定一个注记宽度来允许瓦片中保持较少的要素，以适应较大的注记或标记，也可以使用-Bfnumber 来设置瓦片中最多包含的要素数量。
• -al 或者 --drop-lines： 让线要素跟点要素一样，在低级别做数据抽稀
• -ap 或者 --drop-polygons: 让面要素跟点要素一样，在低级别做数据抽稀

舍弃一小部分要素来保持瓦片大小不超限

• -as 或者--drop-densest-as-needed：如果瓦片太大，尝试增加要素之间的最小间隔来将瓦片大小控制在500kb以下。这种显示间距将会被应用到所有级别的瓦片。
• -ad 或者 --drop-fraction-as-needed：从每一个级别动态舍弃一部分要素来保持瓦片大小不超过500kb限制。 (类似于-pd ，但是是应用于整个级别，而不是每一个瓦片)
• -an 或者 --drop-smallest-as-needed：从每一个级别动态舍弃最小的要素(物理上的最小：最短的线或最小的面)来保持瓦片大小不超过500kb限制。 该选项对点状要素无效。
• -pd 或者 --force-feature-limit： 动态舍弃部分要素来保持瓦片大小不超过500kb限制(该选项与 -ad 类似，但是是针对每个单独的瓦片，而不是整个缩放级别)。该选项可能会导致瓦片边界区域比较难看，一般情况不建议使用。

舍弃紧密交错的要素

• -g gamma 或者 --gamma=_gamma_：特别密集的点将会被丢弃的比例 (默认 0，不丢弃)。gamma值为2表示减少小于一个像素的点，直到其数量减少到原始数量的平方根（译者注：不确定该翻译是否准确）。
• -aG 或者 --increase-gamma-as-needed：如果瓦片太大，尝试使用-g增加gamma值来将瓦片大小控制在500kb以下。这个gamma值将会被应用到整个缩放级别，一般情况下会使用 --drop-densest-as-needed代替该命令。

线和面的简化

• -S scale 或者 --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.
• -ps 或者 --no-line-simplification: 禁止简化线和面
• -pS 或者 --simplify-only-low-zooms: 禁止在最大级别简化线和面 (在低级别仍然执行简化)
• -pt 或者 --no-tiny-polygon-reduction: Don’t combine the area of very small polygons into small squares that represent their combined area.

尝试改善多边形的公共边

• -ab 或者 --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.
• -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. You probably don’t want to use this.

Controlling clipping to tile boundaries

• -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)
• -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.

Reordering features within each tile

• -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).
• -ao or --reorder: Reorder features to put ones with the same properties in sequence, to try to get them to coalesce. You probably don’t want to use this.
• -ac or --coalesce: Coalesce adjacent line and polygon features that have the same properties. You probably don’t want to use this.
• -ar or --reverse: Try reversing the directions of lines to make them coalesce and compress better. You probably don’t want to use this.

添加可计算的属性

• -ag 或者 --calculate-feature-density：添加一个新属性， 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.

尝试修复损坏的数据源

• -aw 或者 --detect-longitude-wraparound： Detect when adjacent points within a feature jump to the other side of the world, and try to fix the geometry.

设置或取消瓦片大小限制

• -M bytes or --maximum-tile-bytes=bytes: Use the specified number of bytes as the maximum compressed tile size instead of 500K.
• -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
• -pC or --no-tile-compression: Don’t compress the PBF vector tile data.

Temporary storage

• -t directory or --temporary-directory=directory: Put the temporary files in directory.
  If you don’t specify, it will use /tmp.

Progress indicator

• -q or --quiet: Work quietly instead of reporting progress

Environment

Tippecanoe ordinarily uses as many parallel threads as the operating system claims that CPUs are available.
You can override this number by setting the TIPPECANOE_MAX_THREADS environmental variable.

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.

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 2011 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.
• -l layer: Include the named layer in the output. You can specify multiple -l options to keep multiple layers. If you don’t specify, they will all be retained.
• -L layer: Remove the named layer from the output. You can specify multiple -L options to remove multiple layers.

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).
• -z maxzoom: Specify the highest zoom level to decode from the tileset
• -Z minzoom: Specify the lowest zoom level to decode from the tileset
• -l layer: Decode only layers with the specified names. (Multiple -l options can be specified.)