Tippecanoe矢量切片的命令行參數解析

使用 GeoJSON數據建立 矢量瓦片

目的

根據你的數據創造一個可自由縮放的視圖

安裝

最簡單的安裝方式是在OSX使用 Homebrew:

$ brew install tippecanoe

也能夠直接下載源碼包，而後經過make && make install直接編譯安裝。

用法

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