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

> 分析时间：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 依赖。