CityPoster — 城市地图海报生成器

基于 maptoposter 改造，专注中国城市离线地图海报。

安装

git clone https://codeberg.org/songwupei/cityposter.git
cd cityposter
uv sync

依赖

核心依赖：geopandas matplotlib osmnx pyarrow（Parquet 缓存），详见 pyproject.toml。

Shell 补全

# bash
source completions/cityposter.bash

# zsh
fpath=(completions $fpath); autoload -Uz compinit; compinit

SinoGDB 数据 (中国城市离线生成)

新：支持 Parquet 和 GPKG 双后端，自动检测。 首次运行后自动缓存，后续秒出图。

数据源优先级（自动检测，无需手动配置）：

SINOGDB_DIR 自动选择:
├─ ~/Public/GeoData/SinoGDB/    ← Parquet（推荐，3.1GB / zstd）
├─ ~/Downloads/SinoGDB-PackSet_gpkg_*/  ← GPKG（原始，7GB）
└─ ~/NutstoreFiles/8-MyData/GeoData/SinoGDB/  ← 坚果云同步

方式一：Parquet（推荐） — 用 gpkg2parquet.py 将 GPKG 转为 Parquet：

python gpkg2parquet.py ~/Downloads/SinoGDB-PackSet_gpkg_*/ -o ~/Public/GeoData/SinoGDB/
# 7 GB GPKG → 3.1 GB Parquet (zstd)，直接可用

方式二：GPKG 原始格式 — 下载 SinoGDB-PackSet，设置路径：

export SINOGDB_DIR="$HOME/Downloads/SinoGDB-PackSet_gpkg_20260208"

首次运行后，数据自动缓存至 cache/：

缓存一旦建立，即使源数据被删除或移动也能正常渲染。 适合：

• 在多台机器间共享缓存目录
• 构建一次后归档源数据释放磁盘空间
• CI/CD 环境只需缓存文件即可出图

使用

# 中国城市 — 走 SinoGDB（有缓存直接用缓存，无缓存从 GPKG 读取并缓存）
cityposter --lat 39.9042 --lon 116.4074 -dc "北京" -dC "中国" -t noir --poi
cityposter --lat 30.5728 --lon 104.0668 -dc "成都" -dC "中国" -t gongqiang --poi

# 中国城市 — GPKG 和缓存都没有时自动降级到 OSMnx（在线）
cityposter --lat 34.26 --lon 108.94 -dc "西安" -t terracotta

# 国际城市 — 直接走 OSMnx
cityposter -c "Paris" -C "France" -t pastel_dream -d 10000

数据源逻辑

cityposter 会自动选择最佳数据源，优先离线：

中国坐标？
├─ 是 → sinogdb 路径
│   ├─ 有 parquet 缓存？→ ✓ 直接用缓存（离线，秒级）
│   ├─ Parquet 数据在？ → 读取 Parquet + 自动写缓存（推荐）
│   ├─ GPKG 数据在？   → 读取 GPKG + 自动写缓存
│   └─ 都没有
│       ├─ Country 主题 → ❌ 报错（需源数据或预置缓存）
│       └─ City 主题    → ⚠ 降级 OSMnx（在线）
└─ 否 → OSMnx 路径（在线，有 pickle 缓存）

--data-source sinogdb|osmnx 可强制指定数据源，跳过自动检测。

参数

--poi 详情

不加值显示全部，指定类别则只显示选中项：

cityposter ... --poi                    # 全部
cityposter ... --poi subway             # 只看地铁
cityposter ... --poi subway,sightseeing,park  # 地铁+景点+公园
cityposter ... --poi subway,custom       # 地铁 + 自定义 POI

简写对照：

不加 --poi 则不显示任何标注，纯地图。

自定义 POI (--custom-poi)

两处数据源，个人目录优先：

GeoJSON 格式（支持 .json / .geojson）：

{
  "type": "FeatureCollection",
  "coord_type": "gcj02",
  "features": [
    {
      "type": "Feature",
      "properties": {"name": "故宫", "category": "景点"},
      "geometry": {"type": "Point", "coordinates": [116.3972, 39.9163]}
    }
  ]
}

• coord_type: "gcj02" 高德坐标自动转 WGS-84，默认 "wgs84"
• category: 支持中文（"景点"）、英文（"Sightseeing"）、key（"sightseeing_spot"）
• 文件名含城市名 = 城市专属优先加载；不含 = 通用兜底
• _ 或 . 前缀文件忽略（禁用/备份）

| -f | png/svg/pdf | png | | --font-family | Google Fonts | Noto Sans SC(中国) |

主题层级

主题按 themes/{city,province,country}/ 分三级，自动检测中国坐标走 SinoGDB：

province 级别默认启用铁路虚线（railway_dashed），在省级尺度清晰可见。

全国地图 (country/province 主题)

themes/country/ 目录包含全国/大区域主题，只加载铁路+省界数据，支持大半径：

# 全国高铁+省界图（8500km，西安中心，16:9 桌面壁纸）
cityposter --lat 34.26 --lon 108.94 -dc 中国 \
  -t atlas_outline -W 16 -H 9 -d 8500000

# SVG 矢量输出（无限缩放）
cityposter ... -f svg

输出附带 _legend.yaml（颜色图例）、.sh（复现脚本）。GeoJSON/Parquet 导出需在主题中设置 "export_layers": true。

地形底图 (--relief)

基于 hongzhao (鸿爪) 的地形烘焙算法，从 AWS Terrarium DEM 瓦片生成山影地形。

# 全国山河叙事地图
cityposter --lat 34.26 --lon 108.94 -dc 中国 \
  -t atlas_outline_relief -d 8000000 -W 16 -H 9

# 城市级地形底图
cityposter --lat 39.9042 --lon 116.4074 -dc 北京 -t noir --relief

特性：

• 自动选取 zoom 级别（5km→z14, 8000km→z6）
• 16 线程并行下载 + tqdm 进度条，缓存至 ~/.cache/cityposter/terrarium/
• Natural Earth 陆地遮罩 → 陆海分离着色
• Mercator→WGS-84 重投影（大范围自动修正变形）
• 输出分辨率按 --dpi × -H 自动适配（--dpi 300 -H 9 → 2700px）
• 省界 Parquet 缓存、铁路分组 pickle 缓存
• 所有参数均可通过 cityposter/rendering/relief_config.toml 调整

高程配色预设 (elevation_preset)

主题 JSON 中通过 "elevation_preset" 切换配色，内置 10 套：

水系 (--water)

cityposter --lat 34.26 --lon 108.94 -dc 中国 \
  -t atlas_outline_relief_water -d 8000000 -W 16 -H 9

加载 Natural Earth 1:50m 河流 (LineString) 和湖泊 (Polygon)，在省界与铁路之间渲染。

渐变遮罩 (gradient)

海报上下边缘的渐变雾化效果，可在主题 JSON 中通过 gradient 对象配置：

{
  "gradient": {
    "enabled": true,
    "color": "#ece2c8",
    "top":    { "height": 0.25, "opacity": 1.0 },
    "bottom": { "height": 0.25, "opacity": 1.0 }
  }
}

所有 53 个主题均已配置，按需调参即可。

图层架构

详见 doc/LAYERS.md。

所有主题 (53)

Credit

Forked from maptoposter by Ankur Gupta. MIT License.

SinoGDB data derived from OpenStreetMap, processed by QGIS.