版本日志
===========

2.1.0
-------
*发布日以 PyPI 为准。*

* **版本与数据依赖**：主包版本提升到 ``2.1.0`` ，并将官方数据包依赖提升到 ``cnmaps-data>=1.1.2`` 。
* **行政区记录增强**：``get_adm_maps`` 返回的 ``MapRecord`` 现在显式提供 ``longitude`` / ``latitude`` 中心点坐标字段，便于直接做标注、打点和文本放置；相关文档、示例和技能说明同步补全。
* **多名称批量筛选**：``get_adm_maps`` / ``get_adm_names`` 支持在同一 ``level`` 下使用 ``province`` / ``city`` / ``district`` / ``country`` 的多值筛选，一次查询可返回多个精确命名对象，但仍不支持在单次调用中混合 ``国`` / ``省`` / ``市`` / ``区县`` 层级。
* **命令行工具扩展**：新增 ``cnmaps export`` 子命令，可直接按照接近 ``get_adm_maps`` 的筛选规则导出 GeoJSON / Shapefile；文档新增独立“命令行工具”章节，并补充 CLI 相关测试。
* **外部边界规范与校验**：新增 ``validate_boundary_file(...)``、``read_boundary_file(...)`` 和 ``cnmaps check-boundary`` ，为自定义 GeoJSON / Shapefile 接入 ``MapPolygon`` 工作流提供统一的 boundary spec、校验入口与读取入口。
* **绘图裁剪能力扩展**：新增 ``clip_streamplot_by_map(...)`` 与 ``clip_imshow_by_map(...)`` ，分别支持对 ``streamplot`` 流线图和 ``imshow`` 图像对象（包括 hillshade）按行政区边界裁剪。
* **EPS / PS 导出经验沉淀**：新增“常见问题”文档，记录复杂边界裁剪后导出 ``EPS`` / ``PS`` 可能失效的场景，并补充 ``simplify=True`` 的 workaround 与相关技能说明。
* **AI Skill 体系上线**：主包内置 bundled skill 结构，支持通过 ``cnmaps install-skill`` 安装到 Codex、Cursor、Claude Code 等助手环境；同时补充共享 references / examples，使 AI 更稳定地理解 ``cnmaps`` 的查询、绘图、裁剪、遮罩、导出与能力边界。
* **依赖清理**：移除了仅用于坐标转换加速的 ``numba`` 运行时依赖，并清理了未实际使用的 ``geojson`` 依赖。
* **文档与示例重构**：整体刷新 README 与 Sphinx 文档，新增 CLI、FAQ、数据来源、国家中心点、世界地图与能力边界等内容，补充大量静态示例图和可运行示例脚本，并统一本地文档构建脚本。

2.0.1
-------
*发布日以 PyPI 为准。*

* **数据依赖约束**：将官方数据包依赖明确收紧为 ``cnmaps-data>=1.1.1``，确保国家级边界、``iso3`` 查询和最新争议地区处理规则能够稳定生效。
* **性能测试**：重构 benchmark 项目与性能页面统计口径，避免将不同 workload 的历史曲线混在同一条线上。
* **性能优化**：对 ``maskout`` / ``make_mask_array`` 的核心路径进行了针对性优化，改善重复网格计算场景下的性能表现。
* **Python / CI**：项目 Python 版本范围更新为 ``>=3.9,<3.13``，主 CI 覆盖 Python 3.9–3.12 与 macOS / Ubuntu / Windows；绘图测试统一使用 ``MPLBACKEND=Agg``，依赖安装步骤增加自动重试以减少网络抖动导致的偶发失败。
* **测试与文档**：补齐国家级查询、文档示例和性能测试用例的查询口径，使其与 ``cnmaps-data`` 拆分后的语义保持一致。

2.0.0
-------
*发布日以 PyPI 为准。*

