观潮 · 模式预报与气象 AI 观察
cartopy 0.26.0：拖了 13 个月，修了 一堆"画图时才炸"的坑
> 📌 上一版记的"官方文档 404，需改走 GitHub Releases"——已解决，GitHub Release API 可以直接取全文。
---
这一版讲了什么
功能上的新增很少，重点全在修 bug。
而且修的全是"平时没事、画特定图时才崩"的那类问题——跨 180° 经线的小岛、极区图的网格线标签、多面板图的缩放同步。
一句话概括：这一版是给画图的人修的。
为什么 13.5 个月才发？看看修复清单就明白了——一半以上的工作量在对齐底层依赖的新版本。
---
功能上的新增
add_feature 和 add_geometries 支持自动设置地图范围。 以前画地物要自己算边界，现在可以自动。
新增 Thunderforest 瓦片支持。 多一家商业瓦片源可选。
底层细节图（.imshow）暴露更多参数。 卫星图像、雷达回波图这类更容易定制。
斜接墨卡托投影可以用 +gamma 参数了，并且当 PROJ 算不出某个方位角时，cartopy 会自动微调一下再试。
默认关闭性能剖析和代码行追踪（需要时可以用 flag 打开）。
---
修掉的痛点（画图人天天撞的）
① 跨 180° 经线的小多边形
问题：画斐济、基里巴斯这类跨日期变更线的小岛时，投影会崩或者形状变形。
原因：这类小多边形的面积太小，跨越了经度周期的边界。
修复：改用更稳健的面积判定方式（鞋带公式），并专门处理了"跨越反子午线的小多边形"。
② 弯曲投影下的网格线标签
问题：在极射赤面投影、兰勃特投影这类弯曲坐标系上画网格线标签，标签会：
- 糊成一团分不清
- 莫名消失
- 在 90° 旋转时错误隐藏
修复：标签现在会正确判断"自己该在哪一侧可见"，并忽略不可见标签对整体布局的影响。曲面上的投影尤其明显。
③ 多面板图缩放不同步
问题：做两个子图共享一个地图的对比图时，缩放其中一个，另一个不跟着动。
修复：已同步。
④ 基础库全面上抬（这才是维护大头）
这一版的修复清单里，"适配新版本"占了一大半：
依赖 · 适配内容
**PROJ 9.8** · 专门修复，**并临时加了一个 PROJ 版本上限**
**NumPy 2.5.0** · 修复弃用警告
**Matplotlib 3.11** · 更新测试基准图
**Shapely** · 移除旧版本支持
最低依赖版本 · 整体抬高
> PROJ 是 cartopy 的底层投影引擎。这一版不得不临时加 PROJ 上限，说明 PROJ 9.8 带来的变更还没完全消化。如果升级后投影行为异常，第一件事应该是查 PROJ 版本。
⑤ 其他实用修复
- 数据下载改用 GitHub 镜像 —— gshhg / gshhs 这类海岸线数据国内下载会快很多也不容易断
- 无多边形时返回空路径而不是报错
- 几何投影里处理空点
- 矢量化的坐标提取（
shapely_to_path）—— 大数据量下性能提升明显 - 闭合三角形路径被正确识别为多边形
- CRS 子类的深拷贝和序列化修复
- PlateCarree 投影的文档错误修正
- ARM manylinux 构建加入 CI → Graviton 这类 ARM 服务器有官方 wheel 了
- CPython 3.14 的 wheel 启用，并在测试 freethreaded / 3.15 的 wheel
---
三个破坏性变更（升级前必须确认）
① Python 最低版本抬到 3.10
3.9 及以下彻底不支持了（上一版 0.25.0 还支持 3.9）。
② 弃用旧的经纬度刻度格式化器
这是 0.26.0 唯一的弃用项，迁移成本不高，但会告警。升级前扫一遍代码：
```bash
grep -rn "LatitudeFormatter\|LongitudeFormatter" your_project/
```
③ 移除旧 Shapely 支持和过时的兼容模块
用极老版本 Shapely 的环境会直接失败。
---
升级前后要做什么
```bash
1. 确认 Python >= 3.10
python -c "import sys; print(sys.version)"
2. 升级
pip install -U cartopy
3. 验证底层引擎
python -c "import cartopy, proj, shapely, matplotlib; print('cartopy', cartopy.__version__); print('PROJ', proj.__version__); print('shapely', shapely.__version__)"
4. 全库扫一遍旧格式化器
grep -rn "LatitudeFormatter\|LongitudeFormatter" your_project/
```
如果升级后投影行为异常：优先查 PROJ 版本（这一版临时 pin 了 PROJ 上限）。