空间#

对空间数据进行操作的函数。

空间索引函数#

cuspatial.quadtree_on_points(points: GeoSeries, x_min, x_max, y_min, y_max, scale, max_depth, max_size)#

根据给定的感兴趣区域边界框，从一组点构建一个四叉树。

参数:
points

点 Series。

x_min

感兴趣区域边界框的左下角 x 坐标。

x_max

感兴趣区域边界框的右上角 x 坐标。

y_min

感兴趣区域边界框的左下角 y 坐标。

y_max

感兴趣区域边界框的右上角 y 坐标。

scale

应用于每个点到 (x_min, y_min) 距离的比例。

max_depth

最大四叉树深度。

max_size

节点在分裂成 4 个叶节点之前允许包含的最大点数。

返回:
resulttuple (cudf.Series, cudf.DataFrame)
keys_to_pointscudf.Series(dtype=np.int32)

一列已排序的键到原始点索引

quadtreecudf.DataFrame

一组输入点的完整四叉树

keycudf.Series(dtype=np.int32)

象限键的 int32 列

levelcudf.Series(dtype=np.int8)

四叉树层级的 int8 列

is_internal_nodecudf.Series(dtype=np.bool_)

一个布尔列，指示节点是四叉节点还是叶节点

lengthcudf.Series(dtype=np.int32)

如果这是非叶象限（即 is_internal_node 为 True），此列的值为非叶象限中的子节点数。

否则，此列的值为叶象限中包含的点数。

offsetcudf.Series(dtype=np.int32)

如果这是非叶象限（即 is_internal_node 为 True），此列的值为非叶象限第一个子节点的位置。

否则，此列的值为叶象限第一个点的位置。

说明

  • 如果 min_x > max_x，则交换 min_x 和 max_x

  • 如果 min_y > max_y，则交换 min_y 和 max_y

  • 通过将每个 x/y 除以 scale，将 2D 坐标转换为 1D Morton 代码：((x - min_x) / scale 和 (y - min_y) / scale)。

  • max_depth 应小于 16，因为 Morton 代码表示为 uint32_t。如果点数较少或 max_size 较大，则最终层数可能少于 max_depth。

  • 所有中间四叉树节点将包含少于 max_size 个点。叶节点允许（但不保证）包含大于或等于 max_size 个点。

示例

根据输入选择 max_size 和 scale 的示例

>>> np.random.seed(0)
>>> points = cudf.DataFrame({
        "x": cudf.Series(np.random.normal(size=120)) * 500,
        "y": cudf.Series(np.random.normal(size=120)) * 500,
    })

>>> max_depth = 3
>>> max_size = 50
>>> min_x, min_y, max_x, max_y = (points["x"].min(),
                                  points["y"].min(),
                                  points["x"].max(),
                                  points["y"].max())
>>> scale = max(max_x - min_x, max_y - min_y) // (1 << max_depth)
>>> print(
        "max_size:   " + str(max_size) + "\n"
        "num_points: " + str(len(points)) + "\n"
        "min_x:      " + str(min_x) + "\n"
        "max_x:      " + str(max_x) + "\n"
        "min_y:      " + str(min_y) + "\n"
        "max_y:      " + str(max_y) + "\n"
        "scale:      " + str(scale) + "\n"
    )
max_size:   50
num_points: 120
min_x:      -1577.4949079170394
max_x:      1435.877311993804
min_y:      -1412.7015761122134
max_y:      1492.572387431971
scale:      301.0

>>> key_to_point, quadtree = cuspatial.quadtree_on_points(
        points["x"],
        points["y"],
        min_x,
        max_x,
        min_y,
        max_y,
        scale, max_depth, max_size
    )

>>> print(quadtree)
    key  level  is_internal_node  length  offset
0     0      0             False      15       0
1     1      0             False      27      15
2     2      0             False      12      42
3     3      0              True       4       8
4     4      0             False       5     106
5     6      0             False       6     111
6     9      0             False       2     117
7    12      0             False       1     119
8    12      1             False      22      54
9    13      1             False      18      76
10   14      1             False       9      94
11   15      1             False       3     103

>>> print(key_to_point)
0       63
1       20
2       33
3       66
4       19
    ...
115    113
116      3
117     78
118     98
119     24
Length: 120, dtype: int32

