API参考

maps

maps模块主要存放与地图边界对象相关的类和函数。

class cnmaps.maps.MapRecord

默认 engine=None 且 only_polygon=False 时返回的地图记录对象。

MapRecord 基于 dict，支持：

• 英文 key 访问，例如 record['country']、record['longitude']

• 点号访问，例如 record.country、record.longitude

• 中文 key 兼容访问，例如 record['国家']、record['经度']

其中中文 key 当前仍兼容，但访问时会触发 DeprecationWarning，并计划在未来 3.x 版本中移除。

class cnmaps.maps.MapPolygon

地图多边形类（内部持有一个 shapely.geometry.MultiPolygon，组合实现，兼容 Shapely 2.0+）

该类基于 shapely.geometry.MultiPolygon 的自定义封装， 并实现了加号等运算符以合并边界。

drop_inner_duplicate(map_polygon)

地图对象的自我纠正，剔除内含的多余多边形，常见于多个地图多边形对象合并时

参数:

map_polygon (cnmaps.maps.MapPolygon) – 地图边界对象, 可以通过 get_adm_maps() 获取

返回:

经过纠正后的MapPolygon对象

返回类型:

cnmaps.maps.MapPolygon

get_extent(buffer=2)

获取范围坐标

参数:

buffer (float or int) – 外扩缓冲边缘, 单位为°, 该值越大, 所取的范围越大. 默认为 2.

返回:

坐标范围点, 该值可直接传入 ax.set_extent() 使用

返回类型:

tuple

to_file(savefp, engine='GeoJSON', meta={'id': None, 'name': None}, encoding='utf-8')

存储为文件

参数:

• savefp (str) – 保存路径

• engine (str) – 存储引擎，支持的选项为 'ESRI Shapefile' 和 'GeoJSON' ，不区分大小写。默认为 'GeoJSON' 。

• meta (dict) – 元信息，写入要素属性。默认为 {'id': None, 'name': None} 。

• encoding (str) – 编码类型。默认为 'utf-8' 。

make_mask_array(lons, lats)

生成边界以外的遮罩（掩膜）数组

参数:

• lons (numpy.ndarray) – 经度矩阵（2维）

• lats (numpy.ndarray) – 纬度矩阵（2维）

返回:

由 True 和 False 组成的遮罩（掩膜）数组

返回类型:

numpy.ndarray

maskout(lons, lats, data)

对边界以外的数据进行遮罩处理

参数:

• lons (numpy.ndarray) – 经度矩阵（2维）

• lats (numpy.ndarray) – 纬度矩阵（2维）

• data (numpy.ndarray) – 数据矩阵（2维）

返回:

遮罩后的数据矩阵

返回类型:

numpy.ma.MaskedArray

cnmaps.maps.read_mapjson(fp: str, wgs84=True)

读取geojson地图边界文件（仅对符合特定格式要求的geojson有效）

参数:

• fp (str) – geojson文件路径.

• wgs84 (bool) – 是否使用 WGS84 坐标，若为 True 则转为 WGS84 坐标，若为 False 则为原始的 GCJ02 坐标（火星坐标）

返回:

地图边界对象

返回类型:

cnmaps.maps.MapPolygon

cnmaps.maps.validate_boundary_file(fp, allow_multi_feature=True)

检查一个外部 GeoJSON / Shapefile 是否符合 cnmaps boundary spec。

当前规范要求：

• 文件格式为 .geojson / .json / .shp

• CRS 必须明确且等价为 WGS84（EPSG:4326）

• 几何必须全部为 Polygon 或 MultiPolygon

• 不能包含空几何或无效几何

参数:

• fp – 待检查的边界文件路径。

• allow_multi_feature (bool) – 是否允许文件包含多个 feature。默认为 True；若允许，读取时会先合并为一个统一边界。

返回:

结构化检查结果对象，包含是否通过、geometry 类型、CRS、错误列表与警告列表等信息。

cnmaps.maps.read_boundary_file(fp, dissolve=True)

读取一个符合 cnmaps boundary spec 的外部 GeoJSON / Shapefile 文件，并将其转换为 MapPolygon。

参数:

• fp – 边界文件路径。

• dissolve (bool) – 是否在读取时先将多个 feature 合并为一个统一边界。默认为 True。

返回:

可直接用于 make_mask_array、maskout、clip_* 等工作流的 MapPolygon。

抛出:

BoundarySpecError – 当文件不符合 cnmaps boundary spec 时抛出。

cnmaps.maps.get_adm_names(province: str = None, city: str = None, district: str = None, level: str = '省', country: str = None, source: str = None, provider: str = None)

获取行政名称（内部调用 get_adm_maps 再抽取名称字段）。

