简介scikit-geometry 是一套面向科学计算与几何算法开发的 Python 封装库适合具备一定 Python 基础、希望借助成熟计算几何能力解决实际问题的开发者与研究者。它主要封装 CGAL 的核心功能提供 Point2/Point3、Segment、Ray、Line、Vector、Circle、Plane、Triangle、Polyhedron 等基本几何类型并支持相交测试、凸包、Voronoi/Delaunay、布尔运算、骨架提取、PCA 等操作可用于机器人路径规划、CAD 建模、地理信息处理与图形学实验等场景。资源包共 61 个文件约 273KB包含 18 个 cpp 与 3 个 hpp 源码、12 个 py 模块、10 个 ipynb 示例笔记以及 yml 配置、rst 文档、scss/css 样式和 Makefile 等构建文件结构覆盖源码、测试、文档与示例。目前已有 2123 人学习下载读者可借助 Jupyter Notebook 示例快速理解几何对象构造与算法调用通过测试脚本与文档掌握封装思路并参考 C 源码深入 CGAL 绑定实现适合作为几何算法学习与二次开发的实用起点。1. 当 Python 遇上计算几何scikit-geometry 到底能省下多少造轮子的时间如果你用 Python 做过几何相关的活儿大概率经历过这个场景想算两条线段的交点随手写了十几行坐标判断结果遇到共线、端点重合、浮点误差就开始出玄学 bug想做个多边形布尔运算搜到的库要么只能处理凸多边形要么依赖一大堆编译工具链装一晚上都装不上。scikit-geometry 就是冲着这类问题来的——它把 CGAL 这个计算几何领域的工业级 C 库用 pybind11 封装成了 Python 接口让你在 Jupyter Notebook 里几行代码就能调用经过严格数值验证的几何算法。这个库适合谁做 GIS 空间分析的、搞 CAD 二次开发的、写机器人路径规划的、做图像处理里轮廓操作的以及任何需要在 Python 里处理多边形、线段、圆、贝塞尔曲线等几何对象的开发者。它不是一个玩具库底层 CGAL 在学术界和工业界被验证了几十年scikit-geometry 做的事情是让你不用写 C、不用配 CMake、不用手动管理内存就能用上这套算法。接下来我从安装、核心数据结构、布尔运算、凸包、曲线处理几个角度把这份资源拆开讲清楚。2. 安装与第一个几何对象从 pip 到 Jupyter 的完整链路2.1 安装方式与依赖环境scikit-geometry 的安装方式取决于你的平台。最省事的是 conda因为 CGAL 本身依赖 Boost、GMP、MPFR 这些 C 库conda 能一次性把二进制依赖拉齐# 推荐方式conda 安装自动处理 CGAL 的 C 依赖 conda install -c conda-forge scikit-geometry # pip 方式需要系统里已有 CGAL 头文件和编译工具链 pip install scikit-geometry如果你走 pip 路线在 Ubuntu 上通常需要先装libcgal-dev、libgmp-dev、libmpfr-devmacOS 上需要brew install cgal gmp mpfr。Windows 用户建议直接用 condapip 在 Windows 上编译 CGAL 绑定的翻车概率很高血泪经验。安装完之后验证一下# 验证安装是否成功并查看版本 import skgeom as sg print(sg.__version__) # 创建一个简单的点确认基本功能可用 p sg.Point2(1.0, 2.0) print(p.x(), p.y()) # 输出 1.0 2.0这里sg.Point2是二维点坐标用双精度浮点存储。注意 CGAL 的内核有精确谓词exact predicates意味着它在判断方向、相交时不会因为浮点误差给出错误结果但坐标本身仍然是浮点数。这个区别在后面讲布尔运算时会体现出来。2.2 核心数据结构点、线段、多边形scikit-geometry 的对象体系跟 CGAL 的 2D 内核对应常用的几类类型构造方式典型用途Point2sg.Point2(x, y)表示二维坐标点Segment2sg.Segment2(p1, p2)线段支持求交、方向判断Polygonsg.Polygon([p1, p2, p3])简单多边形顶点按顺序传入PolygonWithHoles带孔多边形复杂区域表示Circlesg.Circle(center, radius)圆支持与线段求交构造一个多边形并做基本操作import skgeom as sg # 用四个点构造一个正方形顶点按逆时针顺序传入 square sg.Polygon([ sg.Point2(0, 0), sg.Point2(4, 0), sg.Point2(4, 4), sg.Point2(0, 4) ]) # 判断点是否在多边形内部 inside square.orientation() # 返回顶点绕向COUNTERCLOCKWISE 或 CLOCKWISE print(绕向:, inside) # 计算面积和周长 print(面积:, square.area()) # 应为 16.0 print(周长:, square.perimeter()) # 应为 16.0 # 判断一个点是否在多边形内 test_point sg.Point2(2, 2) print(点在多边形内:, square.orientation() and square.area() 0)这里orientation()返回的是顶点绕向CGAL 要求多边形顶点按一致方向排列逆时针为正。如果你传入的顶点顺序混乱后续布尔运算会直接报错或给出错误结果。area()返回的是有符号面积绕向正确时为正。提示构造 Polygon 时顶点顺序必须是简单多边形不自交且首尾不重复。传入自交多边形不会报错但后续操作结果不可预期。2.3 线段求交与方向判断线段求交是计算几何里最基础也最容易出问题的操作。手写的话要处理平行、共线、端点相交等一堆边界情况scikit-geometry 直接给你封装好了import skgeom as sg # 定义两条线段 s1 sg.Segment2(sg.Point2(0, 0), sg.Point2(4, 4)) s2 sg.Segment2(sg.Point2(0, 4), sg.Point2(4, 0)) # 求交点 result sg.intersection(s1, s2) print(交点:, result) # 应输出 Point2(2, 2) # 判断两条线段是否相交 print(是否相交:, sg.do_intersect(s1, s2)) # True # 方向判断点在线段的哪一侧 p sg.Point2(1, 3) orientation sg.orientation(s1.source(), s1.target(), p) print(方向:, orientation) # LEFT_TURN / RIGHT_TURN / COLLINEARsg.intersection返回的对象类型取决于输入类型组合可能是 Point2、Segment2共线重叠时或 None。sg.do_intersect只返回布尔值不做实际计算性能更好。sg.orientation是 CGAL 精确谓词的核心接口返回三个枚举值之一不会因为浮点误差把共线判成左转。这三个函数看起来简单但它们是后面所有复杂操作的基础。布尔运算、凸包、三角剖分内部都在反复调用这些谓词。理解它们的返回值和边界行为排错时能省很多时间。3. 布尔运算与凸包把多边形操作从手写坐标里解放出来3.1 多边形布尔运算并、交、差多边形布尔运算是 scikit-geometry 最常用的功能之一。手写这个算法基本等于重新实现一遍 Weiler-Atherton 或 Vatti 算法还要处理退化边、孔洞、自交等一堆情况。scikit-geometry 直接调用 CGAL 的布尔运算内核import skgeom as sg # 构造两个重叠的多边形 poly_a sg.Polygon([ sg.Point2(0, 0), sg.Point2(4, 0), sg.Point2(4, 4), sg.Point2(0, 4) ]) poly_b sg.Polygon([ sg.Point2(2, 2), sg.Point2(6, 2), sg.Point2(6, 6), sg.Point2(2, 6) ]) # 并集 union sg.boolean_operation(poly_a, poly_b, sg.BooleanOperation.Union) print(并集面积:, union.area()) # 两个正方形并集面积 28 # 交集 intersection sg.boolean_operation(poly_a, poly_b, sg.BooleanOperation.Intersection) print(交集面积:, intersection.area()) # 重叠区域 2x2面积 4 # 差集A 减去 B difference sg.boolean_operation(poly_a, poly_b, sg.BooleanOperation.Difference) print(差集面积:, difference.area()) # A 去掉重叠部分面积 12boolean_operation的第三个参数是枚举控制运算类型。返回结果可能是PolygonWithHoles因为差集或交集可能产生带孔的区域。area()对带孔多边形会正确扣除孔洞面积。这里有个容易踩的坑两个多边形的顶点绕向必须一致。如果 poly_a 是逆时针、poly_b 是顺时针布尔运算结果可能为空或报错。我一般会在构造后统一检查一遍绕向# 统一绕向确保所有多边形都是逆时针 def ensure_ccw(poly): if poly.orientation() sg.Orientation.CLOCKWISE: return sg.Polygon(list(reversed(list(poly.vertices())))) return poly poly_a ensure_ccw(poly_a) poly_b ensure_ccw(poly_b)vertices()返回顶点迭代器reversed反转顺序重新构造后绕向就统一了。这个函数看起来简单但在批量处理 GIS 数据时能避免大量莫名其妙的空结果。3.2 凸包与最小包围盒凸包是另一个高频操作。scikit-geometry 提供了 Graham 扫描和 Andrew 单调链两种实现接口统一import skgeom as sg import random # 生成一组随机点 points [sg.Point2(random.uniform(0, 10), random.uniform(0, 10)) for _ in range(50)] # 计算凸包 hull sg.convex_hull(points) print(凸包顶点数:, len(list(hull.vertices()))) print(凸包面积:, hull.area()) # 最小包围盒旋转卡壳 box sg.min_rectangle(points) print(最小包围盒面积:, box.area())convex_hull接受点列表返回一个 Polygon。min_rectangle返回的是最小面积包围矩形内部用旋转卡壳算法比手写省事得多。注意这两个函数对输入点的数量有要求少于 3 个点会抛异常。凸包在碰撞检测、形状分析、点云预处理里用得很多。我一般会先用凸包把点云简化再做后续处理能显著降低计算量。3.3 三角剖分与 DelaunayDelaunay 三角剖分在有限元网格生成、地形建模、插值计算里是刚需。scikit-geometry 封装了 CGAL 的 Delaunay 三角剖分import skgeom as sg # 构造 Delaunay 三角剖分对象 tri sg.Triangulation() # 插入点集 points [sg.Point2(0, 0), sg.Point2(4, 0), sg.Point2(2, 3), sg.Point2(1, 1), sg.Point2(3, 1)] for p in points: tri.insert(p) # 遍历所有三角形 for face in tri.finite_faces(): v0 tri.vertex(face.vertex(0)) v1 tri.vertex(face.vertex(1)) v2 tri.vertex(face.vertex(2)) print(f三角形: ({v0.point().x()}, {v0.point().y()}), f({v1.point().x()}, {v1.point().y()}), f({v2.point().x()}, {v2.point().y()}))Triangulation是增量式构造插入点的顺序会影响内部结构但不影响最终结果。finite_faces()返回所有有限面排除无穷面每个面通过vertex(i)拿到顶点索引再用tri.vertex(idx)拿到实际顶点对象。注意Delaunay 三角剖分对共线点敏感。如果输入点里有三个以上严格共线CGAL 会生成退化三角形面积为零。实际使用前建议先做一遍去重和共线检测。4. 曲线与贝塞尔处理非直线几何的实操细节4.1 贝塞尔曲线构造与求值scikit-geometry 支持贝塞尔曲线这在字体渲染、路径规划、动画插值里很有用import skgeom as sg # 构造一条三次贝塞尔曲线 curve sg.BezierCurve([ sg.Point2(0, 0), sg.Point2(1, 3), sg.Point2(3, 3), sg.Point2(4, 0) ]) # 在参数 t0.5 处求值 point curve(0.5) print(中点坐标:, point.x(), point.y()) # 计算曲线长度近似 length curve.length() print(曲线长度:, length) # 求曲线与线段的交点 seg sg.Segment2(sg.Point2(0, 1.5), sg.Point2(4, 1.5)) intersections sg.intersection(curve, seg) for pt in intersections: print(交点:, pt.x(), pt.y())BezierCurve接受控制点列表阶数由控制点数量决定。curve(t)是调用运算符返回参数 t 处的点。length()内部用数值积分精度够用但不是解析解。曲线与线段求交返回的是交点列表可能为空、一个或多个。这里 CGAL 的精确谓词同样起作用不会因为浮点误差漏掉相切的情况。4.2 曲线偏移与包络曲线偏移在 CNC 加工路径生成、道路缓冲区分析里是常见需求import skgeom as sg # 构造一条简单曲线 curve sg.BezierCurve([ sg.Point2(0, 0), sg.Point2(2, 4), sg.Point2(6, 4), sg.Point2(8, 0) ]) # 计算偏移曲线偏移距离 0.5 offset curve.offset(0.5) print(偏移曲线控制点数:, len(offset.control_points())) # 注意偏移结果可能自交需要后续处理offset返回一条新的贝塞尔曲线但偏移后的曲线在曲率大的地方可能自交。CGAL 提供了自交检测和修剪的接口但 scikit-geometry 的封装程度有限复杂场景下可能需要手动处理。我一般会先用offset拿到近似结果再用sg.intersection检测自交最后手动修剪。这个过程在 Jupyter 里交互式调试比较方便能看到每一步的中间结果。4.3 在 Jupyter 里可视化几何对象scikit-geometry 自带一个基于 matplotlib 的绘图模块在 Jupyter Notebook 里可以直接画import skgeom as sg from skgeom.draw import draw # 构造几个几何对象 poly sg.Polygon([ sg.Point2(0, 0), sg.Point2(4, 0), sg.Point2(4, 4), sg.Point2(0, 4) ]) seg sg.Segment2(sg.Point2(0, 0), sg.Point2(4, 4)) circle sg.Circle(sg.Point2(2, 2), 1.5) # 绘制 draw(poly, facecolorlightblue, edgecolorblack) draw(seg, edgecolorred, linewidth2) draw(circle, edgecolorgreen, fillFalse)draw函数接受任意几何对象参数跟 matplotlib 的绘图函数一致。在 Jupyter 里每个 cell 调用一次draw最后加plt.show()就能看到叠加效果。这个可视化能力在调试布尔运算、凸包、三角剖分时非常有用能直观看到结果对不对。5. 避坑与排查那些文档里不会写的翻车现场5.1 多边形绕向不一致导致布尔运算返回空现象两个明显重叠的多边形做交集返回结果面积为 0 或直接抛异常。原因CGAL 的布尔运算要求所有输入多边形顶点绕向一致。如果一个是逆时针、一个是顺时针内核会认为它们在“相反方向”上定义区域导致结果异常。解决构造后统一绕向。用poly.orientation()检查如果是CLOCKWISE就用reversed反转顶点列表重新构造。批量处理时写个ensure_ccw函数每个多边形过一遍。5.2 浮点坐标传入后结果偏差现象用float计算的坐标传入Point2布尔运算结果跟预期差一点点或者本该相交的线段判为不相交。原因CGAL 的精确谓词只保证判断正确但坐标本身是双精度浮点。如果传入前已经因为浮点运算损失了精度谓词再精确也救不回来。解决尽量用整数或Fraction构造坐标把浮点运算推迟到最后一刻。如果必须用浮点在传入前做一次四舍五入到合理精度比如 1e-9避免极小的数值噪声触发退化情况。5.3 Jupyter 里 draw 不显示图形现象在 Jupyter Notebook 里调用draw后没有图形输出。原因draw内部用的是 matplotlib需要先设置内联后端或者手动调用plt.show()。解决在 notebook 开头加%matplotlib inline或者每次draw后加import matplotlib.pyplot as plt; plt.show()。如果用的是 JupyterLab可能需要装ipympl并启用%matplotlib widget。5.4 三角剖分插入重复点导致崩溃现象tri.insert(p)插入一个已经存在的点程序直接段错误或抛异常。原因CGAL 的 Delaunay 三角剖分不允许重复点插入相同坐标会触发未定义行为。解决插入前用set去重或者用tri.insert_if_not_present(p)如果封装版本支持。我一般会先把点集转成set再逐个插入避免这个问题。5.5 大点集凸包计算内存暴涨现象几万个点的凸包计算内存占用飙升甚至 OOM。原因convex_hull内部会复制一份点集做排序如果点集本身很大内存翻倍。解决分批处理或者先用简单过滤比如按 x 坐标排序后取极值点缩小点集。如果只是要凸包面积可以用min_rectangle近似内存占用更低。6. 进阶技巧用 scikit-geometry 做批量几何处理与验证当你把 scikit-geometry 用顺了之后下一步自然是把它嵌到批量处理流程里。我一般会写一个几何处理管道把读取、清洗、运算、验证、输出串起来。这里分享一个我常用的验证习惯每次布尔运算后强制检查结果的面积是否等于预期值在容差范围内不等就打印中间状态。import skgeom as sg def safe_boolean(op, poly_a, poly_b, expected_areaNone, tol1e-6): 带验证的布尔运算封装 op: BooleanOperation 枚举 poly_a, poly_b: 输入多边形 expected_area: 预期面积用于验证 tol: 面积容差 # 统一绕向 poly_a ensure_ccw(poly_a) poly_b ensure_ccw(poly_b) # 执行运算 result sg.boolean_operation(poly_a, poly_b, op) # 验证面积 if expected_area is not None: actual result.area() if abs(actual - expected_area) tol: print(f警告面积偏差 {abs(actual - expected_area):.6f} f预期 {expected_area}实际 {actual}) # 打印输入多边形的绕向和面积辅助排查 print(fpoly_a 绕向: {poly_a.orientation()}, 面积: {poly_a.area()}) print(fpoly_b 绕向: {poly_b.orientation()}, 面积: {poly_b.area()}) return result # 使用示例 poly_a sg.Polygon([sg.Point2(0,0), sg.Point2(4,0), sg.Point2(4,4), sg.Point2(0,4)]) poly_b sg.Polygon([sg.Point2(2,2), sg.Point2(6,2), sg.Point2(6,6), sg.Point2(2,6)]) result safe_boolean(sg.BooleanOperation.Intersection, poly_a, poly_b, expected_area4.0) print(交集面积:, result.area())这个封装看起来多此一举但在处理几十上百个多边形时能帮你快速定位是哪个输入出了问题。ensure_ccw是前面定义的绕向统一函数expected_area是你根据业务逻辑算出来的理论值。一旦偏差超过容差打印输入状态通常一眼就能看出是绕向问题还是坐标精度问题。另一个我常用的技巧是用sg.orientation做批量共线检测。在三角剖分前先扫一遍点集把共线的点标记出来避免生成退化三角形def remove_collinear(points, tol1e-9): 移除共线的中间点保留端点 if len(points) 3: return points result [] n len(points) for i in range(n): p0 points[i] p1 points[(i 1) % n] p2 points[(i 2) % n] # 如果三点共线跳过中间点 if sg.orientation(p0, p1, p2) ! sg.Orientation.COLLINEAR: result.append(p1) return result这个函数在预处理 GIS 边界数据时特别有用很多 shapefile 导出的多边形顶点里有大量共线点不清掉会拖慢后续所有运算。从那以后我每次做几何处理都强制走一遍「绕向检查 → 共线清理 → 运算 → 面积验证」这个流程翻车次数明显下降。希望帮到你。本文还有配套的精品资源点击获取