第一章 Clipper2概述与安装（C#版）

1.1 引言

在计算机图形学和地理信息系统（GIS）领域，多边形的布尔运算和偏移操作是极其重要的基础功能。无论是CAD软件、游戏开发、地图制作还是激光切割机的路径规划，都需要对多边形进行精确的裁剪、合并、求交等操作。Clipper2正是为解决这类问题而诞生的一个强大的开源几何运算库。

Clipper2是由澳大利亚程序员Angus Johnson开发的一个高性能多边形裁剪和偏移库。它是原始Clipper库的全新重写版本，相比于10年前发布的Clipper1，Clipper2在算法效率、代码质量、功能完整性等方面都有了质的飞跃。该库原生支持C#语言，并可通过NuGet包管理器轻松安装，使.NET开发者能够快速集成这个强大的几何运算工具。

本教程专注于Clipper2的C#版本，帮助.NET开发者全面掌握这个库的使用方法。

1.2 什么是Clipper2

1.2.1 核心功能概述

Clipper2是一个专注于二维多边形处理的几何运算库，其核心功能包括：

多边形布尔运算（Boolean Operations）

布尔运算是Clipper2最核心的功能之一。它支持对两个或多个多边形执行以下操作：

交集（Intersection）：计算两个多边形重叠的区域
并集（Union）：合并两个多边形，得到它们的完整覆盖区域
差集（Difference）：从一个多边形中减去另一个多边形
异或（XOR）：得到两个多边形不重叠的区域

这些操作不仅适用于简单的凸多边形，更重要的是能够正确处理复杂的凹多边形、自交多边形以及带有孔洞的多边形。

多边形偏移（Polygon Offsetting）

偏移操作也称为膨胀（Inflate）或收缩（Deflate），是指将多边形的边界向内或向外移动指定的距离。这在很多实际应用中都非常有用：

CNC加工中的刀具路径补偿
3D打印中的轮廓生成
地图制作中的缓冲区分析
建筑设计中的边界退让

Clipper2支持多种连接类型（Join Type）和端点类型（End Type），可以生成圆角、斜角或方角的偏移效果。

矩形裁剪（Rectangle Clipping）

这是Clipper2特有的一个优化功能。当裁剪区域是一个轴对齐的矩形时，可以使用专门优化的算法来获得更高的性能。这在地图瓦片生成、视窗裁剪等场景下非常实用。

闵可夫斯基运算（Minkowski Operations）

包括闵可夫斯基和（Minkowski Sum）与闵可夫斯基差（Minkowski Difference）。这些操作在机器人路径规划、碰撞检测等领域有着重要的应用。

1.2.2 Clipper2的设计特点

Clipper2在设计上具有以下显著特点：

高精度整数运算

与许多使用浮点数的几何库不同，Clipper2内部使用64位整数进行所有的几何计算。这种设计虽然需要开发者在输入时进行坐标缩放，但换来的是完全精确的计算结果，避免了浮点数运算中常见的舍入误差和数值不稳定问题。

对于需要使用浮点数的场景，Clipper2也提供了基于double类型的API（PathsD类型），库会自动处理浮点数到整数的转换。

鲁棒性

Clipper2能够正确处理各种边缘情况，包括：

自交多边形
重叠边
共线顶点
极端坐标值
孔洞嵌套

这种鲁棒性使得Clipper2在生产环境中非常可靠，很少出现崩溃或产生无效输出的情况。

高性能

通过精心优化的算法和数据结构，Clipper2在处理复杂多边形时表现出色。C#版本的性能足以满足大多数应用场景的需求，在处理包含数十万顶点的多边形时仍然能够在可接受的时间内完成计算。

简洁的API

Clipper2提供了两层API：

简化的静态函数接口，适合快速使用
完整的类接口（Clipper64、ClipperD），提供更多的控制选项

这种设计既满足了简单用例的便捷性需求，也为高级用户提供了足够的灵活性。

1.2.3 Clipper2与Clipper1的主要区别

作为Clipper1的继任者，Clipper2进行了大量的改进：

算法改进

使用了改进的Vatti算法变体，处理退化情况更加鲁棒
新的多边形偏移算法，产生更高质量的输出
新增矩形裁剪的专用快速算法

API变化

从IntPoint改为Point64/PointD
从Paths改为Paths64/PathsD
更清晰的命名约定
支持PolyTree和Paths两种输出格式

功能增强

新增Z轴值的可选支持
改进的闵可夫斯基运算
更好的SVG输出支持

性能提升

整体性能提升约30%
更低的内存占用
更好的多线程友好性

1.3 Clipper2的应用领域

Clipper2在众多领域都有广泛的应用：

1.3.1 CAD/CAM

