cuSpatial GPU 地理空间加速实战从 GeoPandas 迁移到四叉树空间索引scientific-agent-skills optimize-for-gpu 参考指南【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skillscuSpatial 是 NVIDIA RAPIDS 生态中面向 GPU 的 GIS 库提供空间索引、空间连接、距离计算、轨迹分析和 GeoPandas 兼容的几何类型可把地理空间工作流中计算密集的部分整体搬到 GPU 上执行。本文基于本仓库 optimize-for-gpu 技能下的 cuspatial 参考文档 展开结合仓库内技能骨架、安装指南、决策框架与代码转换模式等配套资料系统讲解 cuSpatial 25.04 的安装边界、GeoPandas 互操作、四叉树加速的空间连接、距离/轨迹/投影等核心 API以及沿用这套技能沉淀的性能调优与正确性验证方法帮助你为已有的大规模地理空间管线做出是否值得上 GPU、以及如何正确上 GPU的工程决策。阅读须知cuSpatial 已进入归档状态本文所有内容适用于固定在 25.04 依赖栈的独立遗留环境。仓库中 SKILL.md 明确将 cuSpatial 标注为 legacy-only归档于 25.04并要求在隔离环境中使用同时 decision_framework.md 和 code_transformation_patterns.md 提供了配套的选型与代码转换指引本文会随文引用。1. 项目定位cuSpatial 在 optimize-for-gpu 技能中的角色scientific-agent-skills 仓库的 optimize-for-gpu 技能面向在 NVIDIA 硬件上对科学计算 Python 代码做 GPU 加速并验证结果正确且更快的场景。该技能维护了一份 RAPIDS 生态的逐库参考清单CuPy、cuDF、cuML、cuGraph、cuVS、cuCIM、KvikIO、Warp、RAFT 等cuSpatial 即其中的地理空间条目。从 SKILL.md 的选择最小合适层一节可以看到cuSpatial 与 cuxfilter 一同被列入legacy-only表格项目状态指导原则cuxfilterFinal release 26.06仅维护现有仪表盘新工作建议用 cuDF HoloViews/hvPlot/DatashadercuSpatialArchived at 25.04仅在隔离的遗留环境中使用新工作建议几何运算留在 GeoPandas/ShapelyCPU用 cuDF 加速其中兼容的表格阶段同时tests/skill-requirements.toml 中[skills.optimize-for-gpu]段的packages []也印证了这一点技能本身不强制预装任何 GPU 包所有 RAPIDS 依赖包括 cuSpatial都交由使用方按实际环境按需安装——这既是为了兼容 CUDA 12/13 的 wheel 差异也是因为 cuSpatial 的归档特性决定了它必须被隔离安装。2. 安装与运行环境25.04 归档状态2.1 项目状态与版本边界cuSpatial 的开发已暂停GitHub 仓库于 2025 年 7 月 28 日归档只读最终版本为 v25.04——RAPIDS v25.06 及以后不再发布任何 cuSpatial 包对应 RAPIDS 停用通知 RSN 45。这带来三个直接影响包仍可安装、仍可运行但其依赖被钉死在 RAPIDS 25.04 时代的版本例如cudf-cu1225.4.*因此无法与当前 RAPIDS 发行版共存于同一环境不存在 CUDA 13-cu13变体——项目归档早于 CUDA 13 wheel 引入RAPIDS 官方未指定继任者——活跃维护的地理空间工作请使用 GeoPandas/ShapelyCPUcuSpatial 只保留给可以长期停留在 25.04 依赖栈的既有管线。这与 installation.md 中的归档说明完全一致cuSpatial 的安装指令被单独标注 ARCHIVED: frozen at 25.04, pins cudf-cu1225.4.*并强调只能在专用环境中安装、必须使用 NVIDIA 索引。2.2 安装命令参考文档要求独立示例使用uv add若用户项目已有包管理器则沿用该项目的约定。uv add --extra-index-urlhttps://pypi.nvidia.com cuspatial-cu1225.4.* # Final 25.04 release两个关键细节--extra-index-urlhttps://pypi.nvidia.com必须保留——PyPI 上的cuspatial-cu12入口只是一个 stub sdist真正的 wheel 托管在 pypi.nvidia.com安装 cuSpatial 会连带拉入cudf-cu1225.4.*及其相关的 25.04 版本钉扎依赖。2.3 安装验证import cuspatial from shapely.geometry import Point gs cuspatial.GeoSeries([Point(0, 0), Point(1, 1)]) print(gs)能正常构造并打印 GPU 端 GeoSeries 即说明安装成功。仓库的 installation.md 给出了同样的验证片段构造GeoSeries([Point(0, 0)])并打印 cuSpatial working。需要注意的是其余 RAPIDS 库的验证脚本cuDF 打印 GPU Series、cuML 打印版本号、cuVS 构建 CAGRA 索引等都假定当前 RAPIDS 26.06 环境不要把它们与 cuSpatial 放在同一个隔离环境里混用。3. GeoPandas 互操作CPU ↔ GPU 的双向通道cuSpatial 最主要的入口是从 GeoPandas 转换而来——任何GeoSeries或GeoDataFrame都可以搬到 GPUimport geopandas as gpd import cuspatial # GeoPandas - cuSpatialCPU - GPU gdf gpd.read_file(my_shapefile.shp) cu_gdf cuspatial.from_geopandas(gdf) # cuSpatial - GeoPandasGPU - CPU gdf_back cu_gdf.to_geopandas()也可以直接构造GeoDataFramecu_gdf cuspatial.GeoDataFrame(geopandas_dataframe)仓库的 code_transformation_patterns.md 给出了一份更贴近真实场景的前/后对照CPU 端用points.within(polygon)逐多边形生成布尔成员矩阵GPU 端用cuspatial.from_geopandas()完成同样的转换、再调用cuspatial.point_in_polygon。该文档特别提醒一个语义差异point_in_polygon返回的是布尔成员矩阵行点、列多边形不是geopandas.sjoin的一对一替代品——迁移前务必确认你原来的代码逻辑到底依赖哪种输出形态。4. GeoSeries 与 GeoDataFrameGPU 上的几何容器cuspatial.GeoSeries是持有 shapely 兼容几何对象Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon的 GPU 端序列。4.1 从 shapely 对象构造from shapely.geometry import Point, Polygon, LineString, MultiPoint import cuspatial points cuspatial.GeoSeries([Point(0, 0), Point(1, 1), Point(2, 2)]) polys cuspatial.GeoSeries([ Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]), Polygon([(2, 2), (3, 2), (3, 3), (2, 3), (2, 2)]) ])4.2 从坐标数组构造大数据更快import cudf # 从交错 xy 坐标构造 Points xy cudf.Series([0.0, 0.0, 1.0, 1.0, 2.0, 2.0]) # x0, y0, x1, y1, ... points cuspatial.GeoSeries.from_points_xy(xy) # 从交错 xy 几何偏移构造 MultiPoints multipoints cuspatial.GeoSeries.from_multipoints_xy( multipoints_xycudf.Series([0.0, 0.0, 1.0, 1.0, 2.0, 2.0, 3.0, 3.0]), geometry_offsetcudf.Series([0, 2, 4]) # 2 个 multipoint每个含 2 个点 )from_points_xy直接吃 cuDF Series避免了逐个 shapely 对象序列化的开销——这也是参考文档性能建议第 2 条的依据详见第 12 节。4.3 GeoSeries 常用属性gs cuspatial.GeoSeries([Point(0, 0), Point(1, 1)]) gs.points.xy # 访问原始交错坐标 gs.sizes # 每个几何体包含的点数 gs.iloc[0] # 访问单个几何体4.4 GeoDataFrame 构造cu_gdf cuspatial.GeoDataFrame({ geometry: cuspatial.GeoSeries([Point(0, 0), Point(1, 1)]), value: cudf.Series([10, 20]) })5. 空间连接点在多边形内Point in Polygon这是地理空间分析中最常见的操作判断哪些点落在哪些多边形内。5.1 朴素版本小数据from shapely.geometry import Point, Polygon import cuspatial points cuspatial.GeoSeries([Point(0, 0), Point(-8, -8), Point(6, 6)]) polygons cuspatial.GeoSeries([ Polygon([(-10, -10), (5, -10), (5, 5), (-10, 5), (-10, -10)]), Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]) ]) result cuspatial.point_in_polygon(points, polygons) # 返回布尔 DataFrame行点列多边形 # polygon_0 polygon_1 # 0 True True - (0,0) 同时落在两个多边形内 # 1 True False - (-8,-8) 只落在第一个内 # 2 False True - (6,6) 只落在第二个内配合仓库 code_transformation_patterns.md 中的迁移示例可以把它与 GeoPandas 的points.within(polygon)逐列堆叠写法做语义对照确保迁移前后输出矩阵的行点、列多边形语义一致。5.2 四叉树加速版本百万级点对于百万量级的点朴素暴力测试会对每个点×每个多边形做计算。四叉树管线会大幅削减需要真正执行的点-多边形测试数量共分四步import cuspatial import cudf # 1. 在点上构建四叉树 key_to_point, quadtree cuspatial.quadtree_on_points( points, # 点的 GeoSeries x_min, x_max, # 包围盒 y_min, y_max, scalescale, # 通常取 (max_extent) / (2^max_depth) max_depth7, # 最大树深 16 max_size125 # 叶子节点分裂前的最大点数 ) # 2. 计算多边形包围盒 poly_bboxes cuspatial.polygon_bounding_boxes(polygons) # 3. 将四叉树与包围盒连接 intersections cuspatial.join_quadtree_and_bounding_boxes( quadtree, poly_bboxes, x_min, x_max, y_min, y_max, scale, max_depth ) # 4. 只对相关象限做点在多边形内测试 result cuspatial.quadtree_point_in_polygon( intersections, quadtree, key_to_point, points, polygons ) # 返回含 polygon_index 与 point_index 两列的 DataFrame参数语义说明对应参考文档与空间索引一节scale网格分辨率推荐取值scale max(x_max - x_min, y_max - y_min) / (2 ** max_depth)max_depth最大树深必须小于 16Morton 码以 uint32 表示max_size叶子节点在分裂前可容纳的最大点数。6. 空间索引四叉树Quadtree在点集上构建四叉树空间索引是可扩展空间连接的基础设施key_to_point, quadtree cuspatial.quadtree_on_points( points, # 点的 GeoSeries x_min, x_max, # 兴趣区域包围盒 y_min, y_max, scale, # 网格分辨率 max_depth, # 最大树深必须 16 max_size # 每个节点分裂前的最大点数 ) # quadtree 是 DataFrame包含列 # key, level, is_internal_node, length, offset # key_to_point 把排序后的四叉树索引映射回原始点索引scale 的选择公式scale max(x_max - x_min, y_max - y_min) / (2 ** max_depth)四叉树是第 5.2 节空间连接、以及第 8 节点到最近线串查询的共同地基先粗粒度用包围盒剪枝再细粒度做精确几何测试。7. 距离函数7.1 Haversine 距离大圆距离面向经纬度坐标p1 cuspatial.GeoSeries([Point(lon1, lat1), Point(lon2, lat2)]) p2 cuspatial.GeoSeries([Point(lon3, lat3), Point(lon4, lat4)]) distances_km cuspatial.haversine_distance(p1, p2) # 返回 cudf.Series单位为公里7.2 两两点间距离欧氏from shapely.geometry import Point, MultiPoint p1 cuspatial.GeoSeries([Point(0, 0), Point(1, 0)]) p2 cuspatial.GeoSeries([Point(3, 4), Point(4, 3)]) dists cuspatial.pairwise_point_distance(p1, p2) # [5.0, 4.243]7.3 两两线串距离from shapely.geometry import LineString ls1 cuspatial.GeoSeries([LineString([(0, 0), (1, 1)])]) ls2 cuspatial.GeoSeries([LineString([(2, 0), (3, 1)])]) dists cuspatial.pairwise_linestring_distance(ls1, ls2)7.4 点到线串距离pts cuspatial.GeoSeries([Point(0, 0)]) lines cuspatial.GeoSeries([LineString([(1, 0), (0, 1)])]) dists cuspatial.pairwise_point_linestring_distance(pts, lines)7.5 有向 Hausdorff 距离from shapely.geometry import MultiPoint spaces cuspatial.GeoSeries([ MultiPoint([(0, 0), (1, 0)]), MultiPoint([(0, 1), (0, 2)]) ]) hausdorff cuspatial.directed_hausdorff_distance(spaces) # 返回 DataFramehausdorff[i][j] 从空间 i 到 j 的有向 Hausdorff 距离8. 最近点找每个点到某条线串上最近的点result cuspatial.pairwise_point_linestring_nearest_points(points, linestrings) # 返回 GeoDataFrame包含 # point_geometry_id, linestring_geometry_id, segment_id, geometry最近点四叉树加速的最近线串查询result cuspatial.quadtree_point_to_nearest_linestring( linestring_quad_pairs, quadtree, key_to_point, points, linestrings ) # 返回 DataFrame包含point_index, linestring_index, distance9. 包围盒Bounding Boxes# 多边形包围盒 poly_bboxes cuspatial.polygon_bounding_boxes(polygons) # 返回 DataFrameminx, miny, maxx, maxy # 线串包围盒带扩展半径 line_bboxes cuspatial.linestring_bounding_boxes(linestrings, expansion_radius0.5)包围盒既是第 5.2 节四叉树空间连接的第 2 步输入也是独立的空间裁剪工具expansion_radius允许在包围盒四周外扩一个缓冲区适合找线串附近 N 距离内的对象这类带容差的查询。10. 投影Sinusoidal 投影经纬度 → 笛卡尔公里当所有点都邻近某个参考原点时可用 Sinusoidal 投影把地理坐标近似转为笛卡尔坐标origin_lon, origin_lat -73.9857, 40.7484 # 例如纽约 lonlat_points cuspatial.GeoSeries([Point(-73.98, 40.75), Point(-73.99, 40.74)]) xy_km cuspatial.sinusoidal_projection(origin_lon, origin_lat, lonlat_points) # 返回投影后 (x, y) 点的 GeoSeries单位为公里11. 空间过滤在矩形窗口内过滤点filtered cuspatial.points_in_spatial_window( points, min_x-10, max_x10, min_y-10, max_y10 ) # 返回只含窗口内点的 GeoSeries12. 轨迹分析从带时间戳的点数据例如车辆 GPS 轨迹中识别、重建并分析轨迹。12.1 推导轨迹objects, traj_offsets cuspatial.derive_trajectories( object_ids[0, 1, 0, 1], # 例如车辆 ID pointscuspatial.GeoSeries([Point(0,0), Point(0,0), Point(1,1), Point(1,1)]), timestamps[0, 0, 10000, 10000] ) # objects: 按 (object_id, timestamp) 排序的 DataFrame含 x, y, timestamp # traj_offsets: 标记每条轨迹起始位置的偏移 Series12.2 距离与速度dist_speed cuspatial.trajectory_distances_and_speeds( len(traj_offsets), objects[object_id], objects_points, # GeoSeries objects[timestamp] ) # 返回 DataFrame每条轨迹含 distance公里和 speed米/秒12.3 轨迹包围盒traj_bboxes cuspatial.trajectory_bounding_boxes( len(traj_offsets), objects[object_id], objects_points ) # 返回 DataFrame每条轨迹的 x_min, y_min, x_max, y_max注意derive_trajectories的输入示例中 object_ids 为[0, 1, 0, 1]且 timestamps 为[0, 0, 10000, 10000]——同一 object_id 按时间戳递增重组为轨迹这正是轨迹的本质定义同一对象按时间排序的连续观测序列。13. 二元空间谓词Binary PredicatesGeoSeries支持 GeoPandas 兼容的二元空间谓词全部由 GPU 加速# 以下均返回 cudf.Series 布尔值 polys.contains(points) # 每个点是否在多边形内 polys.contains_properly(points) # 严格位于内部不在边界上 geom_a.covers(geom_b) # A 是否覆盖 B geom_a.crosses(geom_b) # 几何体是否相交贯穿 geom_a.disjoint(geom_b) # 是否不相交 geom_a.distance(geom_b) # 两两距离 geom_a.geom_equals(geom_b) # 是否几何相等 geom_a.intersects(geom_b) # 是否相交 geom_a.overlaps(geom_b) # 是否重叠 geom_a.touches(geom_b) # 是否相触 geom_a.within(geom_b) # A 是否在 B 内部contains与contains_properly支持allpairsTrue模式返回所有点-多边形包含配对当你有 M 个点、N 个多边形、需要全部匹配时非常有用result polygons.contains(points, allpairsTrue) # 返回 DataFrame含 point_indices 和 polygon_indices 两列这为第 5 节的point_in_polygon提供了谓词层面的等价通道行式需求用默认模式全量配对需求用allpairsTrue避免自己展开数据。14. 性能优化建议参考文档给出五条性能要点结合仓库技能的整体方法论SKILL.md 的优化工作流可进一步强化大数据集务必走四叉树管线。暴力point_in_polygon对每个点×每个多边形做测试四叉树管线quadtree_on_pointsjoin_quadtree_and_bounding_boxesquadtree_point_in_polygon用空间索引预过滤在百万级点/多边形场景下可能快若干个数量级。用坐标数组而非 shapely 对象构造 GeoSeries。GeoSeries.from_points_xy()配 cuDF Series 远比从 shapely Point 对象列表构造快——后者需要逐几何体序列化。让数据留在 GPU 上。cuSpatial 与 cuDF 深度集成——用cudf.read_csv()或cudf.read_parquet()读入数据再从坐标列构造 GeoSeries避免大数据在 GeoPandas 之间来回往返。这与技能保持连贯的 GPU 数据路径原则一致输入只传输一次中间结果保持设备驻留。多对多空间连接用allpairsTrue。需要全部点-多边形配对而非逐行时用contains(points, allpairsTrue)而非自行展开数据。与 cuDF 组合成完整管线。cuSpatial 返回 cuDF DataFrame/Series因此可以在不离开 GPU 的情况下与 cuDF 的过滤、groupby、join 无缝串联。在此基础上技能方法论还要求用正确的方式测量加速SKILL.md 第 6 步GPU 工作是异步的用 CPU 计时器包住未同步的调用测到的是入队时间。应预热上下文创建与 JIT 编译再用 CUDA 事件或库感知计时器例如from cupyx.profiler import benchmark print(benchmark(gpu_function, (arg1, arg2), n_warmup10, n_repeat100))笔记本中用%gpu_timeit端到端时间线用 Nsight Systemsnsys内核分析用 Nsight Computencu。只有通过了正确性校验、且在代表性数据上确实改善了目标指标GPU 路径才应被保留。15. 常见陷阱多边形必须闭合。每个多边形环的首尾坐标必须相同。Shapely 会自动处理闭合但若从原始坐标构造务必保证闭合。部分操作要求 GeoSeries 为单一类型。例如pairwise_point_distance要求序列只含 Point 或只含 MultiPoint——同一序列内不能混类型。四叉树 max_depth 必须小于 16。Morton 码以 uint32 表示因此 max_depth 必须小于 16。Haversine 期望 (lon, lat) 而非 (lat, lon)。cuSpatial 遵循 (经度, 纬度) 约定与 shapely/GeoJSON 一致——不要与某些地图 API 的 (纬度, 经度) 约定混淆。无 CRS 变换。cuSpatial 不处理坐标系转换。搬到 GPU 前请先用 GeoPandas/pyproj 把数据投影到正确的 CRS。这正是第 10 节 Sinusoidal 投影函数存在的意义需要局部笛卡尔坐标时先完成投影再交给距离类函数。16. 何时使用、何时放弃迁移决策与配套资料cuSpatial 的归档属性意味着它不是默认选项。综合 decision_framework.md 的 cuSpatial 专节决策要点如下应当维护 cuSpatial一个已隔离的 25.04 环境已经在跑 GeoPandas 空间操作点在多边形内、空间连接、距离计算、轨迹分析GPS 轨迹分组、速度/距离计算、四叉树空间索引或经纬度 Haversine 距离且愿意停留在旧依赖栈不应作为现状方案不要把它当作当前 GeoPandas 的替代品也不要与当前 RAPIDS 26.06 包混装新工作几何运算保留在 GeoPandas/ShapelyCPU表格阶段用 cuDF 加速这是技能给出的推荐路径。仓库提供了三份可直接沿用的配套资料完整的逐库安装命令与 CUDA 版本选择见 references/installation.md全部 RAPIDS 库的何时用/何时错决策框架见 references/decision_framework.mdGeoPandas 点-多边形到 cuSpatial 的前后对照代码见 references/code_transformation_patterns.md。写作任何 cuSpatial 代码前先读对应参考文件——参考文档强调API 名称即使与 GeoPandas 兼容其默认值、dtype、输出类型与支持参数仍可能有差异。小结cuSpatial 在 25.04 冻结版本上提供了完整的 GPU 地理空间能力——GeoPandas 互操作、四叉树空间索引、点-多边形空间连接、五类距离函数、最近点、包围盒、Sinusoidal 投影、空间过滤、轨迹分析以及全套二元谓词。对于能够长期固定在 25.04 依赖栈的既有管线它是把计算密集环节整体搬到 GPU 的高性价比通道但对于新项目请遵循本仓库 optimize-for-gpu 技能的决策框架把几何运算留在 GeoPandas/Shapely并用 cuDF 加速表格阶段。无论走哪条路径迁移前先建立 CPU 基线与正确性契约、迁移后用同步计时验证端到端收益是让 GPU 加速真正可靠的先决条件。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考