地理处理

基础地理处理工具

Functions:

`auto_loads`(x)	自动识别地理格式并转换为shapely格式
`crs_sh2000`()	测绘院（上海2000）crs信息
`deg_to_decimal`(x)	将度分秒格式的经纬度转为小数
`distance`(p1, p2[, city, epsg_from, epsg_to])	计算两个点（经度，纬度）之间的距离，单位：米
`dumps2x`(x, geom_format)	转换geometry格式
`ensure_lnglat`(lnglat)	确保经纬度是tuple类型，如果是geometry会自动提取经纬度
`ensure_multi_geom`(geom)	将Point/LineString/Polygon转为multi分别转为MultiPoint/MultiLineString/MultiPolygon
`ensure_valid_polygon`(x)
`epsg_from_lnglat`(lng[, lat])	根据经纬度计算 UTM 区域 EPSG 代码
`filter_polygon_from_collection`(x)	从GeometryCollection中筛选面重新组成geometry
`geojson_dumps`(x)	shapely转为geojson文本格式
`geojson_loads`(x[, warning])	geojson文本形式转为shapely几个对象
`get_epsg`(city)	根据城市查询epsg代码，用于投影
`get_inner_point`(polygon[, within])	返回面内的一个点，默认返回中心点，当中心点不在面内则返回面内一个点
`infer_geom_format`(series)	推断geometry格式
`is_geojson`(x[, na])	判断是否为geojson格式
`is_shapely`(x[, na])	判断是否为shapely格式
`is_valid_lnglat`(lng, lat)	判断经纬度是否有效
`is_wkb`(x[, na])	判断是否为wkb格式
`is_wkt`(x[, na])	判断是否为wkt格式
`lng_from_city`(city)	获取城市所在的经度
`multiline2multipolygon`(multiline_shapely[, ...])	multiline转为multipolygon，直接首尾相连
`split_multi_geoms`(geometry)	返回多部件要素中的元素（LineString、Point、Polygon）组成的列表
`text2lnglats`(text, point_sep, lnglat_sep)	将一段坐标文本信息整理成经纬度列表
`text2shapely`(text, geometry_type[, ...])	文本转为shapely
`wkb_dumps`(x[, hex, srid])	将Shapely几何对象转换为文本形式的WKB
`wkb_loads`(x[, hex])	将文本形式的WKB转换为Shapely几何对象
`wkt_dumps`(x)	将Shapely几何对象转换为文本形式的WKT
`wkt_loads`(x)	将文本形式的WKT转换为Shapely几何对象

ricco.geometry.util.auto_loads(x) → BaseGeometry: 自动识别地理格式并转换为shapely格式

ricco.geometry.util.crs_sh2000(): 测绘院（上海2000）crs信息

ricco.geometry.util.deg_to_decimal(x: (<class 'str'>, <class 'list'>, <class 'tuple'>))

将度分秒格式的经纬度转为小数

参数:: x – 字符串或列表， - 字符串格式为 123°5’6.77”（分和秒分别为单双引号） - 列表长度为3，分别是度分秒，数值型

ricco.geometry.util.distance(p1: (<class 'tuple'>, <class 'str'>), p2: (<class 'tuple'>, <class 'str'>), city: str = None, epsg_from: int = 4326, epsg_to: (<class 'str'>, <class 'int'>) = None)

计算两个点（经度，纬度）之间的距离，单位：米

参数:

p1 – 点位1，经纬度或geometry
p2 – 点位2，经纬度或geometry
city – 所在城市，用于投影
epsg_from – epsg代码
epsg_to – 投影epsg代码

ricco.geometry.util.dumps2x(x: BaseGeometry, geom_format): 转换geometry格式

ricco.geometry.util.ensure_lnglat(lnglat) → tuple: 确保经纬度是tuple类型，如果是geometry会自动提取经纬度

