openmaptiles/openmaptiles-tools

OpenMapTiles Tools ![Build Status]([] ![]([]

OpenMapTiles 工具箱用于从 OpenMapTiles 图层生成 TM2Source 项目、imposm3 映射和 SQL 指令。我们鼓励其他人也将其用于矢量瓦片项目，因为这种方法对我们非常有效。

查看 https://github.com/openmaptiles/openmaptiles/ 可获取真实世界示例。

使用方法

系统需安装 Docker 或 Python 3，测试还需 Docker-compose。若不使用 Docker，需安装下文列出的额外工具和库。

使用 Docker

最简单的方式是直接使用 Docker 运行命令。无需本地克隆 openmaptiles-tools，只需克隆 https://github.com/openmaptiles/openmaptiles 并从其根目录运行。

注意： 容器脚本只能访问指定目录及其子目录中的文件，例如示例中的 ${PWD}（当前目录）。

bash
docker run -it --rm -u $(id -u ${USER}):$(id -g ${USER}) \
           -v "${PWD}:/tileset" \
           openmaptiles/openmaptiles-tools \
           <脚本名称> <脚本参数>

其中 <脚本名称> 可以是 bin/ 目录中的任何脚本，例如 generate-imposm3 openmaptiles.yaml。

Docker 卷

• 将 PBF 文件挂载到 /import 文件夹
• 将 mapping.yaml 挂载到 /mapping 文件夹
• 若使用差异模式，需将持久化位置挂载到 /cache 文件夹以便后续重用

不使用 Docker

bash
# 部分工具需要这些包。在 Debian/Ubuntu 上可通过以下命令安装
sudo apt install graphviz sqlite3 aria2 osmctools

# 直接从 git 安装包
python3 -m pip install git+https://github.com/openmaptiles/openmaptiles-tools

# 运行所需脚本，例如从 openmaptiles 目录：
generate-imposm3 openmaptiles.yaml

# 若脚本无法运行，确保 PATH 包含默认 PIP 二进制目录。
# 在 Debian/Ubuntu 上通常是 ~/.local/bin/（用户主目录下）。
# 否则直接运行 ~/.local/bin/generate-imposm3 ...

从源码运行

确保已安装 使用方法 部分列出的所有依赖项。需安装最新 Python（3.6+）

bash
# 获取 OpenMapTiles 图层数据
git clone https://github.com/openmaptiles/openmaptiles.git
# 获取工具仓库
git clone https://github.com/openmaptiles/openmaptiles-tools.git
# 从工具仓库根目录运行脚本
cd openmaptiles-tools
# 安装所需依赖（可能需要 sudo 权限）
python3.6 -m pip install -r requirements.txt
# PYTHONPATH=$PWD 允许脚本找到当前目录中的模块
PYTHONPATH=$PWD python3 bin/generate-imposm3 ../openmaptiles/openmaptiles.yaml

数据概念

您可以定义一个自包含的图层，连同 SQL 文件、图层和数据源定义（如 imposm3 映射文件），然后在瓦片集中引用它，与其他图层混合匹配。

定义自己的图层

查看或复制标准图层（如 https://github.com/openmaptiles/openmaptiles/tree/master/layers/building%EF%BC%89%E5%BC%80%E5%A7%8B%E5%88%9B%E5%BB%BA%E8%87%AA%E5%B7%B1%E7%9A%84%E5%9B%BE%E5%B1%82%E3%80%82%E4%B8%80%E4%B8%AA%E5%9B%BE%E5%B1%82%E5%8C%85%E5%90%AB%E4%B8%80%E4%B8%AA%E7%94%A8 YAML 格式编写的图层定义。

在其中指定 layer 属性，如 id、buffer_size 和可能的 Markdown 文档（description 和 fields）。还可在 schema 中引用 SQL 文件，编写图层所需查询或创建通用表。建议每个图层有一个接受边界框和缩放级别的函数，便于测试和重用。

若数据基于 OSM，可直接引用 imposm3 映射文件 选择所需 OSM 数据。

yaml
layer:
  id: "building"
  description: 来自 OpenStreetMap 的建筑物
  buffer_size: 4
  datasource:
    query: (SELECT geometry FROM layer_building(!bbox!, z(!scale_denominator!))) AS t
  fields:
    render_height: 根据建筑物层数和高度估算的高度。
    class:
      description: 定义建筑物的子类（已知值之一）。
      # 值可以是字符串列表或字典
      # 字典定义 OSM 值到 OMT 字段值的映射
      values:
        school:
          # subclass IN ('school','kindergarten') OR subclass LIKE 'uni%'
          subclass: ['school','kindergarten','uni%']
        railway:
          # (subclass='station' AND mapping_key='railway')
          # OR subclass in ('halt','tram_stop','subway')
          - __AND__:
              subclass: 'station'
              mapping_key: 'railway'
          - subclass: ['halt', 'tram_stop', 'subway']
schema:
  - ./building.sql
datasources:
  - type: imposm3
    mapping_file: ./mapping.yaml

对于已知值（枚举），fields 部分还可包含输入（OSM）值的映射。

若图层 SQL 文件包含 %%FIELD_MAPPING: class%%，generate-sql 脚本会将其替换为：

sql
SELECT CASE
    %%FIELD_MAPPING: class%%
END, ...

替换后：

sql
SELECT CASE
    WHEN "subclass" IN ('school', 'kindergarten')
        OR "subclass" LIKE 'uni%' THEN 'school'
    WHEN ("subclass" = 'station' AND "mapping_key" = 'railway')
        OR "subclass" in ('halt','tram_stop','subway') THEN 'railway'
END, ...

定义自己的瓦片集

瓦片集定义矢量瓦片集中包含的图层（layers）以及用于生成 TM2Source 项目的元数据，以实际生成矢量瓦片。

yaml
tileset:
  layers:
    - layers/building/building.yaml
    - layers/housenumber/housenumber.yaml
    - layers/poi/poi.yaml
  name: 街道级别
  description: 显示建筑物、门牌号和兴趣点等街道级别信息的瓦片集。
  attribution: "OpenStreetMap 贡献者"
  maxzoom: 14
  minzoom: 13
  center: [-12.2168, 28.6135, 4]
  bounds: [-180.0,-85.0511,180.0,85.0511]
  pixel_scale: 256
  defaults:
    srs: +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over
    datasource:
      srid: 900913

瓦片测试

瓦片大小和 PostgreSQL 查询速度

使用 test-perf 评估针对 PostgreSQL 数据库的瓦片生成性能。此工具可测试单个图层、多个图层或整个瓦片。提供多个预定义测试区域以确保跨测试一致性。结果以直方图显示瓦片大小分布。可将当前运行结果与之前保存的结果比较，突出显示较大变化。若测试多个缩放级别，另一个直方图显示每个级别的大小分布。使用 --help 查看所有选项。

test-perf <瓦片集> ...

与下文的 postserve 类似，test-perf 需要 PostgreSQL 连接。

!test-perf 示例图

实时瓦片服务器

Postserve 是 OpenMapTiles 矢量瓦片测试服务器，可根据瓦片集文件定义直接从 PostgreSQL 数据库动态生成元数据和瓦片。

postserve <瓦片集> ...

使用 postserve <瓦片集> 启动服务。使用 --help 获取 PostgreSQL 连接参数列表。若数据库包含完整星球数据，可能需要使用 MIN_ZOOM=6 postserve ... 避免意外生成低缩放级别的慢瓦片。

Postserve Docker 快速入门

• 克隆 https://github.com/openmaptiles/openmaptiles%EF%BC%88%E4%BD%BF%E7%94%A8 Docker 无需 openmaptiles-tools 仓库）
• 运行 PostgreSQL 服务器并导入 openmaptiles OSM 数据，例如按照快速入门指南操作
• 运行 docker pull openmaptiles/openmaptiles-tools 下载最新工具版本
• 在 openmaptiles 仓库目录中运行以下命令。（假设 PostgreSQL 在 localhost:5432 运行，若在 Docker 中运行，可能需要将 --net=host 更改为 --net=openmaptiles_postgres_conn 以匹配 openmaptiles 快速入门设置，并通过 -p 8090:8090 将 8090 端口暴露到主机）

docker run -it --rm -u $(id -u ${USER}):$(id -g ${USER}) \
    -v "${PWD}:/tileset" --net=host \
    openmaptiles/openmaptiles-tools \
    postserve openmaptiles.yaml

查看动态瓦片

可使用任何支持 MVT 的查看器查看瓦片，例如：

• https://maputnik.github.io/editor%EF%BC%88%E5%9C%A8%E7%BA%BF%EF%BC%89%E2%80%94%E2%80%94 将数据源更改为 http://localhost:8090
• QGIS 桌面版—— 添加 Vector Tiles Reader 插件，添加矢量瓦片服务器连接，将 TileJSON URL 设置为 http://localhost:8090

检查实时瓦片内容

使用 debug-mvt 工具检查瓦片内容。该工具查询 PostgreSQL 服务器并显示图层、每行数据和几何类型/大小。可限制输出到特定图层，可选显示所有本地化名称，将几何显示为文本。以下示例查询指定瓦片中 "place" 图层的条目：

bash
$ debug-mvt openmaptiles.yaml 4/7/6 -l place
======= Layer place (默认隐藏额外名称列) =======
  capital  class    iso_a2    name                        name_de                     name_en                       rank       osm_id  is_valid_mvt    mvtgeometry    is_valid_geom    geometry
---------  -------  --------  --------------------------  --------------------------  --------------------------  ------  -----------  --------------  -------------  ---------------  ----------
           country  ES        España                      Spanien                     Spain                            1   1483323000  True            POINT(32)      True             POINT(32)
           country  PT        Portugal                    Portugal                    Portugal                         1  23770282470  True            POINT(32)      True             POINT(32)
        4  city               Casablanca                  Casablanca                  Casablanca                       2    257307240  True            POINT(32)      True             POINT(32)
           country  MA        Maroc                       Marokko                     Morocco                          2   4324250410  True            POINT(32)      True             POINT(32)
        2  city               Madrid                      Madrid                      Madrid                           2    210682950  True            POINT(32)      True             POINT(32)
        2  city               Lisboa                      Lissabon                    Lisbon                           3   2659584900  True            POINT(32)      True             POINT(32)
        4  city               Oran                        Oran                        Oran                             4    275651030  True            POINT(32)      True             POINT(32)
        4  city               Valencia                    Valencia                    Valencia                         4    341056070  True            POINT(32)      True             POINT(32)
        4  city               Sevilla                     Sevilla                     Seville                          4   2488206560  True            POINT(32)      True             POINT(32)
        4  city               Fès                         Fès                         Fez                              4   2890354320  True            POINT(32)      True             POINT(32)
        2  city               Rabat                       Rabat                       Rabat                            4   2991208620  True            POINT(32)      True             POINT(32)
        ...

工具

多流 OSM 数据下载器

download-osm 工具可用于下载区域提取文件或整个星球文件，并验证文件内容。整个星球文件从所有可用 OSM 镜像同时下载，以分散镜像负载并提高下载速度。工具确保获取最新版本，验证所有镜像包含相同版本，并用 md5 哈希验证下载。默认不从 OSM 主站下载以减轻其负载。下载器使用 https://aria2.github.io/%E3%80%82%E6%94%AF%E6%8C%81%E4%BB%8E Geofabrik、BBBike、openstreemap.fr 或任意 URL 下载文件。

bash
# 下载最新版本到当前目录
download-osm planet

# 通过向 aria2c 传递 -d 参数下载到目标目录
download-osm planet -- -d ./downloads

# 从 Geofabrik 下载新西兰提取文件及状态文件
download-osm geofabrik new-zealand --state state.txt

# 列出 Geofabrik 所有可用提取文件
download-osm list geofabrik

生成通过 PostGIS 直接创建 MVT 瓦片的 SQL 代码

使用瓦片集定义创建 PostgreSQL 预备语句 或 创建函数 SQL 代码，通过单个 getTile(z,x,y) 查询使用 PostGIS MVT 支持生成 Mapbox 矢量瓦片格式的完整矢量瓦片。

使用 --help 获取所有参数。

注意： 当前 https://github.com/openmaptiles/postgis 镜像（v2.9 及之前版本）对 ST_AsMVT() 支持存在问题。在 PostGIS 更新前，请使用 https://hub.docker.com/r/sophox/postgis%EF%BC%88%E5%9F%BA%E4%BA%8E%E6%9C%80%E6%96%B0 https://hub.docker.com/r/mdillon/postgis 基础镜像）。另一个已知问题是 PostgreSQL JIT 可能导致 PG11+ 中瓦片生成速度极慢，可能需要禁用。

generate-sqltomvt <瓦片集>

生成 Imposm3 映射文件

接收瓦片集定义并生成用于导入 OSM 数据的 imposm3 映射文件。

generate-imposm3 <瓦片集>

生成 SQL 脚本

将图层定义中引用的所有 SQL 组装成可通过 psql 执行的 SQL 脚本。若指定 --dir 选项，生成可并行执行的 .sql 文件。

generate-sql <瓦片集>
generate-sql <瓦片集> --dir <输出目录>

生成 Markdown 文档

接收瓦片集定义并生成 Markdown 文档。

generate-doc <瓦片集>

生成 ETL（提取-转换-加载）图

依赖：graphviz

从 imposm3 映射文件和 SQL 后处理代码中解析 etldoc: graphviz 注释，生成 svg 文件。.dot 和 .svg 文件名前缀为 etl_

generate-etlgraph <瓦片集>  <目标目录>
generate-etlgraph layers/landcover/landcover.yaml  ./build/devdoc
generate-etlgraph layers/railway/railway.yaml      ./build/etlgraph

示例：

输入命令：generate-etlgraph layers/landcover/landcover.yaml 输出文件：

• layers/landcover/etl_landcover.dot
• layers/landcover/etl_landcover.svg

生成给定图层和缩放级别的 SQL 查询

示例：

generate-sqlquery layers/landcover/landcover.yaml  14

导入和更新 OSM 数据

import-osm、`update-os