massive-cloud/docs/车钩面板算法分析.md

车钩面板算法性能分析报告

分析时间：2026-06-25
算法版本：delivery_v1.2.1 / coupler_panel_release
适用场景：ROI 裁剪后的车钩面板局部点云（~数万点）
测试环境：INTEL SSDSC2KB01（SATA SSD，~394 MB/s）；A100 40 GB；CPU 128 核

---

执行流程总览

run_coupler_measurement_pipeline()
    ├─ load + ROI clip             # 流式读取 / 全量加载后裁剪
    ├─ select_panel_layer()        # 可选层隔离（layer_select.enabled）
    ├─ parse_cad()                 # 可选 STEP CAD 解析
    ├─ autotune detection config   # 可选参数自适应
    ├─ denoise_cloud()             # 去噪流水线（passthrough/voxel/SOR/ROR）
    └─ compute_coupler_measurement()
           ├─ detect_four_holes()  # 占位格 → 圆拟合 → 4 孔检测 ← 主要耗时
           ├─ plane_fit()          # 平面拟合
           └─ compute_deflection_metrics()

---

各步骤详细说明与时间估算

第一阶段：I/O 与 ROI 裁剪

#	步骤	代码位置	说明	估算时间
1	crop_ply_bbox 流式裁剪	pipeline.py:109	当提供 ROI 且输入为 binary PLY 时，分块读取，无需全量加载（关键优化）	~5–30 s（取决于文件大小）
1b	全量 load_point_cloud	pipeline.py:117	无 ROI 时全量加载；1 亿点 ~2 GB binary PLY	~15 s
2	apply_roi 掩码	pipeline.py:118	O(N) numpy 布尔索引	< 1 s

重要：crop_ply_bbox 是 v1.2.1 新增的流式裁剪，避免了整车大点云全量加载。必须在前端配置 ROI 参数，否则回退到全量加载再过滤。

---

第二阶段：可选层隔离与 CAD 解析

#	步骤	代码位置	说明	估算时间
3	select_panel_layer	pipeline.py:137	PCA 法向 + 沿法向直方图取单层；仅当 layer_select.enabled=true 时运行	~2 s
4	parse_cad（STEP → mesh + GT）	data_prep.py:111	OCC tessellate STEP + 提取定位孔 GT；仅当传入 cad_stp_path 时运行	~5–30 s（取决于 STEP 复杂度）
5	detection_overlay autotune	pipeline.py:190	从 CAD 孔半径 + 降采样间距自适应调整 detection 参数	< 1 s

---

第三阶段：去噪（denoise_cloud）

去噪流水线按 YAML config 中 denoise.steps 顺序执行，ROI 裁剪后的局部云通常只剩 数千到数万点，各步骤很快。

#	步骤	代码位置	使用 Open3D C++ 实现	说明	估算时间
6	passthrough_filter（轴截取）	denoise/passthrough.py	是（bbox crop）	沿轴裁剪额外边界；O(N)	< 0.1 s
7	voxel_downsample（VGF）	denoise/voxel.py	是（o3d.voxel_down_sample）	体素降采样，C++ 加速	< 0.5 s
8	statistical_outlier_removal（SOR）	denoise/statistical.py	是（o3d.remove_statistical_outlier）	k-NN 统计离群，C++ 加速	< 1 s
9	radius_outlier_removal（ROR）	denoise/radius.py	是（o3d.remove_radius_outlier）	半径离群，C++ 加速	< 1 s

与 underframe-deflection 的 preprocess 对比：去噪用的是 Open3D C++ 实现，不是 scipy Pure Python，在局部云上几乎无延迟。

---

第四阶段：4 孔检测（主要耗时）

#	步骤	代码位置	说明	估算时间
10	投影到面板平面 + 占位格生成	detection/occupancy_grid.py	PCA 面板法向投影 → 2D 栅格	~1 s
11	孔形空腔检测	detection/detect_holes.py	连通分量 → 面积/圆度 筛选 4 孔；若参数不匹配则抛 HoleDetectionError	~2–5 s
12	circle_fit 精确圆心	detection/circle_fit.py	Taubin 圆拟合，O(M) per hole	~1 s
13	four_hole_selector 4 孔配对	detection/four_hole_selector.py	象限排序 + 几何验证	< 1 s

瓶颈：孔检测依赖 grid_pixel_mm / hole_*_area_mm2 参数匹配。参数不适配会触发 HoleDetectionError，需通过 autotune 或手动指定 profile 解决。

---

第五阶段：测量与输出

#	步骤	代码位置	说明	估算时间
14	plane_fit 精确平面拟合	api.compute_coupler_measurement	SVD 平面拟合	< 1 s
15	compute_deflection_metrics	metrics.py	角度 / 偏移量计算	< 1 s
16	写输出（JSON / PLY / Excel）	pipeline.py	report JSON + xlsx	~2 s

---

总时间汇总

场景	估算耗时	说明
正常流程（有 ROI + 有 CAD）	~1–2 min	主要耗在 STEP 解析和孔检测
无 ROI 的整车输入（1 亿点）	~10 min+	全量加载 + 全量 SOR/ROR 过滤
检测参数不匹配（HoleDetectionError）	失败	需调整 grid_pixel_mm 或使用 autotune

---

主要瓶颈与优化建议

问题	原因	解决方案
HoleDetectionError 频繁发生	grid_pixel_mm 过大或 hole_area 范围不含目标孔	提供 CAD STEP 启用 autotune，或在 manifest 配置 profile
整车云输入太慢	无 ROI 时全量加载 + 全量 SOR/ROR	必须在前端配置 ROI；或 manifest 中配置合理默认 ROI
STEP 解析慢	OCC tessellate 复杂曲面	可预先生成 STL 绕过 OCC；或启用 CAD sample 缓存

---

GPU 使用情况

不使用 GPU。 所有计算为 CPU + numpy + Open3D，无 torch/CUDA 依赖。