API参考
maps
maps模块主要存放与地图边界对象相关的类和函数。
- class cnmaps.maps.MapPolygon(shapely.geometry.MultiPolygon)
地图多边形类
该是基于shapely.geometry.MultiPolygon的自定义类, 并实现了对于加号操作符的支持.
- drop_inner_duplicate(map_polygon)
地图对象的自我纠正,剔除内含的多余多边形,常见于多个地图多边形对象合并时
- 参数:
map_polygon (cnmaps.maps.MapPolygon) – 地图边界对象, 可以通过
get_adm_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': 0, 'name': 'unknown'}
.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.get_adm_names(province: str = None, city: str = None, district: str = None, level: str = '省', country: str = '中华人民共和国', source: str = '高德')
获取行政名称
- 参数:
province (str) – 省/自治区/直辖市/行政特区中文名, 必须为全称, 例如查找河北省应收入
'河北省'
而非'河北'
. 默认为None
.city (str) – 地级市中文名, 必须为全称, 例如查找北京市应输入
'北京市'
而非'北京'
. 默认为None
.district (str) – 区/县中文名, 必须为全称. 默认为
None
.level (str) – 边界等级, 目前支持的等级包括
'省'
,'市'
,'区县'
. 其中'省'
级包括直辖市、特区等;'市'
级为地级市, 若为直辖市, 则名称与'省'
级相同, 比如北京市的省级和市级都是'北京市'
;'区'
和'县'
属于同一级别的不同表达形式. 默认为'省'
.country (str) – 国家名称, 必须为全称. 默认为
'中华人民共和国'
.source (str) – 数据源. 默认为
'高德'
.
- 返回:
满足条件的名称列表
- 返回类型:
list
- cnmaps.maps.get_adm_maps(province: str = None, city: str = None, district: str = None, level: str = '省', country: str = '中华人民共和国', source: str = '高德', db: str = DB_FILE, engine: str = None, record: str = 'all', only_polygon: bool = False, wgs84: bool = True, *args, **kwargs)
获取行政地图的边界对象
- 参数:
province (str) – 省/自治区/直辖市/行政特区中文名, 必须为全称, 例如查找河北省应收入
'河北省'
而非'河北'
. 默认为None
.city (str) – 地级市中文名, 必须为全称, 例如查找北京市应输入
'北京市'
而非'北京'
. 默认为None
.district (str) – 区/县中文名, 必须为全称. 默认为
None
.level (str) – 边界等级, 目前支持的等级包括
'省'
,'市'
,'区县'
. 其中'省'
级包括直辖市、特区等;'市'
级为地级市, 若为直辖市, 则名称与'省'
级相同, 比如北京市的省级和市级都是'北京市'
;'区'
和'县'
属于同一级别的不同表达形式. 默认为'省'
.country (str) – 国家名称, 必须为全称. 默认为
'中华人民共和国'
.source (str) – 数据源. 默认为
'高德'
.db (str) – sqlite db文件路径. 默认从配置文件中取.
engine (str) – 输出引擎, 默认为None, 输出为list列表, 目前支持’geopandas’, 若为geopandas, 则返回GeoDataFrame对象. 默认为 None.
record (str) – 返回记录的形式, 选项包括
'all'
和'first'
; 若为'first'
, 则无论查询结果又几条,仅返回第一条记录, 若为'all'
, 则返回全部数据, 若engine==None
则返回list, 若engine=='geopandas'
, 则返回GeoDataFrame对象. 默认为'all'
.only_polygon (bool) – 是否仅返回地图边界对象(MapPolygon), 若为
True
则返回结果为MapPolygon对象或以MapPolygon对象组合的list, 若为False
, 则返回的结果包含元信息, MapPolygon对象存储在'geometry'
键中. 默认为False
.wgs84 (bool) – 是否使用 WGS84 坐标,若为 True 则转为 WGS84 坐标,若为 False 则为原始的 GCJ02 坐标(火星坐标). 默认为
True
- 返回:
根据输入参数查找到的地图边界的元信息及边界对象
- 返回类型:
GeoDataFrame or list
drawing
drawing模块主要存放与绘图相关的函数
- cnmaps.drawing.clip_contours_by_map(contours, map_polygon)
使用地图边界对象对等值线对象进行裁剪
- 参数:
contours (cartopy.mpl.contour.GeoContourSet) – 等值线对象, 该对象是调用
ax.contour()
或ax.contourf()
方法的返回值,注意: 对象须带有投影信息map_polygon (cnmaps.maps.MapPolygon) – 地图边界对象, 可以通过
get_adm_maps()
获取
- cnmaps.drawing.clip_pcolormesh_by_map(mesh, map_polygon)
使用地图边界对象对填色网格线对象进行裁剪
- 参数:
mesh (cartopy.mpl.geocollection.GeoQuadMesh) – GeoQuadMesh对象, 该对象是调用
ax.pcolormesh()
方法的返回值,注意: 对象须带有投影信息map_polygon (cnmaps.maps.MapPolygon) – 地图边界对象, 可以通过
get_adm_maps()
获取
- cnmaps.drawing.clip_quiver_by_map(quiver, map_polygon)
使用地图边界对象对箭矢簇对象进行裁剪
- 参数:
quiver (matplotlib.quiver.Quiver) – Quiver对象, 该对象是调用
ax.quiver()
方法的返回值,注意: 对象须带有投影信息map_polygon (cnmaps.maps.MapPolygon) – 地图边界对象, 可以通过
get_adm_maps()
获取
- cnmaps.drawing.clip_clabels_by_map(clabel_text, map_polygon)
剪切clabel文本, 一般配合contour函数使用
注意: 该函数仅对于cartopy>=0.19.0版本有效
- 参数:
clabel_text (matplotlib.text.Text) – matplotlib.text.Text对象, 由
clabel
函数返回map_polygon (cnmaps.maps.MapPolygon) – 地图边界对象, 可以通过
get_adm_maps()
获取
- cnmaps.drawing.draw_map(map_polygon, **kwargs)
绘制单个地图边界线
- 参数:
map_polygon (cnmaps.maps.MapPolygon) – 地图边界线对象
- cnmaps.drawing.draw_maps(maps, **kwargs)
绘制多个地图边界
- 参数:
maps (list or GeoDataFrame) – 地图边界线对象
regions
regions模块主要存放组合后的边界对象
- cnmaps.regions.region_polygons
区域性组合地图多边形数据字典,包含的键有:
东北地区、华北地区、华中地区、华南地区、华东地区、西南地区、西北地区、川渝、京津冀、江浙沪、长三角
sample
sample模块主要存放示例数据
- cnmaps.sample.load_dem()
加载中国地区的 DEM 海拔样例数据
- 返回:
(lons, lats, data)
- cnmaps.sample.load_temp()
加载中国地区的气温样例数据
- 返回:
(lons, lats, data)
- cnmaps.sample.load_wind()
加载中国地区的气温样例数据
- 返回:
(lons, lats, u, v)