空间连接函数#

cuspatial.point_in_polygon(points: GeoSeries, polygons: GeoSeries)#

计算一组点和一组多边形中哪些点落在哪些多边形内。请注意，polygons_(x,y) 必须指定为闭合多边形：每个多边形的第一个坐标和最后一个坐标必须相同。

参数:
pointsGeoSeries

要测试的点 Series

polygons: GeoSeries

要测试的多边形 Series

返回:
resultcudf.DataFrame

一个布尔值 DataFrame，指示每个点是否落在每个多边形内。

示例

测试 3 个点是否落在两个多边形中的任何一个内

>>> result = cuspatial.point_in_polygon(
    GeoSeries([Point(0, 0), Point(-8, -8), Point(6, 6)]),
    GeoSeries([
        Polygon([(-10, -10), (5, -10), (5, 5), (-10, 5), (-10, -10)]),
        Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)])
    ], index=['nyc', 'hudson river'])
)
# The result of point_in_polygon is a DataFrame of Boolean
# values indicating whether each point (rows) falls within
# each polygon (columns).
>>> print(result)
            nyc            hudson river
0          True          True
1          True         False
2         False          True
# Point 0: (0, 0) falls in both polygons
# Point 1: (-8, -8) falls in the first polygon
# Point 2: (6.0, 6.0) falls in the second polygon
cuspatial.quadtree_point_in_polygon(poly_quad_pairs, quadtree, point_indices, points: GeoSeries, polygons: GeoSeries)#

测试指定点是否在任何指定多边形内。

使用 cuspatial.join_quadtree_and_bounding_boxes 返回的 (多边形, 象限) 对表，以确保只测试与每个多边形在同一象限中的点是否相交。

这种预过滤可以显着减少每个多边形测试的点数，从而以分配额外内存来存储四叉树和排序的 point_indices 为代价，实现更快的相交测试。

参数:
poly_quad_pairs: cudf.DataFrame

由 cuspatial.join_quadtree_and_bounding_boxes 返回的 (多边形, 象限) 索引对表。

quadtreecudf.DataFrame

给定感兴趣区域边界框的完整四叉树。

point_indicescudf.Series

由 cuspatial.quadtree_on_points 返回的已排序点索引

points: GeoSeries

用于构建四叉树的点

polygons: GeoSeries

要测试的多边形

返回:
resultcudf.DataFrame

每个相交点和多边形对的索引。

polygon_indexcudf.Series

包含多边形的索引。

point_indexcudf.Series

包含点的索引。此索引引用 point_indices，因此它是索引的索引。

cuspatial.quadtree_point_to_nearest_linestring(linestring_quad_pairs, quadtree, point_indices, points: GeoSeries, linestrings: GeoSeries)#

查找象限中每个点最近的线串，并计算每个点和线串之间的距离。

使用 cuspatial.join_quadtree_and_bounding_boxes 返回的 (线串, 象限) 对表，以确保仅计算与每个线串在同一象限中的点的距离。

参数:
linestring_quad_pairs: cudf.DataFrame

由 cuspatial.join_quadtree_and_bounding_boxes 返回的 (线串, 象限) 索引对表。

quadtreecudf.DataFrame

给定感兴趣区域边界框的完整四叉树。

point_indicescudf.Series

由 cuspatial.quadtree_on_points 返回的已排序点索引

points: GeoSeries

要查找最近线串的点

linestrings: GeoSeries

要测试的线串

返回:
resultcudf.DataFrame

每个点及其最近线串的索引，以及两者之间的距离。

point_indexcudf.Series

点索引。此索引引用 point_indices，因此它是索引的索引。

linestring_indexcudf.Series

点最近线串的索引。

distancecudf.Series

点与其最近线串之间的距离。

cuspatial.join_quadtree_and_bounding_boxes(quadtree, bounding_boxes, x_min, x_max, y_min, y_max, scale, max_depth)#

搜索四叉树以查找多边形或线串边界框相交。

参数:
quadtreecudf.DataFrame

给定感兴趣区域边界框的完整四叉树。

bounding_boxescudf.DataFrame

一组多边形或线串的最小边界框

x_min

感兴趣区域边界框的左下角 x 坐标

x_max

感兴趣区域边界框的右上角 x 坐标