ricco.geometry.util.ensure_multi_geom(geom: (<class 'shapely.geometry.base.BaseGeometry'>, <class 'shapely.geometry.base.BaseMultipartGeometry'>)) → BaseMultipartGeometry: 将Point/LineString/Polygon转为multi分别转为MultiPoint/MultiLineString/MultiPolygon

ricco.geometry.util.ensure_valid_polygon(x)

ricco.geometry.util.epsg_from_lnglat(lng, lat=0): 根据经纬度计算 UTM 区域 EPSG 代码

ricco.geometry.util.filter_polygon_from_collection(x): 从GeometryCollection中筛选面重新组成geometry

ricco.geometry.util.geojson_dumps(x: BaseGeometry): shapely转为geojson文本格式

ricco.geometry.util.geojson_loads(x: (<class 'str'>, <class 'dict'>), warning=True): geojson文本形式转为shapely几个对象

ricco.geometry.util.get_epsg(city: str): 根据城市查询epsg代码，用于投影

ricco.geometry.util.get_inner_point(polygon: Polygon, within=True): 返回面内的一个点，默认返回中心点，当中心点不在面内则返回面内一个点

ricco.geometry.util.infer_geom_format(series: (<class 'str'>, <class 'list'>, <class 'tuple'>, <class 'pandas.core.series.Series'>, <class 'shapely.geometry.base.BaseGeometry'>)): 推断geometry格式

ricco.geometry.util.is_geojson(x, na=False) → bool: 判断是否为geojson格式

ricco.geometry.util.is_shapely(x, na=False) → bool: 判断是否为shapely格式

ricco.geometry.util.is_valid_lnglat(lng, lat): 判断经纬度是否有效

ricco.geometry.util.is_wkb(x, na=False) → bool: 判断是否为wkb格式

ricco.geometry.util.is_wkt(x, na=False) → bool: 判断是否为wkt格式

ricco.geometry.util.lng_from_city(city: str): 获取城市所在的经度

ricco.geometry.util.multiline2multipolygon(multiline_shapely: MultiLineString, force=False): multiline转为multipolygon，直接首尾相连

ricco.geometry.util.split_multi_geoms(geometry: BaseMultipartGeometry) → list

返回多部件要素中的元素（LineString、Point、Polygon）组成的列表

参数:: geometry – geometry类型的数据

ricco.geometry.util.text2lnglats(text: str, point_sep: str, lnglat_sep: str)

将一段坐标文本信息整理成经纬度列表

参数:

text – 要转换为文本
point_sep – 点位之间的分隔符
lnglat_sep – 经纬度之间的分隔符

ricco.geometry.util.text2shapely(text: str, geometry_type: str, point_sep: str = ';', lnglat_sep: str = ',', ensure_multi: bool = True)

文本转为shapely

参数:

text – 坐标组成的文本
geometry_type – 要输出的地理类型，可选值为 ‘polygon’、’line’
point_sep – 点位键的分隔符，默认为分号 ‘;’
lnglat_sep – 经纬度的分隔符，默认为逗号 ‘,’
ensure_multi – 是否转为multi-geometry，默认为True

示例

>>> ss = '121.4737,31.2304; 121.4740,31.2304; 121.4740,31.2307'
>>> text2shapely(ss, geometry_type='line', point_sep=';', lnglat_sep=',')
MULTILINESTRING ((121.4737 31.2304, 121.474 31.2304, 121.474 31.2307))

ricco.geometry.util.wkb_dumps(x: BaseGeometry, hex=True, srid=4326): 将Shapely几何对象转换为文本形式的WKB

ricco.geometry.util.wkb_loads(x: str, hex=True): 将文本形式的WKB转换为Shapely几何对象

ricco.geometry.util.wkt_dumps(x: BaseGeometry): 将Shapely几何对象转换为文本形式的WKT

ricco.geometry.util.wkt_loads(x: str): 将文本形式的WKT转换为Shapely几何对象

基于GeoDataframe处理

Functions:

`auto2shapely`(df[, geometry])	自动识别地理格式并转换为shapely格式
`auto2x`(df, geometry_format[, geometry])	将geometry转为指定格式
`buffer`(df, radius[, city, geo_type, ...])	获得一定半径的缓冲区
`distance_gdf`(df, df_target[, c_dst, ...])	计算一个数据集中的每个元素到另一个数据集之间的最短距离
`distance_min`(df, geometry)	计算数据集df中元素到单个geometry的最短距离
`ensure_geometry`(df[, ensure_point, warning, ...])	转换并仅保留geometry列
`ensure_lnglat`(df[, lng, lat, geometry])	自动提取点或转换为点的经纬度
`geojson2shapely`(df[, geometry, epsg_code])	将geojson格式的geometry列转换为shapely格式
`get_area`(df[, c_dst, epsg, decimals])	计算面积（单位：平方米）
`get_neighbors`(df, key_col[, res_type])	获取数据集中每个点的邻居面(相邻标准：至少有一个点相同且不重叠)
`lnglat2shapely`(df[, lng, lat, geometry, ...])	将经纬度坐标转换为shapely格式的geometry
`lnglat2wkb`(df[, lng, lat, geometry, delete, ...])	经纬度转wkb格式的geometry
`lnglat2wkt`(df[, lng, lat, geometry, delete, ...])	经纬度转wkb格式的geometry
`mark_tags_v2`(point_df, polygon_df[, ...])	使用面数据通过空间关联（sjoin）给数据打标签
`nearest_kdtree`(df, df_poi, /, *[, c_count, ...])	KDTree近邻分析，计算一个数据集中的元素到另一个数据集中全部元素的最短距离（单位：米）, 同时可进行其他运算
`nearest_neighbor`(df, df_target[, c_dst, epsg])	近邻分析，计算一个数据集中的元素到另一个数据集中全部元素的最短距离（单位：米）
`projection`(df[, epsg, city, crs])	投影变换
`projection_lnglat`(df[, epsg, city, crs])	直接对经纬度进行投影变换
`shapely2central_shapely`(df[, geometry, within])	获取中心点shapely格式
`shapely2geojson`(df[, geometry])	将shapely格式的geometry列转换为geojson格式
`shapely2lnglat`(df[, geometry, lng, lat, ...])	shapely格式提取面内点转为经纬度。
`shapely2wkb`(df[, geometry])	将shapely格式的geometry列转换为wkb格式
`shapely2wkt`(df[, geometry])	将shapely格式的geometry列转换为wkt格式
`shapely2x`(df, geometry_format[, geometry])	将shapely转为指定的格式
`spatial_agg`(point_df, polygon_df, by, agg[, ...])	对面数据覆盖范围内的点数据进行空间统计
`split_grids`(df, step[, geometry_format])	根据所给边界划分固定边长的栅格
`split_multi_to_rows`(df[, geometry, ...])	将多部件要素拆解为多行的单部件要素
`wkb2lnglat`(df[, geometry, delete, within])	geometry转经纬度，求中心点经纬度
`wkb2shapely`(df[, geometry, epsg_code])	将wkb格式的geometry列转换为shapely格式
`wkb2wkt`(df[, geometry, epsg_code])	wkb转wkt
`wkt2lnglat`(df[, geometry, delete, within])	geometry转经纬度，求中心点经纬度
`wkt2shapely`(df[, geometry, epsg_code])	将wkt格式的geometry列转换为shapely格式
`wkt2wkb`(df[, geometry, epsg_code])	wkb转wkt

ricco.geometry.df.auto2shapely(df, geometry='geometry') → GeoDataFrame: 自动识别地理格式并转换为shapely格式

ricco.geometry.df.auto2x(df, geometry_format: str, geometry='geometry')

将geometry转为指定格式

参数:

df – 要转换的Dataframe
geometry_format – 要转换为的geometry类型，支持shapely,wkb,wkt,geojson
geometry – geometry列的列名，默认为“geometry”

