【VTK手册036】网格拓扑简化工具：vtkCleanPolyData 使用指南

在基于 C++ 和 VTK 的医学图像算法开发中，几何拓扑的严谨性至关重要。无论是经过布尔运算、等值面提取（Marching Cubes）还是复杂的网格剪裁，输出的 vtkPolyData 往往存在冗余点、孤立点或退化单元。

vtkCleanPolyData 是 VTK 核心库中用于维护网格拓扑清洁度的首选过滤器。本文将从基本原理、接口详解到源码逻辑，深度解析该类的用法。

1. 功能概述

vtkCleanPolyData 的核心目标是"精简"与"修复"。其主要执行三项任务：

合并重复点：在指定误差范围内，将空间位置极近的点合并为一点。
移除冗余点：删除未被任何单元（Cell）引用的孤立点。
消除退化单元：将不符合拓扑定义的单元进行降级或删除（如：两个点重合的三角形退化为线）。

2. 快速示例

以下是清理一个包含重复点和退化单元的 vtkPolyData 的典型代码片段：

cpp 复制代码

#include <vtkCleanPolyData.h>
#include <vtkSmartPointer.h>
#include <vtkPolyData.h>

// 假设 inputPolyData 是待处理的几何数据
auto cleaner = vtkSmartPointer<vtkCleanPolyData>::New();
cleaner->SetInputData(inputPolyData);

// 配置参数
cleaner->SetTolerance(0.005);             // 设置相对误差（包围盒对角线的0.5%）
cleaner->PointMergingOn();                // 开启点合并
cleaner->ConvertLinesToPointsOn();        // 允许退化线转为点
cleaner->ConvertPolysToLinesOn();         // 允许退化面转为线

cleaner->Update();

// 获取清理后的结果
vtkPolyData* cleanedData = cleaner->GetOutput();

3. 基本原理与计算公式

3.1 点合并逻辑

vtkCleanPolyData 通过空间定位器（Locator）搜索近邻点。判定两个点 P1,P2P_1, P_2P1,P2 是否合并的标准取决于距离 ddd 与容差 ϵ\epsilonϵ：

d(P1,P2)=(x1−x2)2+(y1−y2)2+(z1−z2)2d(P_1, P_2) = \sqrt{(x_1-x_2)^2 + (y_1-y_2)^2 + (z_1-z_2)^2}d(P1,P2)=(x1−x2)2+(y1−y2)2+(z1−z2)2

相对容差 (Tolerance)：

若 ToleranceIsAbsolute 为假，则实际合并阈值 TTT 取决于输入数据包围盒对角线长度 LLL：

T=Tolerance×LT = \text{Tolerance} \times LT=Tolerance×L
绝对容差 (AbsoluteTolerance)：

若 ToleranceIsAbsolute 为真，则直接使用 AbsoluteTolerance 作为阈值。

3.2 单元退化路径

该滤波器通过累计方式处理单元降级，逻辑如下：

Strip (3点) →ConvertStripsToPolys\xrightarrow{ConvertStripsToPolys}ConvertStripsToPolys Poly
Poly (2点) →ConvertPolysToLines\xrightarrow{ConvertPolysToLines}ConvertPolysToLines Line
Line (1点) →ConvertLinesToPoints\xrightarrow{ConvertLinesToPoints}ConvertLinesToPoints Vert

4. 关键接口详表

根据 vtkCleanPolyData.h 头文件，常用核心接口归纳如下：

接口函数	返回/参数类型	默认值	说明
`SetTolerance(double)`	`double [0, 1]`	`0.0`	设置相对容差（包围盒对角线的比例）
`SetAbsoluteTolerance(double)`	`double`	`1.0`	设置绝对距离阈值
`SetToleranceIsAbsolute(vtkTypeBool)`	`bool`	`false`	是否启用绝对容差模式
`SetPointMerging(vtkTypeBool)`	`bool`	`true`	是否执行点合并逻辑（关闭则仅删除孤立点）
`SetConvertLinesToPoints(vtkTypeBool)`	`bool`	`true`	是否将单点线转换为顶点
`SetConvertPolysToLines(vtkTypeBool)`	`bool`	`true`	是否将二点面转换为线
`SetConvertStripsToPolys(vtkTypeBool)`	`bool`	`true`	是否将三点条带转换为多边形
`SetLocator(vtkIncrementalPointLocator*)`	`pointer`	`vtkMergePoints`	指定空间定位器，手动优化搜索性能
`SetOutputPointsPrecision(int)`	`int`	`DEFAULT`	设置输出点坐标的精度（单精度/双精度）
`SetPieceInvariant(vtkTypeBool)`	`bool`	`true`	是否保证多块数据并行处理时的结果一致性

5. 源码逻辑与性能分析

5.1 定位器选择机制

在 RequestData 过程中，vtkCleanPolyData 会根据容差设定自动选择算法路径：

精确匹配 ：如果 Tolerance == 0.0，底层使用 vtkMergePoints，利用哈希映射实现 O(N)O(N)O(N) 的合并速度。
模糊匹配 ：如果 Tolerance > 0.0，则使用 vtkIncrementalPointLocator，进行邻域半径搜索，计算开销相对较高。

5.2 全局 ID 合并

源码中存在一个重要特性：如果输入数据包含 Global ID 数组，滤波器将优先基于 ID 进行合并。两个点只有在拥有相同 Global ID 时才会被合并，即使它们在空间上重合。

5.3 注意事项

拓扑变更 ：合并点可能导致流形结构变为非流形结构，建议在医学高精度建模中谨慎设置 Tolerance。
无单元点 ：如果输入的 PolyData 只有点云而没有单元，必须先通过 vtkVertexGlyphFilter 为其添加顶点单元，否则 vtkCleanPolyData 可能会将其作为冗余点删除。

6. 进阶建议

对于超大规模数据集（千万级三角面片），vtkCleanPolyData 的增量定位器可能会成为性能瓶颈。头文件中特别提到了 vtkStaticCleanPolyData ，它是该类的非增量、多线程实现版本。在不要求增量处理的场景下，切换到 vtkStaticCleanPolyData 通常能获得数倍的加速。