天地图 ZXY 瓦片下载工具

一个用于批量下载天地图（国家地理信息公共服务平台）矢量底图瓦片的 Python 工具。

功能特性

• ✅ 支持多种底图类型：矢量底图(vec)、矢量注记(cva)、影像底图(img)、影像注记(cia)、地形晕渲(ter)、地形注记(cta)、全球境界(ibo)
• ✅ 支持球面墨卡托投影（Web Mercator，EPSG:3857）
• ✅ 支持层级范围下载（z_min 到 z_max）
• ✅ 支持 Web Mercator (EPSG:3857) 坐标输入
• ✅ 支持经纬度坐标输入（自动转换为 Web Mercator，EPSG:3857）
• ✅ 多 Token 轮换管理，避免请求限制
• ✅ 并发下载，提高下载速度
• ✅ 自动重试和错误处理
• ✅ 断点续传，跳过已下载的瓦片

项目结构

tilesMap/
├── main.py              # 主程序入口
├── config.py            # 配置文件（URL模板、TOKENS、常量）
├── token_manager.py     # Token 轮换管理模块
├── coordinate.py        # 坐标转换模块
├── downloader.py        # 下载逻辑模块
├── requirements.txt     # 项目依赖
├── README.md           # 项目说明
└── .gitignore          # Git 忽略文件

安装依赖

pip install -r requirements.txt

使用方法

底图类型和投影说明

底图类型 (LayerType)：

• VEC: 矢量底图
• CVA: 矢量注记
• IMG: 影像底图
• CIA: 影像注记
• TER: 地形晕渲
• CTA: 地形注记
• IBO: 全球境界

投影方式 (Projection)：

• W: 球面墨卡托投影 (_w，Web Mercator，EPSG:3857)

注意：经纬度输入会自动转换为 Web Mercator (EPSG:3857) 坐标，然后使用球面墨卡托投影下载。

方式1：使用经纬度坐标下载

from downloader import download_by_lonlat_range
from config import LayerType, Projection

# 下载矢量底图（经纬度会自动转换为 Web Mercator）
download_by_lonlat_range(
    z_min=10,
    z_max=12,
    lon_min=121.0,
    lon_max=122.0,
    lat_min=29.5,
    lat_max=30.5,
    layer_type=LayerType.VEC,
)

# 下载影像底图
download_by_lonlat_range(
    z_min=10,
    z_max=12,
    lon_min=121.0,
    lon_max=122.0,
    lat_min=29.5,
    lat_max=30.5,
    layer_type=LayerType.IMG,
)

方式2：使用 Web Mercator 坐标

from downloader import download_by_mercator_range
from config import LayerType, Projection

download_by_mercator_range(
    z_min=10,
    z_max=12,
    mercator_x_min=13480000,   # Web Mercator X 最小值（米）
    mercator_x_max=13580000,   # Web Mercator X 最大值（米）
    mercator_y_min=3440000,    # Web Mercator Y 最小值（米）
    mercator_y_max=3540000,    # Web Mercator Y 最大值（米）
    layer_type=LayerType.VEC,
)

方式3：使用瓦片坐标

from downloader import download_range
from config import LayerType, Projection

download_range(
    z=12,
    x_min=3370, x_max=3380,
    y_min=1550, y_max=1560,
    layer_type=LayerType.VEC,
)

运行项目

python main.py

配置说明

在 config.py 中可以修改以下配置：

• TOKENS: API Token 列表
• MAX_REQ_PER_TOKEN: 每个 token 的最大请求次数
• OUT_DIR: 输出目录（会根据底图类型和投影自动创建子目录，如 vec_w/、img_w/）
• MAX_WORKERS: 并发线程数
• RETRIES: 失败重试次数
• TIMEOUT: 请求超时时间
• SLEEP_JITTER: 请求间隔抖动范围
• DEFAULT_LAYER_TYPE: 默认底图类型（LayerType.VEC）
• DEFAULT_PROJECTION: 默认投影方式（Projection.W，球面墨卡托）

模块说明

• config.py: 存放所有配置常量，包括底图类型和投影枚举
• token_manager.py: Token 管理器，负责 token 轮换和使用计数
• coordinate.py: 坐标转换工具（经纬度 ↔ Web Mercator ↔ 瓦片坐标）
• downloader.py: 核心下载逻辑，包含所有下载相关函数，支持多种底图类型和投影
• main.py: 程序入口，包含使用示例

输出目录结构

下载的瓦片会按照以下结构存储：

tiles/
├── vec_w/          # 矢量底图（球面墨卡托）
│   └── z/
│       └── x/
│           └── y.png
├── img_w/          # 影像底图（球面墨卡托）
├── cva_w/          # 矢量注记（球面墨卡托）
└── ...

开发说明

• Python 版本要求：3.7+
• 使用虚拟环境推荐：python -m venv venv