ricco.geometry.df.buffer(df: DataFrame, radius: int | float, city: str | None = None, geo_type: str = 'point', geometry: str = 'geometry', buffer_geometry: str = 'buffer_geometry', geo_format='wkb') → DataFrame

获得一定半径的缓冲区

参数:

df – pd.DataFrame, 包含地理信息的DataFrame
radius – numeric, 缓冲区半径（单位米）
city – str, 可选, 投影城市，可提高数据精度
geo_type – str, 地理数据类型，可选point, line或polygon(包括multipolygon)，默认point
geometry – str, geometry字段名，默认”geometry”
buffer_geometry – 输出的缓冲区geometry字段名，默认”buffer_geometry”
geo_format – str, 输出的缓冲区geometry格式，支持wkb,wkt,shapely,geojson，默认wkb

返回:

包含缓冲区geometry的DataFrame

ricco.geometry.df.distance_gdf(df: GeoDataFrame, df_target: GeoDataFrame, c_dst: str = '最小距离', left_geometry='geometry'): 计算一个数据集中的每个元素到另一个数据集之间的最短距离

ricco.geometry.df.distance_min(df: GeoDataFrame, geometry: BaseGeometry) → float

计算数据集df中元素到单个geometry的最短距离

参数:

df – 数据集，GeoDataFrame格式
geometry – 单个geometry，shapely格式

ricco.geometry.df.ensure_geometry(df, ensure_point=False, warning=False, geometry='geometry', lng='lng', lat='lat'): 转换并仅保留geometry列

ricco.geometry.df.ensure_lnglat(df, lng='lng', lat='lat', geometry='geometry'): 自动提取点或转换为点的经纬度

ricco.geometry.df.geojson2shapely(df, geometry='geometry', epsg_code: int = 4326) → GeoDataFrame: 将geojson格式的geometry列转换为shapely格式

ricco.geometry.df.get_area(df: DataFrame, c_dst='area', epsg: int | None = None, decimals=2) → DataFrame

计算面积（单位：平方米）

参数:

df – 要计算的面数据
c_dst – 输出面积的列名，默认为“area”
epsg – 对于跨时区或不在同一个城市的可以指定epsg code，默认会根据经度中位数获取
decimals – 要保留的小数位数

ricco.geometry.df.get_neighbors(df: (<class 'pandas.core.frame.DataFrame'>, <class 'geopandas.geodataframe.GeoDataFrame'>), key_col: str, res_type='dict') -> (<class 'dict'>, <class 'pandas.core.frame.DataFrame'>)

获取数据集中每个点的邻居面(相邻标准：至少有一个点相同且不重叠)

参数:

df –
key_col – 关键列，必须唯一
res_type – 返回类型，可返回dict或Dataframe

ricco.geometry.df.lnglat2shapely(df, lng='lng', lat='lat', geometry='geometry', delete=True, epsg_code: int = 4326) → GeoDataFrame: 将经纬度坐标转换为shapely格式的geometry

ricco.geometry.df.lnglat2wkb(df, lng='lng', lat='lat', geometry='geometry', delete=False, epsg_code=4326): 经纬度转wkb格式的geometry

ricco.geometry.df.lnglat2wkt(df, lng='lng', lat='lat', geometry='geometry', delete=False, epsg_code=4326): 经纬度转wkb格式的geometry

ricco.geometry.df.mark_tags_v2(point_df: ~pandas.core.frame.DataFrame, polygon_df: ~pandas.core.frame.DataFrame, col_list: (<class 'list'>, <class 'str'>) = None, *, predicate='intersects', drop_geometry=False, geometry_format='wkb', warning=True, point_lng='lng', point_lat='lat', point_geometry='geometry', polygon_geometry='geometry', warning_message=None, ensure_point=True)

使用面数据通过空间关联（sjoin）给数据打标签

参数:

point_df – 点数据
polygon_df – 面数据
col_list – 面数据中要关联到结果中的列，若为空则全部关联
predicate – 关联方法，默认 ‘intersects’
drop_geometry – 结果是否删除geometry，默认不删除
geometry_format – 输出的geometry格式，支持wkb,wkt,shapely,geojson，默认wkb
warning – 是否输出警告信息
point_lng – 指定点数据的经度列名
point_lat – 指定点数据的经度列名
point_geometry – 指定点数据的geometry列名
polygon_geometry – 指定面数据的geometry列名
warning_message – 是否输出警告信息，已弃用
ensure_point – point_df是否强制转换为点数据

ricco.geometry.df.nearest_kdtree(df: ~pandas.core.frame.DataFrame, df_poi: ~pandas.core.frame.DataFrame, /, *, c_count: str = 'count', c_min_distance: str = 'min_distance', agg: dict = None, limit: int = None, r: (<class 'int'>, <class 'float'>) = None, keep_origin: bool = False, leaf_size: int = 2, epsg: int = None, city=None, crs=None)

KDTree近邻分析，计算一个数据集中的元素到另一个数据集中全部元素的最短距离（单位：米）, 同时可进行其他运算

参数:

df – 基础数据集，统计该数据及周边的其他数据集的信息
df_poi – 被统计的数据集
c_count – 计数列字段名，默认“count”
c_min_distance – 最短距离字段名，默认“min_distance”
agg – 计算 df_poi 中的其他字段，格式如: {‘面积’: [‘sum’, ‘mean’]}，即计算面积的和、均值
limit – 限制符合条件的 df_poi 中的个数，由近及远
r – 限制查询半径
keep_origin – 是否保留匹配后原始的索引信息
leaf_size – KDTree 叶子节点大小
epsg – 投影代码，用于投影，epsg/city/crs指定多个时以epsg为准
city – 城市，用于获取城市中心点，epsg/city/crs指定多个时以epsg为准
crs – 数据集的 crs，epsg/city/crs指定多个时以epsg为准

ricco.geometry.df.nearest_neighbor(df: DataFrame, df_target: DataFrame, c_dst: str = 'min_distance', epsg: int | None = None) → DataFrame

近邻分析，计算一个数据集中的元素到另一个数据集中全部元素的最短距离（单位：米）

参数:

df –
df_target –
c_dst – 输出最短距离的列名，默认为“min_distance”
epsg – 对于跨时区或不在同一个城市的可以指定epsg code，默认会根据经度中位数获取

ricco.geometry.df.projection(df: GeoDataFrame, epsg: int | None = None, city: str | None = None, crs=None) → GeoDataFrame

投影变换

参数:

df – 输入的GeomDataFrame格式的数据
epsg – epsg code, 第一优先级
city – 城市名称，未传入epsg的情况下将通过城市名称获取epsg，若二者都为空则根据经纬度获取
crs – 投影坐标系，第二优先级

ricco.geometry.df.projection_lnglat(df: DataFrame, epsg=None, city=None, crs=None) → DataFrame

直接对经纬度进行投影变换

参数:

df – 输入的GeomDataFrame格式的数据
epsg – epsg code, 第一优先级
city – 城市名称，未传入epsg的情况下将通过城市名称获取epsg，若二者都为空则根据经纬度获取
crs – 投影坐标系，第二优先级

ricco.geometry.df.shapely2central_shapely(df, geometry='geometry', within=False): 获取中心点shapely格式

ricco.geometry.df.shapely2geojson(df, geometry='geometry'): 将shapely格式的geometry列转换为geojson格式

ricco.geometry.df.shapely2lnglat(df, geometry='geometry', lng='lng', lat='lat', within=False, delete=False)

shapely格式提取面内点转为经纬度。

参数:

df – 要转换的DataFrame
geometry – 输入的geometry列名
lng – 输出的经度列名
lat – 输出的纬度列名
within – 范围的点是否再面内 - False(default): 直接返回中心点； - True: 返回面内的一个点
delete – 是否删除geometry