min_y

感兴趣区域边界框的左下角 y 坐标

max_y

感兴趣区域边界框的右上角 y 坐标

scale

应用于每个点到 (x_min, y_min) 距离的比例

max_depth

停止测试相交的最大四叉树深度

返回:
resultcudf.DataFrame

每个相交边界框和叶象限的索引。

bbox_offsetcudf.Series

与四叉树相交的每个 bbox 的索引。

quad_offsetcudf.Series

与 poly bbox 相交的每个叶象限的索引。

说明

  • 如果 min_x > max_x，则交换 min_x 和 max_x

  • 如果 min_y > max_y，则交换 min_y 和 max_y

测量函数#

cuspatial.directed_hausdorff_distance(multipoints: GeoSeries)#

计算所有空间对之间的有向 Hausdorff 距离。

参数:
multipoints: GeoSeries

一个多点列，其中每个多点表示一个输入空间，用于计算其与其他输入空间的 Hausdorff 距离。

返回:
resultcudf.DataFrame

result[i, j] 表示 multipoints[i] 和 multipoint[j] 之间的 Hausdorff 距离。

示例

从一个空间到另一个空间的有向 Hausdorff 距离是第一个空间中任何点到第二个空间中最接近点之间所有距离中的最大值。

维基百科

考虑网格上的一对线

     :
     x
-----xyy---
     :
     :

x0 = (0, 0), x1 = (0, 1)

y0 = (1, 0), y1 = (2, 0)

x0 是 x 中与 y 最接近的点。从 x0 到 y 中最远点的距离为 2。

y0 是 y 中与 x 最接近的点。从 y0 到 x 中最远点的距离为 1.414。

计算一组空间之间的有向 Hausdorff 距离

>>> pts = cuspatial.GeoSeries([
...     MultiPoint([(0, 0), (1, 0)]),
...     MultiPoint([(0, 1), (0, 2)])
... ])
>>> cuspatial.directed_hausdorff_distance(pts)
    0         1
0  0.0  1.414214
1  2.0  0.000000
cuspatial.haversine_distance(p1: GeoSeries, p2: GeoSeries)#

计算任意经/纬度对列表之间的 Haversine 距离（公里）。

参数:
p1: GeoSeries

点 Series（浮点数）

p2: GeoSeries

点 Series（浮点数）

返回:
resultcudf.Series

p1 和 p2 之间点对的距离

>>> import cudf
    ..

>>> import cuspatial
    ..

>>> a = {"latitude":[0.0,0.0,1.0,1.0],
    ..
… “longitude”: [0.0,1.0,0.0,1.0]}
>>> df = cudf.DataFrame(data=a)
    ..

>>> # Create cuSpatial GeoSeries from cuDF Dataframe
    ..

>>> gs = cuspatial.GeoSeries.from_points_xy(
    ..
… df[[‘longitude’, ‘latitude’]].interleave_columns()
… )
>>> # Create Comparator cuSpatial GeoSeries from a comparator point
    ..

>>> df['compare_lat'] = 2.0 # this will broadcast the value to all rows
    ..

>>> df['compare_lng'] = 2.0
    ..

>>> cmp_gs = cuspatial.GeoSeries.from_points_xy(
    ..
… df[[‘compare_lat’, ‘compare_lng’]].interleave_columns()
… )
>>> # Calculate Haversine Distance of cuDF dataframe to comparator point
    ..

>>> df['compare_dist'] = cuspatial.haversine_distance(gs, cmp_gs)
    ..

>>> df.head()
    latitude  longitude  compare_lat  compare_lng  compare_dist
0 0.0 0.0 2.0 2.0 314.474805
1 0.0 1.0 2.0 2.0 248.629315
2 1.0 0.0 2.0 2.0 248.568719
3 1.0 1.0 2.0 2.0 157.225432
cuspatial.pairwise_point_distance(points1: GeoSeries, points2: GeoSeries)#

计算 (多)点-(多)点对之间的距离

目前 points1 和 points2 必须仅包含点或多点。在同一个 series 中混合点和多点是不支持的。

参数:
points1GeoSeries

一个 (多)点 GeoSeries

points2GeoSeries

一个 (多)点 GeoSeries

返回:
distancecudf.Series

每对 (多)点之间的距离

示例

