8000 GitHub - AkiTanXL/PTD: 用于复现和改进经典点云滤波算法PTD · GitHub
[go: up one dir, main page]

Skip to content
AkiTanXLPublic

About

用于复现和改进经典点云滤波算法PTD

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

36 Commits

Folders and files

Repository files navigation

PTD

PTD 是一个面向研究与工程复用的 C++17 点云地面滤波项目,目标是把经典 Progressive TIN Densification 做成可运行、可测试、可扩展的工程框架,而不是一次性的脚本复现。

当前仓库已经具备单块串行基线:支持 TXT 输入输出、经典 PTD 主流程、双阶段去噪、自适应阈值迭代、镜像点二次判定、可选 CGAL TIN 后端,以及 Python 批处理与评估工具。

1. PTD 算法原理

本项目所说的“经典 PTD”主要对应 Peter Axelsson 在 2000 年发表的工作:DEM Generation from Laser Scanner Data Using Adaptive TIN Models。该文通常被视为 PTD 的代表性原始文献,可参考 ISPRS proceedings 页面 和 原文 PDF。

PTD 的核心思想是:先用一小批可靠地面种子点建立一个稀疏 TIN,再用这个 TIN 逐轮吸收满足几何约束的候选点,直到地表模型收敛。它不是一次性全局分类,而是“保守建模 + 逐步加密”。

经典流程可以概括为:

  1. 在 XY 平面上按网格选取局部最低点,作为初始地面种子。
  2. 用种子点构建初始 TIN,作为当前地表参考。
  3. 对候选点定位其参考三角形,计算局部几何量。
  4. 若候选点满足阈值约束,则将其接纳为地面点,并插入 TIN。
  5. 重复迭代,直到候选集为空,或最新一轮没有新增地面点。

当前实现里,主判据主要依赖 3 个几何量:

  • distanceToReference:候选点到参考三角面的绝对距离。
  • angleToReferenceDegrees:候选点到参考三角形三个节点形成的最大节点角。
  • slopeDegrees:参考三角面的坡度,主要用于断裂地形的镜像点触发。

本仓库在经典 PTD 之上已经落地了几项工程化增强,但仍保持“引擎只编排、策略可替换”的边界:

  • ClassicSeedSelector:按网格最低点选种子;若种子无法形成有效初始三角形,会按全局低点继续补点。
  • 双阶段去噪:
    • GlobalBeforeSeed:选种子前对全量点去噪;
    • SeedAfterSelection:选出种子后再对种子子集去噪。
  • 阈值模式:
    • fixed:直接使用配置中的距离阈值和角度阈值;
    • adaptive:初始化轮基于“原始点云 + seed TIN”,后续轮基于“accepted geometry records”估计阈值。
  • 镜像点二次判定:当主判据未接纳、距离超阈值且坡度较大时,触发镜像路径,缓解陡坎和断裂地形误判。
  • TIN 抽象解耦:上层依赖 ITIN,构建时若找到 CGAL 则使用 CgalTinAdapter,否则回退到 FakeTIN。

当前版本的定位很明确:它是单块串行、可测试、可扩展的 PTD 工程基线,还不是完整的块处理或并行框架。

2. 面向用户:如何运行

环境

  • 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。

CLI 运行

最小示例:

./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/false
    • ground count: ...
    • non-ground count: ...
    • status: ...

Python 工具链

仓库内置两类实验工具:

  • 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_level
  • seed_cell_size
  • slope_threshold
  • distance_threshold
  • angle_threshold
  • threshold_mode
  • tin_update

其他常用命令

./build/benchmarks/ptd_denoiser_benchmark
./.venv/bin/python -m unittest discover -s tools/tests -v

3. 面向开发者:架构与模块职责

设计约束

  • PTDEngine 只做流程编排,不内嵌具体策略规则。
  • 种子选择、阈值获取、候选管理、插入判定都通过接口注入。
  • 上层不直接耦合具体三角化库,只依赖 ITIN。
  • PointCloud 保持 SoA 布局;PointView 负责只读子集绑定。
  • 当前虽然只跑单块串行流程,但接口边界要为 block / parallel 预留空间。

主要模块

  • apps/ptd_cli

    • 命令行入口;
    • 负责解析参数、装配默认策略、选择 TIN 后端并发起一次完整运行。
  • src/core

    • PointCloud:统一保存坐标、标签、状态;
    • PointView:只读子集视图,不复制底层点数据。
  • src/geometry

    • 负责纯几何计算;
    • 包括平面构造、点到平面距离、向量夹角、节点最大夹角、坡度等。
  • src/preprocessing

    • 负责去噪能力;
    • 当前核心是 IDenoiser、CombinedDenoiser、DenoiseContext、DenoiseResult。
  • src/spatial

    • 定义 TIN 抽象层;
    • ITIN 提供 buildInitialTIN、locateSurface、insertVertex;
    • 当前实现有 FakeTIN 和 CgalTinAdapter。
  • src/strategy

    • ISeedSelector:只负责选种子;
    • IThresholdPolicy:只负责准备和返回阈值;
    • ICandidateManager:只负责候选集合生命周期;
    • IInsertionPolicy:只负责根据几何量和阈值给出 Accept / Reject / Defer;
    • context.hpp 统一定义执行上下文、迭代上下文、局部几何、阈值集合和 accepted geometry records。
  • src/engine

    • PTDEngine 是真正的流程编排层;
    • 当前串起:全量去噪、种子选择、种子去噪、初始 TIN、候选初始化、逐轮阈值准备、主判据、镜像判据、TIN 更新、结果统计。
    • PTDResult 汇总成功状态、迭代轮次、分类计数和阶段耗时。
  • src/io

    • TxtPointCloudReader:读取 X Y Z label;
    • TxtResultWriter:写出 X Y Z label,并统一保证二分类协议。
  • src/util

    • Config、Logger、Timer、build_info 等基础设施。
  • tests

    • 按模块镜像组织;
    • 覆盖核心数据结构、去噪、TIN、策略、引擎、CLI 和 Python 工具链。
  • benchmarks

    • 当前提供 ptd_denoiser_benchmark。
  • tools

    • evaluate.py、run_isprs_batch.py、eval_aggregation.py 组成实验辅助层。

当前运行链路

  1. CLI 构造 Config。
  2. TxtPointCloudReader 把 TXT 载入 PointCloud。
  3. 引擎基于全量索引构造 PointView。
  4. 可选全量去噪,噪点直接落为 NonGround。
  5. ISeedSelector 选出种子。
  6. 可选种子去噪,噪声种子从初始 TIN 输入中剔除。
  7. ITIN 构建初始 TIN。
  8. ICandidateManager 初始化候选快照。
  9. 每轮由引擎准备阈值摘要,IThresholdPolicy 生成本轮阈值,IInsertionPolicy 给出主判据,必要时进入镜像点路径。
  10. 接纳点更新标签、状态和 TIN,并写入 acceptedGeometryRecords_。
  11. 收敛后统计结果,由 TxtResultWriter 写出。

推荐扩展点

  • 新的种子策略:实现 ISeedSelector
  • 新的阈值策略:实现 IThresholdPolicy
  • 新的候选管理方式:实现 ICandidateManager
  • 新的插入判定规则:实现 IInsertionPolicy
  • 新的真实 TIN 后端:实现 ITIN
  • 新的预处理能力:实现 IDenoiser

不建议的做法:

  • 把策略规则直接写进 PTDEngine
  • 把具体几何库类型泄露到上层
  • 把实验脚本逻辑反向耦合进核心模块

About

用于复现和改进经典点云滤波算法PTD

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0