温室地面分割 Benchmark 工具

这是一个独立的温室 PCD 地面分割评测工具骨架，目标是把不同算法放到同一份预处理输入、同一套输出目录和同一套二维栅格规则下进行横向比较。当前版本优先保证结构清晰、参数可调、日志可落盘、后续易扩展。

当前状态

已实现：

• 统一 YAML 配置加载与命令行覆写
• 统一预处理流程
• ASCII PCD 和 binary PCD 读取
• ransac_global
• ransac_tiled
• elevation_grid
• 统一结果目录、栅格输出、预览图、汇总报告
• pmf、csf、gseg3d 适配器占位

暂未完成：

• binary_compressed PCD 读取
• PMF / CSF / GSeg3D 真正接入
• ROI 真值精度评价
• occupancy_clean 形态学后处理
• 更高效的近邻搜索与大点云优化

目录结构

ground_benchmark/
  algorithms/
scripts/
configs/
  algorithms/
  experiments/
  rois/

环境依赖

• Ubuntu 22.04
• Python 3.10+
• numpy
• PyYAML
• matplotlib
• pandas
• psutil

如果后续要接入 pmf / csf / gseg3d，建议把第三方依赖独立记录到对应算法 README 或配置旁注中。

快速运行

先跑单个算法：

python3 scripts/run_single.py \
  --input 20260106_165109.pcd \
  --algorithm ransac_global \
  --config configs/algorithms/ransac_global.yaml \
  --set preprocessing.voxel_leaf_size=0.05 \
  --set preprocessing.sor_mean_k=20 \
  --set preprocessing.sor_stddev_mul=1.0 \
  --set grid_projection.resolution=0.05 \
  --set dataset.name=greenhouse_map_01 \
  --output results/greenhouse_map_01/ransac_global/run_001

更推荐先把公共配置和算法配置合并后再跑。当前批量脚本已经内置这个合并逻辑：

python3 scripts/run_all.py \
  --dataset greenhouse_map_01 \
  --input 20260106_165109.pcd \
  --experiment configs/experiments/coarse_round_01.yaml

生成汇总报告：

python3 scripts/generate_report.py --results-root results

真实温室地图首轮命令

下面这两条是已经在 20260106_165109.pcd 上跑通的示例，适合先快速看一个代表性区域的分割效果：

MPLCONFIGDIR=/tmp python3 scripts/run_single.py \
  --input 20260106_165109.pcd \
  --algorithm ransac_global \
  --config configs/common.yaml \
  --set dataset.name=greenhouse_map_01_real_roi_b \
  --set preprocessing.crop.enabled=true \
  --set preprocessing.crop.min_x=0 \
  --set preprocessing.crop.max_x=8 \
  --set preprocessing.crop.min_y=-20 \
  --set preprocessing.crop.max_y=-10 \
  --set preprocessing.crop.min_z=-2 \
  --set preprocessing.crop.max_z=3 \
  --set preprocessing.voxel_leaf_size=0.15 \
  --set preprocessing.sor_mean_k=12 \
  --set preprocessing.sor_stddev_mul=1.0 \
  --set grid_projection.resolution=0.1 \
  --set algorithm.distance_threshold=0.08 \
  --set algorithm.max_ground_angle_deg=15 \
  --set algorithm.random_seed=42 \
  --set algorithm.iterations=120 \
  --output results/greenhouse_map_01_real_roi_b/ransac_global/run_001

MPLCONFIGDIR=/tmp python3 scripts/run_single.py \
  --input 20260106_165109.pcd \
  --algorithm elevation_grid \
  --config configs/common.yaml \
  --set dataset.name=greenhouse_map_01_real_roi_b \
  --set preprocessing.crop.enabled=true \
  --set preprocessing.crop.min_x=0 \
  --set preprocessing.crop.max_x=8 \
  --set preprocessing.crop.min_y=-20 \
  --set preprocessing.crop.max_y=-10 \
  --set preprocessing.crop.min_z=-2 \
  --set preprocessing.crop.max_z=3 \
  --set preprocessing.voxel_leaf_size=0.15 \
  --set preprocessing.sor_mean_k=12 \
  --set preprocessing.sor_stddev_mul=1.0 \
  --set grid_projection.resolution=0.1 \
  --set algorithm.resolution=0.2 \
  --set algorithm.initial_ground_mode=percentile_10 \
  --set algorithm.ground_height_threshold=0.1 \
  --set algorithm.min_points_per_cell=2 \
  --output results/greenhouse_map_01_real_roi_b/elevation_grid/run_001

结果目录

每次运行会输出到：

results/<dataset>/<algorithm>/<run_id>/

典型文件包括：

• benchmark_input.pcd
• preprocessing_stats.json
• config_resolved.yaml
• ground.pcd
• nonground.pcd
• occupancy_raw.pgm
• occupancy_raw.yaml
• occupancy_raw.csv
• occupancy_clean.pgm
• occupancy_clean.yaml
• occupancy_clean.csv
• preview_topdown.png
• runtime.json
• metrics.json

设计说明

可复用性

每个算法都通过统一入口注册。后续如果你要接一个新算法，只需要：

1. 在 ground_benchmark/algorithms/ 下新增实现；
2. 注册名字；
3. 在 configs/algorithms/ 下补一份 YAML；
4. 在实验配置里增加一组运行项。

参数调节

单次运行支持 --set key=value 覆写，例如：

python3 scripts/run_single.py \
  --input 20260106_165109.pcd \
  --algorithm elevation_grid \
  --config merged.yaml \
  --set algorithm.initial_ground_mode=percentile_20 \
  --set algorithm.ground_height_threshold=0.1 \
  --output results/tmp/elevation_grid/test_01

后续优先补强建议

1. 增加 ASCII/二进制 PCD 双格式支持
2. 用 scipy.spatial.cKDTree 优化 SOR 和局部搜索
3. 补 ROI 标签读取与点级指标
4. 把 pmf 真正接到 PCL 可执行程序或 Python 绑定
5. 把 csf / gseg3d 做成独立外部命令适配器

注意事项

• 当前版本不会修改原始 PCD。
• 当前版本对超大点云的内存占用还比较高，特别是 SOR 步骤。
• 如果输入 PCD 是二进制格式，脚本会明确报错而不是静默失败。