在计算机辅助设计和制造领域，Clipper2被广泛用于：

刀具路径规划：CNC铣床、激光切割机、等离子切割机等设备需要根据工件的轮廓计算刀具的运动路径。通过Clipper2的偏移功能，可以轻松实现刀具半径补偿。

2D嵌套优化：在板材切割中，需要将多个零件尽可能紧凑地排列在原材料上。Clipper2可用于检测零件之间的重叠，辅助实现嵌套算法。

布尔建模：在2D CAD中，经常需要对图形进行布尔运算，如合并多个区域、切割图形等。

1.3.2 GIS地理信息系统

地理信息系统是Clipper2的重要应用领域：

缓冲区分析：围绕地理要素（如道路、河流、建筑物）创建指定距离的缓冲区。

叠置分析：计算两个图层的交集、并集、差集，例如计算洪水淹没区域与居民区的重叠部分。

地图瓦片生成：使用矩形裁剪功能高效生成地图瓦片数据。

区域合并：将相邻的行政区划或地块合并为更大的区域。

1.3.3 游戏开发

在游戏开发中，Clipper2可用于：

碰撞检测：使用闵可夫斯基运算计算两个多边形是否相交。

可见性计算：计算视野区域与障碍物的交集。

地图编辑器：实现地形的绘制和擦除功能。

路径寻找：生成导航网格的预处理步骤。

1.3.4 3D打印和激光切割

轮廓生成：将3D模型切片后，生成每一层的打印轮廓。

路径优化：对打印路径进行偏移，生成填充图案。

切割优化：计算激光切割的最优路径。

1.3.5 电子设计自动化（EDA）

PCB设计：计算铜皮区域、敷铜填充等。

DRC检查：设计规则检查中的间距验证。

布局优化：计算元器件的占用区域。

1.4 安装与环境配置

1.4.1 通过NuGet安装（推荐）

最简单的方式是通过NuGet包管理器安装Clipper2：

使用.NET CLI

dotnet add package Clipper2

使用Visual Studio

右键点击项目 → 管理NuGet程序包
搜索”Clipper2”
点击安装

使用程序包管理器控制台

Install-Package Clipper2

1.4.2 手动添加源代码

如果需要自定义修改或者无法使用NuGet，可以从GitHub下载源代码后手动添加。

从GitHub仓库（https://github.com/AngusJohnson/Clipper2）下载源代码后，将CSharp/Clipper2Lib目录下的所有.cs文件添加到项目中。

需要的文件包括：

Clipper.Core.cs - 核心数据类型定义
Clipper.Engine.cs - 裁剪引擎实现
Clipper.cs - 主要的公共API
Clipper.Offset.cs - 多边形偏移功能
Clipper.RectClip.cs - 矩形裁剪功能
Clipper.Minkowski.cs - 闵可夫斯基运算

// 添加命名空间引用
using Clipper2Lib;

1.4.3 支持的.NET版本

Clipper2的C#版本使用.NET Standard 2.0，这意味着它可以在以下平台上使用：

.NET Core 2.0+
.NET 5/6/7/8+
.NET Framework 4.6.1+
Mono 5.4+
Xamarin
Unity（2018.1+）

1.4.4 项目配置示例

创建一个新的控制台应用程序：

dotnet new console -n Clipper2Demo
cd Clipper2Demo
dotnet add package Clipper2

在项目文件（.csproj）中，您会看到类似这样的引用：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Clipper2" Version="1.x.x" />
  </ItemGroup>
</Project>

1.5 第一个Clipper2程序

让我们通过一个完整的C#示例来感受Clipper2的使用方式。

1.5.1 完整示例程序

using System;
using Clipper2Lib;

namespace Clipper2Demo
{
    class Program
    {
        static void Main(string[] args)
        {
            // 定义主体多边形（一个正方形）
            Paths64 subject = new Paths64();
            subject.Add(Clipper.MakePath(new long[] { 0, 0, 100, 0, 100, 100, 0, 100 }));
            
            // 定义裁剪多边形（一个与主体部分重叠的正方形）
            Paths64 clip = new Paths64();
            clip.Add(Clipper.MakePath(new long[] { 50, 50, 150, 50, 150, 150, 50, 150 }));
            
            // 执行交集运算
            Paths64 intersection = Clipper.Intersect(subject, clip, FillRule.NonZero);
            Console.WriteLine($"交集结果包含 {intersection.Count} 个多边形");
            
            foreach (Path64 path in intersection)
            {
                Console.Write("多边形顶点：");
                foreach (Point64 pt in path)
                {
                    Console.Write($"({pt.X},{pt.Y}) ");
                }
                Console.WriteLine();
            }
            
            // 执行并集运算
            Paths64 unionResult = Clipper.Union(subject, clip, FillRule.NonZero);
            Console.WriteLine($"并集结果包含 {unionResult.Count} 个多边形");
            
            // 执行差集运算
            Paths64 difference = Clipper.Difference(subject, clip, FillRule.NonZero);
            Console.WriteLine($"差集结果包含 {difference.Count} 个多边形");
            
            // 执行异或运算
            Paths64 xorResult = Clipper.Xor(subject, clip, FillRule.NonZero);
            Console.WriteLine($"异或结果包含 {xorResult.Count} 个多边形");
            
            Console.WriteLine("\n按任意键退出...");
            Console.ReadKey();
        }
    }
}