>>> from shapely.geometry import Point, MultiPoint
>>> p1 = cuspatial.GeoSeries([
...     MultiPoint([(0.0, 0.0), (1.0, 0.0)]),
...     MultiPoint([(0.0, 1.0), (1.0, 0.0)])
... ])
>>> p2 = cuspatial.GeoSeries([
...     Point(2.0, 2.0), Point(0.0, 0.5)
... ])
>>> cuspatial.pairwise_point_distance(p1, p2)
0    2.236068
1    0.500000
dtype: float64
cuspatial.pairwise_linestring_distance(multilinestrings1: GeoSeries, multilinestrings2: GeoSeries)#

计算 (多)线串-(多)线串对之间的距离

两条线串之间的最短距离定义为两条线串所有线段对之间的最短距离。如果任何线段相交，距离为 0。

参数:
multilinestrings1GeoSeries

一个 (多)线串 GeoSeries

multilinestrings2GeoSeries

一个 (多)线串 GeoSeries

返回:
distancecudf.Series

每对线串之间的距离

示例

>>> from shapely.geometry import LineString, MultiLineString
>>> ls1 = cuspatial.GeoSeries([
...     LineString([(0, 0), (1, 1)]),
...     LineString([(1, 0), (2, 1)])
... ])
>>> ls2 = cuspatial.GeoSeries([
...     MultiLineString([
...         LineString([(-1, 0), (-2, -1)]),
...         LineString([(-2, -1), (-3, -2)])
...     ]),
...     MultiLineString([
...         LineString([(0, -1), (0, -2), (0, -3)]),
...         LineString([(0, -3), (-1, -3), (-2, -3)])
...     ])
... ])
>>> cuspatial.pairwise_linestring_distance(ls1, ls2)
0    1.000000
1    1.414214
dtype: float64
cuspatial.pairwise_point_linestring_distance(points: GeoSeries, linestrings: GeoSeries)#

计算 (多)点-(多)线串对之间的距离

(多)点与(多)线串之间的距离定义为多点中每个点与多线串中每个线段之间的最短距离。

该算法计算成对距离。结果中的第 i 行是 points 中第 i 个 (多)点与 linestrings 中第 i 个 (多)线串之间的距离。

参数:
pointsGeoSeries

要计算距离的 (多)点。

linestringsGeoSeries

要计算距离的 (多)线串。

返回:
distancecudf.Series

说明

输入 GeoSeries 必须包含单一类型的几何图形。例如，points series 不能同时包含点和多边形。目前不支持 points 同时包含点和多点的情况。

示例

计算点数组与线串数组之间的距离

>>> from shapely.geometry import (
...     Point, MultiPoint, LineString, MultiLineString
... )
>>> import geopandas as gpd, cuspatial
>>> pts = cuspatial.from_geopandas(gpd.GeoSeries([
...     Point(0.0, 0.0), Point(1.0, 1.0), Point(2.0, 2.0)
... ]))
>>> mlines = cuspatial.from_geopandas(gpd.GeoSeries(
...     [
...        LineString([Point(-1.0, 0.0),
...                    Point(-0.5, -0.5),
...                    Point(-1.0, -0.5),
...                    Point(-0.5, -1.0)]),
...        LineString([Point(8.0, 10.0),
...                    Point(11.21, 9.48),
...                    Point(7.1, 12.5)]),
...        LineString([Point(1.0, 0.0), Point(0.0, 1.0)]),
...     ]))
>>> cuspatial.pairwise_point_linestring_distance(pts, mlines)
0     0.707107
1    11.401754
2     2.121320
dtype: float64

计算多点与多线串数组之间的距离 >>> # 3 对多点，每对包含 3 个点 >>> ptsdata = [ … [[9, 7], [0, 6], [7, 2]], … [[5, 8], [5, 7], [6, 0]], … [[8, 8], [6, 7], [4, 1]], … ] >>> # 3 对多线串，每对包含 2 个线串 >>> linesdata = [ … [ … [[86, 47], [31, 17], [84, 16], [14, 63]], … [[14, 36], [90, 73], [72, 66], [0, 5]], … ], … [ … [[36, 90], [29, 31], [91, 70], [25, 78]], … [[61, 64], [89, 20], [94, 46], [37, 44]], … ], … [ … [[60, 76], [29, 60], [53, 87], [8, 18]], … [[0, 16], [79, 14], [3, 6], [98, 89]], … ], … ] >>> pts = cuspatial.from_geopandas( … gpd.GeoSeries(map(MultiPoint, ptsdata)) … ) >>> lines = cuspatial.from_geopandas( … gpd.GeoSeries(map(MultiLineString, linesdata)) … ) >>> cuspatial.pairwise_point_linestring_distance(pts, lines) 0 0.762984 1 33.241540 2 0.680451 dtype: float64

