metacollin/tippecanoe

Tippecanoe

镜像概述和主要用途

Tippecanoe是Mapbox开发的工具，用于从大型（或小型）GeoJSON、Geobuf或CSV特征集合构建矢量瓦片集。其核心目标是实现数据的尺度无关视图，使得在从全球到单个建筑的任何缩放级别，都能展示数据的密度和纹理，而非通过丢弃所谓不重要的特征、聚类或聚合进行简化。

核心功能和特性

• 多格式输入支持：兼容GeoJSON、Geobuf和CSV格式的地理数据
• 尺度无关视图：在不同缩放级别保持数据特征的密度和纹理，避免过度简化
• 智能缩放级别管理：通过-zg选项自动选择合理的最大缩放级别，或手动指定最小/最大缩放范围
• 灵活的特征处理：提供特征丢弃（--drop-densest-as-needed）、合并（--coalesce-densest-as-needed）、聚类（--cluster-distance）等策略
• 自定义图层配置：支持指定图层名称、描述，合并或分离多源数据图层
• 属性控制：可筛选、转换和累积特征属性，优化瓦片大小
• 并行处理：支持多线程读取输入数据，提升处理效率
• 多投影支持：兼容WGS84（EPSG:4326）和Web Mercator（EPSG:3857）投影

使用场景和适用范围

• 大型地理数据集处理：如OpenStreetMap全量数据、城市建筑足迹、社交媒体位置数据等
• 多尺度地图可视化：需要在全球到局部范围内均保持数据细节的应用
• 数据密度分析：展示区域发展程度、交通流量、人口分布等空间模式
• 地图瓦片生成：为Web地图、移动地图应用提供矢量瓦片数据源

安装方法

OSX系统

通过Homebrew安装：

sh
brew install tippecanoe

Ubuntu系统

从源码构建：

sh
git clone https://github.com/mapbox/tippecanoe.git
cd tippecanoe
make -j
make install

使用方法

基本命令格式：

sh
tippecanoe -o file.mbtiles [options] [file.json file.json.gz file.geobuf ...]

• 未指定输入文件时，从标准输入读取GeoJSON
• 多个输入文件将分别生成独立图层
• GeoJSON特征无需包裹在FeatureCollection中，可直接拼接多个特征或文件

推荐初始命令

若不确定选项配置，建议先使用：

sh
tippecanoe -zg -o out.mbtiles --drop-densest-as-needed in.geojson

• -zg：自动选择反映数据精度的最大缩放级别
• --drop-densest-as-needed：若瓦片过大，自动丢弃各缩放级别中最不明显的特征

使用示例

创建Alameda县道路瓦片集

sh
tippecanoe -o alameda.mbtiles -l alameda -n "Alameda County from TIGER" -z13 tl_2014_06001_roads.json

• -l alameda：指定图层名称为"alameda"
• -n：设置瓦片集描述
• -z13：最大缩放级别设为13

全球铁路网络瓦片集

sh
curl -L -O https://www.naturalearthdata.com/http//www.naturalearthdata.com/download/10m/cultural/ne_10m_railroads.zip
unzip ne_10m_railroads.zip
ogr2ogr -f GeoJSON ne_10m_railroads.geojson ne_10m_railroads.shp

tippecanoe -zg -o ne_10m_railroads.mbtiles --drop-densest-as-needed --extend-zooms-if-still-dropping ne_10m_railroads.geojson

• --extend-zooms-if-still-dropping：若高缩放级别瓦片仍过大，自动增加缩放级别直至所有特征可被表示

聚类城市人口数据

sh
curl -L -O https://www.naturalearthdata.com/http//www.naturalearthdata.com/download/10m/cultural/ne_10m_populated_places.zip
unzip -o ne_10m_populated_places.zip
ogr2ogr -f GeoJSON ne_10m_populated_places.geojson ne_10m_populated_places.shp

tippecanoe -zg -o ne_10m_populated_places.mbtiles -r1 --cluster-distance=10 --accumulate-attribute=POP_MAX:sum ne_10m_populated_places.geojson

• -r1：禁用低缩放级别点特征自动丢弃
• --cluster-distance=10：聚类距离设为10像素
• --accumulate-attribute=POP_MAX:sum：聚类特征的POP_MAX（人口）属性求和

主要选项说明

输出控制

• -o file.mbtiles：指定输出MBTiles文件路径
• -e directory：输出到目录而非MBTiles文件
• -f：覆盖现有文件
• -F：允许保留现有元数据或瓦片表（不推荐）

瓦片集元数据

• -n name：瓦片集名称（默认从文件名推导）
• -A text：归属信息（HTML格式）
• -N description：瓦片集描述

图层配置

• -l name：指定单个图层名称，合并多输入文件到该图层
• -L name:file：为单个文件指定图层名
• -L{JSON}：通过JSON对象配置图层，如-L'{"file":"data.json", "layer":"cities", "description":"City points"}'

缩放级别设置

• -z zoom：最大缩放级别（默认14）
• -Z zoom：最小缩放级别（默认0）
• -zg：自动猜测合理的最大缩放级别
• -ae：若特征在最大缩放级别仍被丢弃，自动增加缩放级别

属性处理

• -x attribute：排除指定属性（可多次使用）
• -y attribute：仅保留指定属性（可多次使用）
• -X：排除所有属性，仅保留几何信息
• -E attribute:operation：累积属性值（支持sum/product/mean/max/min等）

特征过滤

• -j filter：使用Mapbox GL样式过滤器筛选特征，如-j '{"*": [">=", "$zoom", 10]}'
• -J filter-file：从文件读取过滤器配置

瓦片分辨率

• -d detail：最大缩放级别细节（默认12，对应4096像素分辨率）
• -D detail：低缩放级别细节（默认12）
• -m detail：瓦片过大时的最小细节（默认7）