1.5.2 代码解析

引入命名空间

using Clipper2Lib;

这一行引入了Clipper2库的命名空间，使我们可以直接使用库中的类型和方法。

创建多边形

Paths64 subject = new Paths64();
subject.Add(Clipper.MakePath(new long[] { 0, 0, 100, 0, 100, 100, 0, 100 }));

Paths64是一个路径集合，可以包含多个多边形
Clipper.MakePath()是一个辅助方法，将坐标数组转换为Path64对象
坐标以x,y交替的方式提供：{x1, y1, x2, y2, x3, y3, x4, y4}

执行布尔运算

Paths64 intersection = Clipper.Intersect(subject, clip, FillRule.NonZero);

Clipper.Intersect()是一个静态方法，执行交集运算
第三个参数FillRule.NonZero指定填充规则
返回值是一个Paths64对象，包含运算结果

1.5.3 运行结果

对于上述两个正方形：

主体正方形：(0,0) - (100,100)
裁剪正方形：(50,50) - (150,150)

运算结果：

交集：得到一个50x50的正方形，顶点为(50,50)、(100,50)、(100,100)、(50,100)
并集：得到一个L形多边形，覆盖两个正方形的完整区域
差集：得到主体正方形减去重叠部分后的L形区域
异或：得到两个不重叠的L形区域

1.5.4 使用浮点数坐标

如果您的数据使用浮点数坐标，可以使用PathsD类型：

using System;
using Clipper2Lib;

class FloatExample
{
    static void Main()
    {
        // 使用浮点数坐标
        PathsD subject = new PathsD();
        subject.Add(Clipper.MakePath(new double[] { 0.0, 0.0, 10.5, 0.0, 10.5, 10.5, 0.0, 10.5 }));
        
        PathsD clip = new PathsD();
        clip.Add(Clipper.MakePath(new double[] { 5.25, 5.25, 15.75, 5.25, 15.75, 15.75, 5.25, 15.75 }));
        
        // 第四个参数指定精度（小数位数）
        PathsD result = Clipper.Intersect(subject, clip, FillRule.NonZero, 2);
        
        Console.WriteLine($"结果包含 {result.Count} 个多边形");
    }
}

1.6 坐标系统与精度

1.6.1 整数坐标系统

Clipper2使用64位有符号整数作为内部坐标类型。有效坐标范围为：

最小值：-4,611,686,018,427,387,903 (-2^62 + 1)
最大值：+4,611,686,018,427,387,903 (+2^62 - 1)

这个范围足以处理大多数实际应用场景。

1.6.2 浮点数到整数的转换

如果你的应用使用浮点数坐标，Clipper2提供了便捷的转换方式：

using Clipper2Lib;

class CoordinateConversion
{
    static void Main()
    {
        // 假设原始坐标范围是 0.0 - 10.0
        // 选择一个合适的缩放因子
        double scale = 1000.0;  // 精度为0.001

        // 方式一：直接使用PathsD类型的API（库自动处理转换）
        PathsD originalPaths = new PathsD();
        originalPaths.Add(Clipper.MakePath(new double[] { 0.0, 0.0, 10.0, 0.0, 10.0, 10.0, 0.0, 10.0 }));
        
        PathsD clipPaths = new PathsD();
        clipPaths.Add(Clipper.MakePath(new double[] { 5.0, 5.0, 15.0, 5.0, 15.0, 15.0, 5.0, 15.0 }));
        
        // 第四个参数2表示保留2位小数精度
        PathsD result = Clipper.Intersect(originalPaths, clipPaths, FillRule.NonZero, 2);
        
        // 方式二：手动缩放
        Paths64 scaledPaths = Clipper.ScalePaths64(originalPaths, scale);
        // 处理后再缩放回来
        PathsD resultD = Clipper.ScalePathsD(scaledPaths, 1.0 / scale);
    }
}

### 1.6.3 精度选择建议

选择合适的精度取决于应用需求：