参数:

• province (str | list[str]) – 省/自治区/直辖市/行政特区中文名，必须为全称；也支持传入名称列表进行批量过滤。默认为 None。

• city (str | list[str]) – 地级市中文名，必须为全称；也支持传入名称列表进行批量过滤。默认为 None。

• district (str | list[str]) – 区/县中文名，必须为全称；也支持传入名称列表进行批量过滤。默认为 None。

• level (str) – 边界等级，请使用 '国'、'省'、'市'、'区县' 之一（与 get_adm_maps 的 level 含义一致）。默认为 '省'。

• country (str | list[str]) –

  国家名称。国家级查询可传中文名、ISO3 或组合码；也支持传入名称或代码列表做批量过滤；不传时不做国家过滤。

  从 2.0.0 开始，'中国' 也会自动视为 '中华人民共和国' 的别称。

• source (str) – 数据源过滤条件；不传时不做来源过滤。

• provider (str) – 数据提供者名称。默认为官方 'cnmaps-data'；传入其他名称时，会按已安装 provider 的 name 进行匹配。

返回:

满足条件的名称列表

返回类型:

list

备注

从 2.0.0 开始，国家级查询里传入 country='中国' 会自动等价于 country='中华人民共和国'。 一次查询仍然只对应一个 level ；列表过滤只是在该等级下批量选择多个名称，不支持在同一次调用里混合 国、省、市、区县 结果。下同。

cnmaps.maps.get_adm_maps(province: str = None, city: str = None, district: str = None, level: str = None, country: str = None, source: str = None, db: str = None, engine: str = None, record: str = 'all', only_polygon: bool = False, wgs84: bool = True, simplify: bool = False, provider: str = None, *args, **kwargs)

获取行政地图的边界对象。

参数:

• province (str | list[str]) – 省/自治区/直辖市/行政特区中文名，必须为全称；也支持传入名称列表进行批量过滤。默认为 None。

• city (str | list[str]) – 地级市中文名，必须为全称；也支持传入名称列表进行批量过滤。默认为 None。

• district (str | list[str]) – 区/县中文名，必须为全称；也支持传入名称列表进行批量过滤。默认为 None。

• level (str) – 边界等级，须为 '国'、'省'、'市'、'区县' 之一；也可使用 '区'、'县'、'区/县' 等写法（内部归一为 '区县'）。若为 None，则根据是否传入 province / city / district 自动推断等级。国界查询使用 level='国' （全国陆地与南海诸岛等为多条记录，常见用法为 record='first' 等）。

• country (str | list[str]) –

  国家名称。国家级查询可传中文名、ISO3 或组合码；也支持传入名称或代码列表做批量过滤；不传时不做国家过滤。

  从 2.0.0 开始，'中国' 也会自动视为 '中华人民共和国' 的别称。

• source (str) – 数据源过滤条件；不传时不做来源过滤。

• db (str) – SQLite 数据库文件路径。默认使用所选 provider 的索引库。

• engine (str) – 输出引擎：None 时为 list （元素为字典或 MapPolygon）；'geopandas' 时为 GeoDataFrame。当 engine='geopandas' 时，几何列保持为原生 Shapely geometry；当 engine is None 时，对外仍返回 MapPolygon 以保持历史接口。

• record (str) – 'all' 返回全部匹配记录；'first' 仅返回第一条。

• only_polygon (bool) – True 时只返回 MapPolygon 或 MapPolygon 列表；False 时返回带 'geometry' 等字段的字典列表（或 GeoDataFrame）。

• wgs84 (bool) – True 为 WGS84，False 为 GCJ02（火星坐标）。

• simplify (bool) – 是否对几何做简化。默认为 False。当你需要把按边界裁剪后的结果导出为 EPS / PS，且遇到文件无法被正常打开或转换的问题时，可以优先尝试 simplify=True；详见 常见问题。

• provider (str) – 数据提供者名称。默认为官方 'cnmaps-data'；传入其他名称时，会按已安装 provider 的 name 进行匹配。

返回:

根据参数查到的地图元信息与几何。

• 当 engine is None 且 only_polygon=False 时，返回 MapRecord 对象（或其列表）。 记录中同时包含英文字段 country、province、city、district、level、source、kind、longitude、latitude， 并兼容中文字段访问；中文 key 计划在未来 3.x 版本中移除。

• 当 engine='geopandas' 时，返回 GeoDataFrame。其中 geometry 列为原生 Shapely geometry， 并同时保留英文列和兼容性的中文列；geometry 只保留一份，不额外复制中文别名列。

• 当 only_polygon=True 时，返回 MapPolygon 或 MapPolygon 列表。

返回类型:

list or geopandas.GeoDataFrame

