项目地址: https://github.com/AngusJohnson/Clipper2
官方文档: http://www.angusj.com/clipper2/Docs/Overview.htm
包管理器: NuGet
Clipper22.0.0 | vcpkgclipper2| npmclipper2-js1.2.4 | 源码 tagClipper2_2.0.1(2025-12-19,截至 2026-10)版本: 上游 tag
Clipper2_2.0.1;NuGet 稳定包仍为2.0.0,二者 API 相同,装包时以 NuGet 版本为准许可证: Boost Software License 1.0
概述
Clipper2 相对 Clipper1 的提升:
- 全新算法,速度更快、内存更省
- 支持浮点(
PathsD)与整数(Paths64)双模式 - 全新偏移引擎:更鲁棒的 mitre/square/round 端帽与连接
- 简洁 API:
Union/Intersect/Difference/Xor顶级函数 - 多语言:C++、C#、Delphi、JS(Clipper2.js 移植)
安装
C#
dotnet add package Clipper2 # 2.0.0,提供 Clipper2Lib 命名空间
C++
# vcpkg
vcpkg install clipper2
# 或直接 add subdirectory CPP/Clipper2Lib 到 CMake
JavaScript
npm install clipper2-js # 1.2.4,第三方原生 TS/JS 移植;另有 WASM 移植 js-angusj-clipper 1.3.1
验证
# C#:包能还原且命名空间可解析,跑通一个 union 即可视为就绪
dotnet list package | grep Clipper2
# Node:确认版本
node -e "console.log(require('clipper2-js/package.json').version)"
核心 API
核心数据结构(C#)
using Clipper2Lib;
PointD pd = new(10.5, 20.7); // 浮点点
PathD path = new() { new(0,0), new(10,0), new(10,10), new(0,10) };
PathsD subj = new() { path }; // 多个 path
PathsD clip = new() { /* ... */ };
整数版本:Point64 / Path64 / Paths64,避免浮点误差。
布尔运算
using Clipper2Lib;
PathsD a = new() { Clipper.MakePath(new[] { 0d,0, 100,0, 100,100, 0,100 }) };
PathsD b = new() { Clipper.MakePath(new[] { 50d,50, 150,50, 150,150, 50,150 }) };
PathsD u = Clipper.Union(a, b, FillRule.NonZero);
PathsD i = Clipper.Intersect(a, b, FillRule.NonZero);
PathsD d = Clipper.Difference(a, b, FillRule.NonZero);
PathsD x = Clipper.Xor(a, b, FillRule.NonZero);
FillRule:
EvenOdd(奇偶)NonZero(非零)Positive(正向缠绕)Negative(负向缠绕)
多边形偏移(Inflate / 缩进)
PathsD outline = new() {
Clipper.MakePath(new[] { 0d,0, 100,0, 100,100, 0,100 })
};
// 向外偏移 10 单位
PathsD outer = Clipper.InflatePaths(outline, 10,
JoinType.Round, // Square / Miter / Round
EndType.Polygon); // Polygon / Joined / Butt / Square / Round
// 向内偏移:负数
PathsD inner = Clipper.InflatePaths(outline, -10,
JoinType.Miter, EndType.Polygon);
EndType:
Polygon闭合多边形Joined开放多线段,端点首尾相连Butt/Square/Round开放线段端帽
高级用法(ClipperD/Clipper64 类)
需要更精细控制(PolyTree、ZFill 回调等):
ClipperD clipper = new(2); // 参数是浮点舍入精度(默认 2 位小数)
clipper.AddSubject(subj); // 重载接收 PathD 或 PathsD
clipper.AddClip(clip);
PolyTreeD tree = new();
clipper.Execute(ClipType.Union, FillRule.NonZero, tree);
// 遍历层级:PolyTreeD/D 节点可 foreach,节点上是 Polygon 与 Count
foreach (PolyPathD node in tree) {
bool hole = node.IsHole; // 该节点是不是孔
PathD? poly = node.Polygon; // 根节点 Polygon 为 null
}
// 只要扁平结果:PolyTreeToPathsD 把树压平
PathsD flat = Clipper.PolyTreeToPathsD(tree);
PolyTreeD 保留外环/内孔的层级关系,对于带孔多边形非常重要;注意没有 GetAllPaths 这种取法,压平用 Clipper.PolyTreeToPathsD(tree),保留层级就自己遍历 PolyPathD 的 Count / 索引器 / IsHole。
实用工具
double area = Clipper.Area(path); // 有符号面积(PathD 或 PathsD 都有重载)
RectD bbox = Clipper.GetBounds(paths); // 包围盒
PathsD simp = Clipper.SimplifyPaths(paths, 0.5); // 简化(容差)
PathsD ramer = Clipper.RamerDouglasPeucker(paths, 0.5); // RDP 简化
PathD trim = Clipper.TrimCollinear(path, 2); // 去共线点(PathD 版要传精度)
bool inside = Clipper.PointInPolygon(new PointD(1, 1), path)
== PointInPolygonResult.IsInside; // 点在多边形内判定
PathD rev = Clipper.ReversePath(path); // 反向缠绕
bool ccw = Clipper.IsPositive(path); // 缠绕方向判定
// 闵可夫斯基和/差(轮廓膨胀工具)
PathD mink = Clipper.MinkowskiSum(pattern, path, false);
注意 C# 绑定里没有 Centroid(形心)这类几何量函数,需要形心就自己按 Area 加权算或用包围盒/中点(Clipper.MidPoint)代替。
C++ 用法
#include "clipper2/clipper.h"
using namespace Clipper2Lib;
PathsD subj{ MakePathD({0,0, 100,0, 100,100, 0,100}) };
PathsD clip{ MakePathD({50,50, 150,50, 150,150, 50,150}) };
auto u = Union(subj, clip, FillRule::NonZero);
auto inflated = InflatePaths(u, 10.0, JoinType::Round, EndType::Polygon);
典型工作流
输入:PathD/Path64 轮廓集合;输出:布尔/偏移结果的 PathsD/Paths64,再转下游格式。
工作流一:2D 轮廓布尔运算(C#)
- 通过
Clipper.MakePath或手工构造PathD/Path64列表 - 选择 FillRule(一般用
NonZero) - 直接调用静态函数
Clipper.Union(a, b, FillRule.NonZero) - 如需 PolyTree(孔洞层级),使用
ClipperD类 +PolyTreeD - 对结果进行
SimplifyPaths或TrimCollinear清理 - 导出结果,转换为下游格式(如转回 DXF polyline)
工作流二:多边形膨胀与缩进(CAM 刀路补偿)
- 从 CAD 文件读取零件轮廓多边形
- 使用
Clipper.InflatePaths(paths, offset, JoinType.Round, EndType.Polygon)生成刀路偏置 - 正值外扩(粗加工),负值内缩(精加工)
- 对偏移结果做
SimplifyPaths,去除多余顶点 - 输出为 G-code 或 CAM 系统格式
性能要点
- 优先 Path64 + 适当 scale:浮点版内部仍用整数实现,避免精度问题
- SimplifyPaths 在大量数据布尔前预处理,减少顶点
- 避免共线点:
TrimCollinear - 大对象用 PolyTree:避免重新计算外/内环关系
- Inflate 注意 miter limit:尖角处可能产生超大顶点
- 多线程:Clipper2 单实例非线程安全,多线程需独立实例
与其它库对比
| 库 | 语言 | 主要特性 |
|---|---|---|
| Clipper2 | C++/C#/Delphi/JS | 高性能布尔+偏移,AGG 兼容 |
| CGAL Boolean | C++ | 精确算术,复杂但慢 |
| JTS / NTS | Java/.NET | 完整空间分析,速度中等 |
| Boost.Polygon | C++ | 仅整数,高性能 |
常见问题
| 问题 | 解决 |
|---|---|
| 输出空集 | 检查 FillRule、方向(逆时针 vs 顺时针)、闭合性 |
| 偏移变形 | 调整 JoinType 与 MiterLimit |
| 浮点精度异常 | 改用 Path64 或 ClipperD(precision) |
| 与 Clipper1 不兼容 | API 已变化,参考迁移指南 |
找不到 Centroid / GetAllPaths |
C# 绑定没有这两个函数:形心自行按 Area 加权计算,PolyTree 压平用 Clipper.PolyTreeToPathsD(tree) |
| 想用 Python 调 Clipper2 | 官方没有发布 PyPI 包(pip install clipper2 不可用);Python 侧要么装 Clipper1 系的 pyclipper,要么用 shapely(底层 GEOS)替代,或自己编译 C++ 版写绑定 |
C++ 编译报 clipper2/clipper.h: No such file |
include 目录要指向 CPP/Clipper2Lib/include;CMake 里 add_subdirectory(CPP/Clipper2Lib) 后链接 Clipper2Lib 目标,不要只拷 clipper.h 漏掉 clipper.core.h/clipper.engine.h |
AI 使用建议
- 推荐工作流模式:新项目优先使用 Clipper2 的静态顶层函数(
Union/Intersect/Difference/Xor/InflatePaths),比 Clipper1 的类实例方式更简洁。浮点模式直接用PathsD,整数模式用Paths64(指定 scale)。 - 关键注意事项:①
FillRule默认用NonZero;②InflatePaths的JoinType和MiterLimit影响偏移质量——圆形连接(Round)最稳健;③ 浮点模式下ClipperD(precision)的 precision 参数控制内部整数转换精度;④PolyTree保留孔洞层级。 - 常用代码模式:
Clipper.Union(pathsA, pathsB, FillRule.NonZero)→Clipper.InflatePaths(result, offset, JoinType.Round, EndType.Polygon)→Clipper.SimplifyPaths(result, tolerance)。
相关技能
- clipper1 — 一代 Clipper 库(遗留代码维护参考):../clipper1/SKILL.md
- qcad — 2D CAD 软件,DXF 多边形编辑:../qcad/SKILL.md
- librecad — 开源 2D CAD,配合 Clipper 做几何处理:../librecad/SKILL.md