* **数据包拆分**：``cnmaps`` 自 2.0 起不再内置官方行政区、地理边界与样例数据，官方数据已迁移到独立包 ``cnmaps-data``；安装 ``cnmaps`` 时会默认安装 ``cnmaps-data``。
* **数据提供者机制**：运行时默认通过已安装的 ``cnmaps-data`` 或兼容 ``cnmaps.data_providers`` entry point 协议的第三方数据包提供数据，不再回退到仓库内置数据目录。
* **Shapely 2.0**：本版本最重要的变更是将依赖与实现全面对齐 Shapely 2.x（``pyproject.toml`` 中为 ``shapely>=2.0.0``），在保留 ``MapPolygon`` 等既有 API 的前提下，消除此前与 Shapely 2.0 迁移相关的兼容性问题；该项变更对应 `Issue 106 <https://github.com/cnmetlab/cnmaps/issues/106>`_。
* **Cartopy 兼容**：绘图裁剪逻辑同时兼容新版 ``cartopy.mpl.path.shapely_to_path`` 与旧版 ``cartopy.mpl.patch.geos_to_path``，并适配新的 ``GeoContourSet`` 接口。
* **性能**：对样例数据加载、GeoJSON 读取、行政区查询与 ``MapPolygon`` 内部重复多边形清理进行了缓存和热点优化，全量测试耗时显著下降。
* 文档：安装说明、贡献者指南、API 参考等与当前工程及 CI 同步（Python/NumPy/Shapely 约束、GitHub Actions、函数签名与返回行为等）。

1.1.7
------
*发布时间: 2023-08-10*

* Python 解释器要求升级到 3.9。
* Cartopy 版本要求升级到 0.22.0。
* 修复了由于 ``shapely>=2.0`` 导致的错误。
* 修复了 Numba、Geopandas 的警告提示问题。
* pip 安装时不再需要手动安装依赖。


1.0.1
-------
*发布时间: 2022-04-05*

* 修复了安装依赖缺少 geopandas 的问题。

1.0.0
-------
*发布时间: 2022-04-05*

* 增加了 ``cnmaps.maps.get_adm_maps`` 函数以支持对市、区县等行政边界的查询，高德的行政边界数据上已下探到区县级别。

   * 支持多条件筛选和一次性返回多个对象功能。
   * 集成了geopandas引擎。

* 增加了 ``cnmaps.maps.get_adm_names`` 函数以支持对支持的行政区关键字的查询。
* 增加了 ``cnmaps.drawing.draw_maps`` 函数以方便一次性绘制多个地图边界。
* 增加了 ``cnmaps.regions.region_polygons`` 可以直接获取例如华北地区、华东地区、京津冀、江浙沪等边界对象。
* 删除了 ``cnmaps.get_map`` 函数，其行政边界查询的功能转移至 ``get_adm_maps`` ，但用法上会有一些变化。
* 暂时删除了对青藏高原边界的支持。

0.2.1
---------
*发布时间: 2022-03-02*

* 修复了Windows系统中GBK编码无法加载数据的问题。

0.2.0
---------
*发布时间: 2022-02-16*

* 增加了对pcolormesh图的裁剪支持。
* 修复了边界错误的问题。

0.1.11
---------
*发布时间: 2022-02-14*

* 尝试修复安装时出现gbk编码异常的问题。

0.1.10
---------
*发布时间: 2022-02-13*

* 增加功能: cnmaps.get_map函数: 获取地图。
* 增加功能: cnmaps.draw_map函数: 绘制地图。
* 增加功能: cnmaps.MapPolygon类: 地图对象, 包括: 加号(合并)、减号(剪切)、逻辑与(交集)运算符的支持，get_extent方法。
* 增加功能: cnmaps.clip_contours_by_map函数: 基于MapPolygon类对等值线图做裁减。
* 增加功能: cnmaps.sample.load_dem函数: 加载dem样例数据。
* 增加功能: cnmaps.clip_clabels_by_map函数: 基于MapPolygon类对标签做裁减。
* 对cartopy.crs各类投影的支持。
* 对全国中国国界、全国各省(特区/直辖市)地图的预置, 且处理了已知的拓扑错误。
* 集成 Travis CI 自动化测试（后续版本已迁移至 GitHub Actions）。