cnmaps.provider.get_available_data_providers()

返回当前环境中已发现的 provider 名称列表。

返回:

已发现的数据提供者名称

返回类型:

tuple

cnmaps.provider.get_data_provider(name: str = None)

返回当前使用的数据提供者对象。

参数:

name (str) – 可选的 provider 名称。若为 None，则返回当前默认 provider；传入名称时，会按已安装 provider 的 name 进行匹配。

返回:

数据提供者对象

drawing

drawing模块主要存放与绘图相关的函数

cnmaps.drawing.clip_contours_by_map(contours, map_polygon, ax=None, extent=None, set_extent=False)

使用地图边界对等值线 / 填色等值线（contour / contourf）结果裁剪。

参数:

• contours (cartopy.mpl.contour.GeoContourSet) – ax.contour() 或 ax.contourf() 的返回值，须带投影信息。

• map_polygon – 地图边界对象；支持单个 MapPolygon、MapPolygon 列表或 GeoDataFrame 几何列，通常由 get_adm_maps(..., only_polygon=True) 或 get_adm_maps(..., engine='geopandas') 得到。

• ax – 坐标轴；默认优先使用 contours.axes，拿不到时再回退到 matplotlib.pyplot.gca()。

• extent – 可选的经纬度范围 [left, right, lower, upper]。若传入，则会先用地图边界裁剪，再与该矩形范围求交。

• set_extent (bool) – 若为 True 且同时传入 extent，则自动调用 ax.set_extent(extent, crs=ccrs.PlateCarree())。

cnmaps.drawing.clip_pcolormesh_by_map(mesh, map_polygon, ax=None, extent=None, set_extent=False)

对 pcolormesh 结果按地图边界裁剪。

参数:

• mesh (cartopy.mpl.geocollection.GeoQuadMesh) – ax.pcolormesh() 的返回值，须带投影信息。

• map_polygon – 地图边界对象；支持单个 MapPolygon、列表或 GeoDataFrame。

• ax – 坐标轴；默认优先使用 mesh.axes，拿不到时再回退到当前轴。

• extent – 可选的经纬度范围 [left, right, lower, upper]。

• set_extent (bool) – 若为 True 且同时传入 extent，则自动设置坐标范围。

cnmaps.drawing.clip_quiver_by_map(quiver, map_polygon, ax=None, extent=None, set_extent=False)

对箭矢图 quiver 按地图边界裁剪。

参数:

• quiver (matplotlib.quiver.Quiver) – ax.quiver() 的返回值，须带投影信息。

• map_polygon – 地图边界对象；支持单个 MapPolygon、列表或 GeoDataFrame。

• ax – 坐标轴；默认优先使用 quiver.axes，拿不到时再回退到当前轴。

• extent – 可选的经纬度范围 [left, right, lower, upper]。

• set_extent (bool) – 若为 True 且同时传入 extent，则自动设置坐标范围。

cnmaps.drawing.clip_imshow_by_map(image, map_polygon, ax=None, extent=None, set_extent=False)

对 imshow 图像按地图边界裁剪，常用于山地阴影图（hillshade）或 RGB 栅格底图。

参数:

• image – ax.imshow() 的返回值。

• map_polygon – 地图边界对象；支持单个 MapPolygon、列表或 GeoDataFrame。

• ax – 坐标轴；默认优先使用 image.axes，拿不到时再回退到当前轴。

• extent – 可选的经纬度范围 [left, right, lower, upper]。

• set_extent (bool) – 若为 True 且同时传入 extent，则自动设置坐标范围。

cnmaps.drawing.clip_streamplot_by_map(streamplot, map_polygon, ax=None, extent=None, set_extent=False)

对流线图 streamplot 按地图边界裁剪。

参数:

• streamplot – ax.streamplot() 的返回值。

• map_polygon – 地图边界对象；支持单个 MapPolygon、列表或 GeoDataFrame。

• ax – 坐标轴；默认优先使用 streamplot.lines.axes，拿不到时再回退到当前轴。

• extent – 可选的经纬度范围 [left, right, lower, upper]。

• set_extent (bool) – 若为 True 且同时传入 extent，则自动设置坐标范围。

cnmaps.drawing.clip_scatter_by_map(scatter, map_polygon, ax=None, extent=None, set_extent=False)

对 scatter 散点按地图边界裁剪（设置 set_clip_path）。

参数:

• scatter (matplotlib.collections.PathCollection) – ax.scatter() 的返回值。

• map_polygon – 地图边界对象；支持单个 MapPolygon、列表或 GeoDataFrame。

• ax – 坐标轴；默认优先使用 scatter.axes，拿不到时再回退到当前轴。