| 应用场景 | 建议精度 | 缩放因子 |
|----------|----------|----------|
| 屏幕绘图（像素） | 1像素 | 1 |
| CAD应用（毫米） | 0.001mm | 1000 |
| GIS应用（米） | 0.0001m | 10000 |
| 高精度加工 | 0.0001mm | 10000 |

## 1.7 填充规则（Fill Rules）

填充规则决定了如何判定一个点是在多边形内部还是外部。这对于处理复杂的自交多边形和带孔洞的多边形至关重要。

### 1.7.1 EvenOdd规则

偶奇规则是最简单的填充规则：从该点向任意方向画一条射线，计算射线与多边形边界的交点数量。如果交点数为奇数，则点在内部；如果为偶数，则点在外部。

```csharp
Paths64 result = Clipper.Union(paths, FillRule.EvenOdd);

适用场景：

SVG和PostScript中的默认规则
简单的图形绘制
不关心顶点顺序的场景

1.7.2 NonZero规则

非零规则考虑边的方向：从该点向任意方向画一条射线，当射线从左向右穿过边时计数器加1，从右向左穿过时减1。如果最终计数器不为0，则点在内部。

Paths64 result = Clipper.Union(paths, FillRule.NonZero);

适用场景：

大多数CAD应用
需要区分内外边界的场景
GIS中的面状要素

1.7.3 Positive规则

正数规则：只有当计数器为正数时，点才被认为在内部。这意味着只有逆时针方向的路径会产生填充区域。

Paths64 result = Clipper.Union(paths, FillRule.Positive);

1.7.4 Negative规则

负数规则：只有当计数器为负数时，点才被认为在内部。这意味着只有顺时针方向的路径会产生填充区域。

Paths64 result = Clipper.Union(paths, FillRule.Negative);

1.7.5 如何选择填充规则

using Clipper2Lib;

class FillRuleExample
{
    static void Main()
    {
        // 示例：一个带孔洞的多边形
        Paths64 paths = new Paths64();
        
        // 外边界（逆时针）
        paths.Add(Clipper.MakePath(new long[] { 0, 0, 100, 0, 100, 100, 0, 100 }));
        
        // 孔洞（顺时针）
        paths.Add(Clipper.MakePath(new long[] { 25, 25, 25, 75, 75, 75, 75, 25 }));

        // 使用NonZero规则，正确识别孔洞
        Paths64 result = Clipper.Union(paths, FillRule.NonZero);

        // 使用EvenOdd规则，同样可以正确识别（不需要考虑顶点顺序）
        Paths64 result2 = Clipper.Union(paths, FillRule.EvenOdd);
    }
}

1.8 许可证

Clipper2使用Boost Software License 1.0许可证，这是一个非常宽松的开源许可证：

✅ 可以在商业项目中免费使用
✅ 可以修改源代码
✅ 可以重新分发
✅ 不需要公开你的源代码
✅ 不需要在产品中声明使用了Clipper2

1.9 获取帮助与资源

1.9.1 官方资源

GitHub仓库：https://github.com/AngusJohnson/Clipper2
官方文档：https://www.angusj.com/clipper2/Docs/Overview.htm
问题反馈：https://github.com/AngusJohnson/Clipper2/issues

1.9.2 社区资源

Stack Overflow：使用clipper或clipper2标签
各语言社区的讨论区

1.9.3 常见问题

Q: Clipper2支持曲线吗？

A: Clipper2只处理直线段组成的多边形。如果需要处理曲线（如圆弧、贝塞尔曲线），需要先将曲线离散化为折线。

Q: 为什么要使用整数坐标？

A: 整数运算可以确保计算的精确性和可重复性，避免浮点数舍入误差导致的问题。

Q: Clipper2可以处理3D多边形吗？

A: Clipper2是一个2D库，但支持可选的Z轴值传递功能（USINGZ）。Z值会在运算过程中保留或插值，但不参与布尔运算的计算。

Q: 如何处理非常大或非常小的坐标？

A: 建议将坐标缩放到合适的范围。过大的坐标可能导致溢出，过小的坐标会损失精度。

1.10 本章小结

本章我们学习了：

Clipper2的核心功能：布尔运算、多边形偏移、矩形裁剪、闵可夫斯基运算
设计特点：高精度整数运算、鲁棒性、高性能、简洁API
与Clipper1的区别：算法改进、API变化、功能增强、性能提升
应用领域：CAD/CAM、GIS、游戏开发、3D打印、EDA
C#安装方法：NuGet包管理器安装、手动添加源代码
基本使用：第一个Clipper2 C#程序
坐标系统：整数坐标、精度选择、浮点转换
填充规则：EvenOdd、NonZero、Positive、Negative

在下一章中，我们将深入学习Clipper2的核心数据结构，包括Point、Path、Paths、PolyTree等，为后续的高级操作打下坚实的基础。