最近点函数#

cuspatial.pairwise_point_linestring_nearest_points(points: GeoSeries, linestrings: GeoSeries) → GeoDataFrame#

返回两个 GeoSeries 点和线串之间的最近点。

也支持多点和多线串。限制是 points series 必须仅包含点或仅包含多点。

参数:
pointsGeoSeries

点 GeoSeries。目前仅支持点 series 或多点 series。

linestringsGeoSeries

线串或多线串 GeoSeries。

返回:
GeoDataFrame

一个具有四列的 GeoDataFrame。

  • “point_geometry_id” 包含行中最接近点的索引。如果 points 由单点组成，则此值为 0。

  • “linestring_geometry_id” 包含多线串中包含最近点的线串索引。

  • “segment_id” 包含线串中包含最近点的线段索引。

  • “geometry” 包含线串上最近点的点。

边界框#

cuspatial.polygon_bounding_boxes(polygons: GeoSeries)#

计算一组多边形的最小边界框。

参数:
polygons: GeoSeries

多边形 Series

返回:
resultcudf.DataFrame

每个多边形的最小边界框

minxcudf.Series

每个边界框的最小 x 坐标

minycudf.Series

每个边界框的最小 y 坐标

maxxcudf.Series

每个边界框的最大 x 坐标

maxycudf.Series

每个边界框的最大 y 坐标

说明

没有多边形的概念。如果传入多边形，将计算并返回每个多边形的边界框。用户负责处理多边形情况。

cuspatial.linestring_bounding_boxes(linestrings: GeoSeries, expansion_radius: float)#

计算一组线串的最小边界框。

参数:
linestrings: GeoSeries

线串 Series

expansion_radius

每个线串点的半径

返回:
resultcudf.DataFrame

每个线串的最小边界框

minxcudf.Series

每个边界框的最小 x 坐标

minycudf.Series

每个边界框的最小 y 坐标

maxxcudf.Series

每个边界框的最大 x 坐标

maxycudf.Series

每个边界框的最大 y 坐标

投影函数#

cuspatial.sinusoidal_projection(origin_lon, origin_lat, lonlat: GeoSeries)#

相对于原点，将经度/纬度进行正弦投影，得到以公里为单位的笛卡尔 (x/y) 坐标。

如果所有点都靠近原点，则可用于将经度/纬度坐标近似转换为笛卡尔坐标。误差随距原点距离的增加而增大。结果相对于地球大小（公里）进行缩放。详情请参见 https://en.wikipedia.org/wiki/Sinusoidal_projection。

参数:
origin_lonnumber

经度偏移（在转换为 x,y 之前从每个输入中减去）

origin_latnumber

纬度偏移（在转换为 x,y 之前从每个输入中减去）

lonlat: GeoSeries

包含要转换的经度和纬度的点 GeoSeries

返回:
resultGeoSeries

包含转换后坐标的 GeoSeries。

空间过滤函数#

cuspatial.points_in_spatial_window(points: GeoSeries, min_x, max_x, min_y, max_y)#

仅返回落在矩形窗口内的坐标子集。

点 (x, y) 在查询窗口内当且仅当 min_x < x < max_x AND min_y < y < max_y

窗口由最小和最大 x 和 y 坐标指定。

参数:
points: GeoSeries

点 geoseries

min_x: float

查询窗口的较低 x 坐标

max_x: float

查询窗口的较高 x 坐标

min_y: float

查询窗口的较低 y 坐标

max_y: float

查询窗口的较高 y 坐标

返回:
resultGeoSeries

落在窗口内的上述 points 子集

说明

  • 如果 min_x > max_x，则交换 min_x 和 max_x

  • 如果 min_y > max_y，则交换 min_y 和 max_y