• extent – 可选的经纬度范围 [left, right, lower, upper]。

• set_extent (bool) – 若为 True 且同时传入 extent，则自动设置坐标范围。

cnmaps.drawing.clip_clabels_by_map(clabel_text, map_polygon, ax=None, extent=None)

按边界隐藏落在区域外的等值线标签，一般与 contour + clabel 联用。

注意：依赖 Cartopy 与地图投影，建议在 cartopy >= 0.19.0 环境下使用。

参数:

• clabel_text – ax.clabel() 返回的可迭代标签集合（内部对逐个 matplotlib.text.Text 判断位置是否在 map_polygon 内）。

• map_polygon – 地图边界对象；支持单个 MapPolygon、列表或 GeoDataFrame。

• ax – 坐标轴；默认优先使用首个标签对象所在的 axes，拿不到时再回退到当前轴。

• extent – 可选的经纬度范围 [left, right, lower, upper]；标签可见性会基于地图边界与该范围的交集判断。

cnmaps.drawing.draw_map(map_polygon, ax=None, **kwargs)

绘制单个地图边界线（或 MultiLineString）。

参数:

• map_polygon – MapPolygon 或 shapely.geometry.MultiLineString。

• ax – 坐标轴；默认当前轴。

• kwargs – 其余关键字参数会透传给 ax.add_geometries。若未传 color / c，默认使用黑色。 额外支持 autoscale 参数（默认为 True），用于在绘制后自动缩放到当前几何范围。

cnmaps.drawing.draw_maps(maps, ax=None, **kwargs)

批量绘制多个地图边界。

参数:

• maps – list （MapPolygon、MapRecord 或含 geometry 的字典）、单个 MapPolygon，或 geopandas.GeoDataFrame。

• ax – 坐标轴；默认当前轴。

regions

regions模块主要存放组合后的边界对象

cnmaps.regions.region_polygons

区域性组合地图多边形数据字典，包含的键有：

东北地区、华北地区、华中地区、华南地区、华东地区、西南地区、西北地区、川渝、京津冀、江浙沪、长三角

sample

sample模块主要存放示例数据

cnmaps.sample.load_dem(provider: str = None)

加载中国地区的 DEM 海拔样例数据。

参数:

provider (str) – 数据提供者名称。默认为官方 'cnmaps-data'。

返回:

(lons, lats, data)

cnmaps.sample.load_temp(provider: str = None)

加载中国地区的气温样例数据。

参数:

provider (str) – 数据提供者名称。默认为官方 'cnmaps-data'。

返回:

(lons, lats, data)

cnmaps.sample.load_wind(provider: str = None)

加载中国地区的风场样例数据（u、v 分量）。

参数:

provider (str) – 数据提供者名称。默认为官方 'cnmaps-data'。

返回:

(lons, lats, u, v)

cli

命令行工具目前主要包括 install-skill 与 export 两个子命令。

install-skill {codex,cursor,claudecode} [--dir DIR] [--mode {local,global}] [--force]

安装 cnmaps 自带的 AI Skill 描述。

• codex / cursor / claudecode：目标助手类型

• --dir DIR：本地安装时指定项目目录，默认是当前目录

• --mode local：安装到当前项目目录

• --mode global：安装到用户主目录下的全局目录

• --force：覆盖已有安装

export OUTPUT [--country ...] [--province ...] [--city ...] [--district ...] [--level ...] [--source ...] [--provider ...] [--record {all,first}] [--engine ENGINE] [--encoding ENCODING] [--gcj02] [--simplify]

直接在命令行里完成“查询边界 + 导出文件”。

• OUTPUT：目标输出路径；默认按后缀推断格式，其中 .geojson / .json 对应 GeoJSON，.shp 对应 ESRI Shapefile

• --country、--province、--city、--district：边界筛选条件，均支持多个值

• --level：行政等级，例如 国、省、市、区县

• --source：数据源筛选

• --provider：数据提供者名称

• --record all：导出所有匹配记录

• --record first：只导出第一条匹配记录

• --engine：显式指定导出格式

• --encoding：指定输出编码

• --gcj02：导出 GCJ02 坐标，而不是默认的 WGS84

• --simplify：导出前先简化几何

其中各类筛选规则尽量与 get_adm_maps 保持一致；如果需要多个名称筛选，可在同一个参数后依次写出多个值。

check-boundary PATH [--json]

检查一个外部边界文件是否符合 cnmaps boundary spec。

• PATH：待检查的 GeoJSON / Shapefile 文件路径

• --json：输出结构化 JSON 检查结果；这只是检查结果的输出格式，与输入文件格式无关

若检查通过，文件即可进一步通过 read_boundary_file(...) 读取并转换为 MapPolygon。