PTD 是一个面向研究与工程复用的 C++17 点云地面滤波项目,目标是把经典 Progressive TIN Densification 做成可运行、可测试、可扩展的工程框架,而不是一次性的脚本复现。
当前仓库已经具备单块串行基线:支持 TXT 输入输出、经典 PTD 主流程、双阶段去噪、自适应阈值迭代、镜像点二次判定、可选 CGAL TIN 后端,以及 Python 批处理与评估工具。
本项目所说的“经典 PTD”主要对应 Peter Axelsson 在 2000 年发表的工作:DEM Generation from Laser Scanner Data Using Adaptive TIN Models。该文通常被视为 PTD 的代表性原始文献,可参考 ISPRS proceedings 页面 和 原文 PDF。
PTD 的核心思想是:先用一小批可靠地面种子点建立一个稀疏 TIN,再用这个 TIN 逐轮吸收满足几何约束的候选点,直到地表模型收敛。它不是一次性全局分类,而是“保守建模 + 逐步加密”。
经典流程可以概括为:
- 在 XY 平面上按网格选取局部最低点,作为初始地面种子。
- 用种子点构建初始 TIN,作为当前地表参考。
- 对候选点定位其参考三角形,计算局部几何量。
- 若候选点满足阈值约束,则将其接纳为地面点,并插入 TIN。
- 重复迭代,直到候选集为空,或最新一轮没有新增地面点。
当前实现里,主判据主要依赖 3 个几何量:
distanceToReference:候选点到参考三角面的绝对距离。angleToReferenceDegrees:候选点到参考三角形三个节点形成的最大节点角。slopeDegrees:参考三角面的坡度,主要用于断裂地形的镜像点触发。
本仓库在经典 PTD 之上已经落地了几项工程化增强,但仍保持“引擎只编排、策略可替换”的边界:
ClassicSeedSelector:按网格最低点选种子;若种子无法形成有效初始三角形,会按全局低点继续补点。- 双阶段去噪:
GlobalBeforeSeed:选种子前对全量点去噪;SeedAfterSelection:选出种子后再对种子子集去噪。
- 阈值模式:
fixed:直接使用配置中的距离阈值和角度阈值;adaptive:初始化轮基于“原始点云 + seed TIN”,后续轮基于“accepted geometry records”估计阈值。
- 镜像点二次判定:当主判据未接纳、距离超阈值且坡度较大时,触发镜像路径,缓解陡坎和断裂地形误判。
- TIN 抽象解耦:上层依赖
ITIN,构建时若找到 CGAL 则使用CgalTinAdapter,否则回退到FakeTIN。
当前版本的定位很明确:它是单块串行、可测试、可扩展的 PTD 工程基线,还不是完整的块处理或并行框架。
- CMake 3.20+
- 支持 C++17 的编译器
- Python 3
- 可选:CGAL(启用真实 TIN 后端时需要)
cmake -S . -B build
cmake --build build若不想启用 CGAL:
cmake -S . -B build -DPTD_ENABLE_CGAL_BACKEND=OFF
cmake --build build建议构建后先验证:
ctest --test-dir build --output-on-failure
./build/apps/ptd_cli/ptd_cli --version
./build/apps/ptd_cli/ptd_cli --help
./.venv/bin/python -m unittest discover -s tools/tests -v当前 CLI 使用最简单的 TXT 协议:
- 输入:每行
X Y Z label - 输出:每行
X Y Z label
约定:
- 输入文件第 4 列必须存在,但当前只使用前三列坐标;
- 输出中
0 = ground,1 = non-ground; Unknown标签写出时也会归并为1。
最小示例:
./build/apps/ptd_cli/ptd_cli \
--input /path/to/samp11.txt \
--output /path/to/samp11_pred.txt \
--log-level info固定阈值示例:
./build/apps/ptd_cli/ptd_cli \
--input /path/to/samp11.txt \
--output /path/to/samp11_pred.txt \
--log-level info \
--seed-cell-size 10.0 \
--threshold-mode fixed \
--distance-threshold 0.5 \
--angle-threshold 70.0 \
--slope-threshold 30.0 \
--global-denoise on \
--seed-denoise off \
--tin-update on自适应阈值示例:
./build/apps/ptd_cli/ptd_cli \
--input /path/to/samp11.txt \
--output /path/to/samp11_pred.txt \
--log-level info \
--threshold-mode adaptive \
--global-denoise on \
--seed-denoise off \
--tin-update on--seed-cell-size <float>:种子网格边长;未显式提供时 CLI 默认补成10.0。--threshold-mode adaptive|fixed:阈值模式切换。--distance-threshold <float>:固定距离阈值,仅fixed模式生效。--angle-threshold <float>:固定角度阈值,仅fixed模式生效。--slope-threshold <float>:镜像点触发坡度阈值;<= 0等价于关闭镜像触发。--global-denoise <bool>:是否启用种子前全量去噪,默认on。--seed-denoise <bool>:是否启用种子后二次去噪,默认off。--tin-update <bool>:是否执行增量 TIN 更新;关闭时仅做单轮迭代。
说明:adaptive 模式下,CLI 会忽略手工输入的 distance 和 angle,统一走内部阈值估计链路。
info 级别下,通常重点关注这些日志:
- 预处理:
Global denoise: noise_count=<N>Seed denoise: noise_count=<N>Seeds for initial TIN: count=<N>
- 迭代:
Iteration N thresholds: distance=..., angle=...Iteration N: candidates=..., accept=..., reject=..., defer=..., mirror_triggered=..., mirror_accepted=..., mirror_failed=..., remaining=...
- 汇总:
success: true/falseground count: ...non-ground count: ...status: ...
仓库内置两类实验工具:
-
tools/evaluate.py- 比较参考真值和预测结果;
- 输出混淆矩阵、常见指标、JSON 报告和点级误差码文件。
-
tools/run_isprs_batch.py- 扫描
data_dir下的samp*.txt; - 调用
ptd_cli逐样本运行; - 立即评估并汇总成
total_eval_<run_index>.json。
- 扫描
推荐直接在 Python 中调用:
from tools.run_isprs_batch import run_isprs_batch
run_isprs_batch(
data_dir="/path/to/ISPRS",
reports_dir="/path/to/reports",
build_dir="build",
run_index="00",
default_params={
"seed_cell_size": 10.0,
"threshold_mode": "fixed",
"distance_threshold": 0.5,
"angle_threshold": 70.0,
"tin_update": "on",
},
)批处理脚本当前支持透传这些参数键:
log_levelseed_cell_sizeslope_thresholddistance_thresholdangle_thresholdthreshold_modetin_update
./build/benchmarks/ptd_denoiser_benchmark
./.venv/bin/python -m unittest discover -s tools/tests -vPTDEngine只做流程编排,不内嵌具体策略规则。- 种子选择、阈值获取、候选管理、插入判定都通过接口注入。
- 上层不直接耦合具体三角化库,只依赖
ITIN。 PointCloud保持 SoA 布局;PointView负责只读子集绑定。- 当前虽然只跑单块串行流程,但接口边界要为 block / parallel 预留空间。
-
apps/ptd_cli- 命令行入口;
- 负责解析参数、装配默认策略、选择 TIN 后端并发起一次完整运行。
-
src/corePointCloud:统一保存坐标、标签、状态;PointView:只读子集视图,不复制底层点数据。
-
src/geometry- 负责纯几何计算;
- 包括平面构造、点到平面距离、向量夹角、节点最大夹角、坡度等。
-
src/preprocessing- 负责去噪能力;
- 当前核心是
IDenoiser、CombinedDenoiser、DenoiseContext、DenoiseResult。
-
src/spatial- 定义 TIN 抽象层;
ITIN提供buildInitialTIN、locateSurface、insertVertex;- 当前实现有
FakeTIN和CgalTinAdapter。
-
src/strategyISeedSelector:只负责选种子;IThresholdPolicy:只负责准备和返回阈值;ICandidateManager:只负责候选集合生命周期;IInsertionPolicy:只负责根据几何量和阈值给出Accept / Reject / Defer;context.hpp统一定义执行上下文、迭代上下文、局部几何、阈值集合和 accepted geometry records。
-
src/enginePTDEngine是真正的流程编排层;- 当前串起:全量去噪、种子选择、种子去噪、初始 TIN、候选初始化、逐轮阈值准备、主判据、镜像判据、TIN 更新、结果统计。
PTDResult汇总成功状态、迭代轮次、分类计数和阶段耗时。
-
src/ioTxtPointCloudReader:读取X Y Z label;TxtResultWriter:写出X Y Z label,并统一保证二分类协议。
-
src/utilConfig、Logger、Timer、build_info等基础设施。
-
tests- 按模块镜像组织;
- 覆盖核心数据结构、去噪、TIN、策略、引擎、CLI 和 Python 工具链。
-
benchmarks- 当前提供
ptd_denoiser_benchmark。
- 当前提供
-
toolsevaluate.py、run_isprs_batch.py、eval_aggregation.py组成实验辅助层。
- CLI 构造
Config。 TxtPointCloudReader把 TXT 载入PointCloud。- 引擎基于全量索引构造
PointView。 - 可选全量去噪,噪点直接落为
NonGround。 ISeedSelector选出种子。- 可选种子去噪,噪声种子从初始 TIN 输入中剔除。
ITIN构建初始 TIN。ICandidateManager初始化候选快照。- 每轮由引擎准备阈值摘要,
IThresholdPolicy生成本轮阈值,IInsertionPolicy给出主判据,必要时进入镜像点路径。 - 接纳点更新标签、状态和 TIN,并写入
acceptedGeometryRecords_。 - 收敛后统计结果,由
TxtResultWriter写出。
- 新的种子策略:实现
ISeedSelector - 新的阈值策略:实现
IThresholdPolicy - 新的候选管理方式:实现
ICandidateManager - 新的插入判定规则:实现
IInsertionPolicy - 新的真实 TIN 后端:实现
ITIN - 新的预处理能力:实现
IDenoiser
不建议的做法:
- 把策略规则直接写进
PTDEngine - 把具体几何库类型泄露到上层
- 把实验脚本逻辑反向耦合进核心模块