# coupler-panel-validation

高铁车钩面板**偏转角测量**算法。输入待测点云 + ROI + 理论 CAD，输出面板相对车体纵轴的两个方向偏转角及最大偏差，并生成 Excel 报表。

## 这个项目做什么

给定一块车钩安装面板的扫描点云，算法测量它相对理论安装姿态的**偏转**：

- `θ_right` —— 面板法向在一个方向上的偏转角（度）
- `θ_ref` —— 面板法向在另一个方向上的偏转角（度）
- `dx_y_max` / `dx_z_max` —— 由偏转引起的最大 x 向偏差（mm）

支持两种输入规模：
- **单零件点云**（对零件 STP 采样得到的稠密点云）
- **整车扫描点云**（GB 级 PLY，用 ROI 框出车钩区域后内部流式裁剪）

## 三件套输入（集成主路径）

| 输入 | 说明 |
|---|---|
| **ROI JSON** | 6 个数的轴对齐包围盒，框出待测面板区域（即裁剪超参数） |
| **点云 PLY** | 待测点云，可为整车（多 GB），算法内部按 ROI 流式裁剪 |
| **CAD STP** | 理论模型，作辅助 / 审计 |

输出：`eval_report.xlsx`（含两个偏转角的 GT / 预测 / 误差 + 中间量 + 运行时间）。

## 快速开始

```bash
# 安装（锁定版本见 requirements.txt）
python -m pip install -r requirements.txt
pip install -e ".[all]"

# 三件套集成入口
python examples/run_integration.py \
    --roi   examples/roi_train2_coupler.json \
    --cloud /path/to/train_2_1T.ply \
    --stp   /path/to/asm.stp \
    --out   runs/train2 \
    --profile train2_coupler
```

库调用：

```python
from coupler_panel.pipeline import run_coupler_measurement_pipeline
from coupler_panel.roi_select import load_roi_json

result = run_coupler_measurement_pipeline(
    input_cloud = "train_2_1T.ply",
    out_dir     = "runs/train2",
    profile     = "train2_coupler",
    roi_spec    = load_roi_json("roi_train2_coupler.json"),
)
print(result.theta_right_deg, result.theta_ref_deg)
```

## 文档

| 文档 | 内容 |
|---|---|
| [USAGE.md](USAGE.md) | **集成方使用指南** —— 三件套输入、API、ROI JSON、profile、输出、坐标系 |
| [CHANGES.md](CHANGES.md) | **修改记录** —— 每轮改了什么、为什么、遇到的问题与定位解决 |

## 坐标系约定

- 算法以面板法向 `n=(n_x,n_y,n_z)` 相对 x 轴的夹角定义偏转，强制 `n_x>0`。
- **坐标轴含义由数据集决定**：项目标称约定为 x=纵向、y=宽度、z=高度；但某些整车数据集为 x=车长、y=车高、z=车宽（y/z 对调）。偏转角公式对称、理论 0 不受影响，但 `D_y_max`/`D_z_max` 对应的物理轴随之对调。ROI JSON 的六个边界必须与**点云自身坐标系**一致。详见 USAGE.md。