ricco.geometry.df.shapely2wkb(df, geometry='geometry'): 将shapely格式的geometry列转换为wkb格式

ricco.geometry.df.shapely2wkt(df, geometry='geometry'): 将shapely格式的geometry列转换为wkt格式

ricco.geometry.df.shapely2x(df: (<class 'geopandas.geodataframe.GeoDataFrame'>, <class 'pandas.core.frame.DataFrame'>), geometry_format: str, geometry='geometry')

将shapely转为指定的格式

参数:

df – 要转换的GeoDataFrame
geometry_format – 支持wkb,wkt,shapely,geojson
geometry – geometry列的列名，默认“geometry”

ricco.geometry.df.spatial_agg(point_df: DataFrame, polygon_df: DataFrame, by: str | List[str], agg: dict, polygon_geometry: str = 'geometry') → DataFrame

对面数据覆盖范围内的点数据进行空间统计

参数:

point_df – pd.DataFrame, 点数据dataframe;
polygon_df – pd.DataFrame, 面数据dataframe;
by – Union[str, List[str]], 空间统计单位字段；
agg – dict, 空间统计操作。格式为{‘被统计字段名’: ‘操作名’, …}的字典。如{‘poi’:’sum’};
polygon_geometry – str, 面数据geometry字段名，默认”geometry”;

返回:

pd.DataFrame, 包含空间统计单位字段和被统计字段和面数据geometry的DataFrame

ricco.geometry.df.split_grids(df: GeoDataFrame, step: int, geometry_format='wkb')

根据所给边界划分固定边长的栅格

参数:

df – 边界文件，GeoDataFrame格式
step – 栅格边长，单位：米
geometry_format – 栅格格式，支持wkb,wkt,shapely,geojson

ricco.geometry.df.split_multi_to_rows(df, geometry='geometry', geometry_format=None): 将多部件要素拆解为多行的单部件要素

ricco.geometry.df.wkb2lnglat(df, geometry='geometry', delete=False, within=False): geometry转经纬度，求中心点经纬度

ricco.geometry.df.wkb2shapely(df, geometry='geometry', epsg_code: int = 4326) → GeoDataFrame: 将wkb格式的geometry列转换为shapely格式

ricco.geometry.df.wkb2wkt(df, geometry='geometry', epsg_code: int = 4326): wkb转wkt

ricco.geometry.df.wkt2lnglat(df, geometry='geometry', delete=False, within=False): geometry转经纬度，求中心点经纬度

ricco.geometry.df.wkt2shapely(df, geometry='geometry', epsg_code: int = 4326) → GeoDataFrame: 将wkt格式的geometry列转换为shapely格式

ricco.geometry.df.wkt2wkb(df, geometry='geometry', epsg_code: int = 4326): wkb转wkt

拓扑处理

Functions:

`fix_topology`(df[, c_geometry, ...])	修复面地理数据的拓扑问题,index不能重复
`is_topology_valid`(df[, c_geometry])	判断整列geometry是否规范, 仅支持面数据，

ricco.geometry.topology.fix_topology(df: GeoDataFrame, c_geometry='geometry', fill_intersects=False, keep_contains=False) → GeoDataFrame

修复面地理数据的拓扑问题,index不能重复

参数:

df – 需要进行拓扑修复的GeoDataFrame
c_geometry – geometry列列名
fill_intersects – 是否填满相交的区域，如果为True的话，两个面相交的区域会随机分配到其中一个面内
keep_contains – fill_intersects为True时才有效，即是否强制保留被包含的面

返回:

修复完拓扑问题的GeoDataFrame

ricco.geometry.topology.is_topology_valid(df: GeoDataFrame, c_geometry='geometry')

判断整列geometry是否规范, 仅支持面数据，

检查geometry是否有空值，
检查每个geometry是否存在拓扑问题，
检查整列geometry之间是否存在拓扑问题

参数:

df – 需要进行拓扑修复的GeoDataFrame
c_geometry – geometry列名

返回:

geometry数据是否规范