简介scikit-geometry 是一套面向科学计算与几何算法开发的 Python 封装库适合具备一定 Python 基础、希望借助成熟计算几何能力解决实际问题的开发者与研究者。它主要封装了 C 计算几何算法库 CGAL 的核心功能提供 Point2、Point3、Segment2、Ray2、Line2、Circle2、Plane3、Triangle3、Polyhedron3 等基本几何类型并支持线段构造、相交测试、凸包、Voronoi 图、布尔运算、骨架提取、主成分分析等操作可用于机器人路径规划、CAD 建模、地理信息处理等场景。资源包共 61 个文件约 273KB包含 18 个 cpp 源文件、12 个 py 脚本、10 个 ipynb 示例笔记以及 yml 配置、hpp 头文件、rst 文档等覆盖源码、测试与文档多个层面。目前已有 2123 人学习下载。通过其中的 Jupyter Notebook 示例与测试脚本读者可快速理解几何算法的调用方式并借助源码与文档深入掌握封装细节为二次开发与算法验证提供参考。1. scikit-geometry当几何计算开始像 NumPy 一样顺手做几何算法的人大概都有过这种体验算个多边形布尔运算先翻 CGAL 文档再配 Boost 依赖最后被模板报错糊一脸。scikit-geometry 想干的事就是把这类计算收进 Python 的调用习惯里——import skgeom as sg然后像操作数组一样操作点、线段、多边形。它底层绑的是 CGAL但暴露出来的接口是 Python 原生的不需要你写 C 模板也不需要手动管理内存。适合谁做 CAD 原型、机器人路径规划、GIS 空间分析、游戏碰撞检测的开发者尤其是那些想快速验证几何思路、不想在编译环境上耗三天的人。这一章先把「它是什么、边界在哪」讲清楚后面几章再动手。2. 环境搭建与第一个多边形从安装到布尔运算跑通2.1 为什么选 scikit-geometry 而不是自己包 CGAL自己用 pybind11 或 Cython 包 CGAL最直接的代价是编译时间和模板实例化爆炸。CGAL 的精确谓词和惰性求值机制在 C 里是优势但暴露到 Python 时如果接口设计不好每次调用都可能在 Python 和 C 之间来回拷贝数据。scikit-geometry 的做法是把常用几何对象做成 Python 类内部持有 CGAL 的句柄运算在 C 侧完成只把结果传回来。常见做法是先用它做算法验证确认几何逻辑没问题后再决定是否下沉到 C 做性能优化。我一般会建议团队里做算法原型的同学先用它因为改一行 Python 比改一行模板快太多。另一个选型理由是它的 API 命名跟 shapely 有相似之处但底层精度策略不同。shapely 基于 GEOS浮点运算为主scikit-geometry 走的是 CGAL 的精确谓词路线在退化情况比如三点共线、自相交多边形下更稳。如果你的场景里经常出现「理论上应该相交但浮点算出来不相交」那这个差异就值得关注。2.2 安装conda 与 pip 的取舍scikit-geometry 的依赖里有 CGAL 和 Boost直接 pip install 在部分平台上会触发源码编译耗时且容易缺头文件。我一般优先走 conda# 创建独立环境避免和系统里的 CGAL 版本打架 conda create -n skgeom python3.10 conda activate skgeom # conda-forge 渠道有预编译包省去编译 CGAL 的麻烦 conda install -c conda-forge scikit-geometry如果只能用 pip先确认系统里有 CGAL 头文件和 Boost# Ubuntu 系示例安装编译期依赖 sudo apt-get install libcgal-dev libboost-all-dev # 再装 Python 包此时会走源码编译 pip install scikit-geometry装完后验证import skgeom as sg print(sg.__version__) # 能打印版本号就说明底层绑定加载成功参数说明python3.10不是硬性要求3.8 到 3.11 一般都可以但建议避开刚发布的 Python 大版本因为预编译包跟进有延迟。conda-forge 的包名就是scikit-geometry不要写成skgeom。2.3 构造点、线段、多边形并做布尔运算先跑一个最小闭环两个矩形求交。import skgeom as sg from skgeom import Point2, Segment2, Polygon # 用逆时针顺序给顶点CGAL 对多边形方向敏感 rect_a Polygon([ Point2(0, 0), Point2(4, 0), Point2(4, 3), Point2(0, 3), ]) rect_b Polygon([ Point2(2, 1), Point2(6, 1), Point2(6, 4), Point2(2, 4), ]) # 布尔交集返回一个新的 Polygon 对象 inter sg.boolean_set.intersection(rect_a, rect_b) # 遍历结果的顶点 for poly in inter: print(交点数量:, len(poly.vertices)) for v in poly.vertices: print(v.x(), v.y())逻辑说明boolean_set.intersection返回的是一个可迭代对象因为两个多边形的交集可能不止一个连通分量。每个分量是一个 Polygonvertices是顶点迭代器。参数上顶点顺序必须是逆时针顺时针会导致有向面积符号相反布尔运算结果可能为空或异常。如果拿到的数据源方向不确定可以先做一次方向校正# 检查有向面积为负则反转顶点顺序 def ensure_ccw(poly): area sum( poly.vertices[i].x() * poly.vertices[(i1) % len(poly.vertices)].y() - poly.vertices[(i1) % len(poly.vertices)].x() * poly.vertices[i].y() for i in range(len(poly.vertices)) ) / 2.0 if area 0: # 反转顶点列表后重新构造 verts list(poly.vertices)[::-1] return Polygon(verts) return poly这段代码里的area是鞋带公式判断方向用。注意 scikit-geometry 的 Polygon 构造后顶点顺序就固定了没有原地反转的方法得重新构造。3. 精确谓词与退化情况为什么浮点几何总在关键时刻翻车3.1 浮点误差在几何里的典型表现用浮点算几何最经典的问题是「明明共线的三点算出来不共线」。比如判断点是否在线段上浮点做法是算叉积是否接近零但阈值设多少都有人不服。CGAL 的精确谓词用自适应精度算术先按浮点算如果结果落在不确定区间再提升精度重算直到符号确定。scikit-geometry 把这个能力带到了 Python 层。看一个退化例子from skgeom import Point2, Segment2 # 三个点理论上共线 p Point2(0, 0) q Point2(1, 1) r Point2(2, 2) seg Segment2(p, q) # orientation 判断点 r 相对线段 pq 的方向 # 返回 0 表示共线正负表示左右 result sg.orientation(p, q, r) print(orientation:, result) # 精确谓词下会稳定返回 0而不是 1e-16 之类的浮点噪声逻辑说明sg.orientation是 CGAL 精确谓词的直接暴露返回值是整数符号不是浮点。参数顺序是「起点、终点、待判断点」。这个函数在实现凸包、线段相交、点在多边形内判断时是基础构件。如果你自己用叉积写在接近共线时就会遇到符号跳变导致凸包多一个点或少一个点。3.2 用精确谓词重写「点是否在多边形内」浮点版本的射线法在边界附近容易误判。用 scikit-geometry 的Polygon自带方法from skgeom import Point2, Polygon poly Polygon([ Point2(0, 0), Point2(5, 0), Point2(5, 5), Point2(0, 5), ]) test_point Point2(2.5, 2.5) # 判断点是否在多边形内部 inside poly.contains(test_point) print(inside:, inside) # 边界上的点 boundary_point Point2(0, 2.5) print(on boundary:, poly.contains(boundary_point))逻辑说明contains内部走的是 CGAL 的精确判断边界情况有明确语义。参数上test_point必须是 Point2 对象不能直接传元组。如果数据量大逐个构造 Point2 会有开销可以先把坐标列表转成 Point2 列表再批量判断。注意contains对边界点的返回值取决于具体实现版本稳妥做法是同时用on_boundary类方法确认或者自己用orientation组合判断。3.3 退化情况下的布尔运算稳定性两个多边形共享一条边时布尔运算最容易出问题。浮点实现可能返回一个细长的碎片精确谓词下会正确合并或分割。from skgeom import Point2, Polygon import skgeom # 两个矩形共享一条边 x2 left Polygon([Point2(0,0), Point2(2,0), Point2(2,2), Point2(0,2)]) right Polygon([Point2(2,0), Point2(4,0), Point2(4,2), Point2(2,2)]) # 求并集 union_result skgeom.boolean_set.join(left, right) for poly in union_result: print(并集顶点数:, len(poly.vertices)) # 精确谓词下应该得到一个 4 个顶点的矩形而不是两个分离的碎片逻辑说明boolean_set.join是并集操作。共享边在精确算术下会被正确识别为内部边结果合并成一个多边形。如果换成浮点库共享边上的点可能因为微小误差被判定为不相交结果返回两个独立多边形。参数上两个多边形的顶点顺序都要是逆时针否则并集结果可能不符合预期。4. 避坑与排查scikit-geometry 落地时的五个血泪经验4.1 坑一顶点顺序反了布尔运算返回空现象两个明显相交的多边形intersection返回空列表。 原因其中一个多边形顶点是顺时针有向面积为负CGAL 把它当成「洞」或无效区域处理。 解决构造前统一做方向校正用 2.3 里的ensure_ccw函数过一遍。如果数据来自 GeoJSON注意 GeoJSON 规范里外环是逆时针、内环是顺时针转换时要对齐。4.2 坑二Point2 不能直接当元组用现象poly.contains((2.5, 2.5))报类型错误。 原因scikit-geometry 的接口要求显式 Point2 对象不做隐式转换。 解决统一在数据入口处把坐标转成 Point2。如果从 NumPy 数组来写一个转换函数import numpy as np from skgeom import Point2 def array_to_points(arr): # arr 形状为 (N, 2) return [Point2(float(x), float(y)) for x, y in arr]参数说明float()强制转换是为了避免 NumPy 的 float32 传进去后精度不够CGAL 内部按 double 算但入口处统一成 Python float 更稳。4.3 坑三大量小对象导致内存增长现象循环里反复构造 Polygon 和 Point2内存持续上涨。 原因CGAL 对象在 Python 侧有句柄垃圾回收不及时会堆积。 解决把循环拆成批次每批处理完显式del并触发gc.collect()。更根本的做法是尽量用批量接口比如把多个多边形放进一个列表一次性做布尔运算而不是逐个循环。4.4 坑四conda 和 pip 混装导致绑定加载失败现象import skgeom报ImportError: undefined symbol。 原因conda 装的 CGAL 版本和 pip 编译时链接的版本不一致。 解决一个环境里只用一种安装方式。如果已经混了先conda remove scikit-geometry再pip uninstall scikit-geometry清干净后重装。检查conda list | grep cgal和pip list | grep geometry确认没有残留。4.5 坑五布尔运算结果顶点数暴增现象两个简单多边形求交结果有几百个顶点。 原因输入多边形有自相交或重复顶点CGAL 在精确计算时把退化边拆成了多个段。 解决运算前先做清理去重顶点、检查自相交。scikit-geometry 没有内置的simplify但可以用Polygon的is_simple类方法检查不简单就先用其他工具修。常见做法是先用 shapely 的buffer(0)修自相交再转成 scikit-geometry 的 Polygon。5. 进阶技巧用 scikit-geometry 做凸包与骨架提取5.1 凸包从点集到最小外接多边形凸包是很多几何流水线的第一步。scikit-geometry 提供了convex_hullfrom skgeom import Point2 import skgeom import random # 生成随机点集 random.seed(42) points [Point2(random.uniform(0, 10), random.uniform(0, 10)) for _ in range(50)] # 计算凸包返回一个 Polygon hull skgeom.convex_hull(points) print(凸包顶点数:, len(hull.vertices)) for v in hull.vertices: print(f({v.x():.2f}, {v.y():.2f}))逻辑说明convex_hull接受 Point2 的可迭代对象返回逆时针方向的凸包 Polygon。参数上点集里如果有重复点精确谓词会正确处理不会影响结果。如果点集共线返回的是一条退化多边形顶点数为 2后续使用时要判断len(hull.vertices) 3再做面积计算。5.2 骨架提取用中轴变换做路径规划scikit-geometry 里有skeleton模块可以对多边形做中轴变换得到骨架图。这在机器人路径规划里很有用——骨架上的点天然远离边界适合做安全路径。from skgeom import Point2, Polygon from skgeom.skeleton import StraightSkeleton # 构造一个 L 形多边形 poly Polygon([ Point2(0, 0), Point2(4, 0), Point2(4, 2), Point2(2, 2), Point2(2, 4), Point2(0, 4), ]) # 计算直线骨架 skeleton StraightSkeleton(poly) # 遍历骨架边 for edge in skeleton.edges: src edge.source tgt edge.target print(f骨架边: ({src.x():.1f},{src.y():.1f}) - ({tgt.x():.1f},{tgt.y():.1f}))逻辑说明StraightSkeleton对简单多边形有效输入必须是非自相交的。edges返回的是骨架边集合每条边有source和target两个端点。参数上多边形顶点顺序影响骨架方向但不影响拓扑结构。如果多边形有洞需要额外处理当前接口对带洞多边形的支持有限常见做法是把洞单独提出来做约束。5.3 验证方法用面积守恒检查布尔运算布尔运算做完后怎么确认结果对一个简单办法是面积守恒两个多边形并集的面积等于各自面积之和减去交集面积。import skgeom from skgeom import Point2, Polygon a Polygon([Point2(0,0), Point2(3,0), Point2(3,3), Point2(0,3)]) b Polygon([Point2(1,1), Point2(4,1), Point2(4,4), Point2(1,4)]) area_a abs(skgeom.area(a)) area_b abs(skgeom.area(b)) inter list(skgeom.boolean_set.intersection(a, b)) area_inter sum(abs(skgeom.area(p)) for p in inter) union list(skgeom.boolean_set.join(a, b)) area_union sum(abs(skgeom.area(p)) for p in union) # 面积守恒检查 print(a b - inter , area_a area_b - area_inter) print(union area , area_union) # 两者应该相等误差在精确算术下为 0逻辑说明skgeom.area返回有向面积取绝对值得到实际面积。intersection和join返回可迭代对象可能有多个分量所以用列表推导求和。这个检查在调试布尔运算时很实用如果两边对不上说明输入多边形有问题或者运算结果有退化分量。我自己的习惯是每次换数据集或改几何逻辑后先跑一遍面积守恒检查再跑业务逻辑。这个习惯帮我省过好几次「结果看起来对但实际有碎片」的后悔药。几何计算没有黑匣子精确谓词给了你确定性但前提是输入得干净、方向得对、退化情况得提前想到。希望帮到你。本文还有配套的精品资源点击获取