# underframe_deflection 使用指南

> 面向软件集成方。说明如何用「**待测整车点云 + 理论 CAD（stp）+ ROI JSON**」三件套输入，
> 调用算法，得到含挠度核心数据的 Excel 输出。

---

## 1. 输入与输出

### 输入（集成方提供）

| 文件 | 格式 | 必需 | 说明 |
| --- | --- | --- | --- |
| **待测整车点云** | `.ply`（ASCII 或 binary） | ✅ | 现场扫描的整车点云。支持超大文件（实测 12GB / 10 亿点，流式裁剪不爆内存） |
| **理论 CAD** | `.stp` | ✅（按需用） | 理论模型。**当前实例点云已配准**，CAD 仅记录路径作溯源；需重新配准时见 §4 |
| **ROI JSON** | `.json` | ✅ | 每根梁一个，描述该梁的轴对齐裁剪框（AABB） |

> 左右梁是**两次独立调用**：左梁一个 ROI → 一份输出；右梁一个 ROI → 一份输出。

### 输出（左右各一份）

```
out_dir/
├── left/
│   ├── report.xlsx          ← 挠度核心数据 Excel（Summary + Deflection_Curve）
│   ├── report.json          ← 完整结果（机器读）
│   ├── deflection_curve.csv ← 沿车长的逐点挠度
│   └── deflection_curve.png ← 诊断图
├── right/                   ← 同上结构
└── summary.json             ← 左右汇总
```

---

## 2. ROI JSON 格式

坐标系：**x = 车长（纵向），y = 车高（挠度方向），z = 车宽（横向）**，单位 mm。

```json
{
  "x_min": -100000.0,
  "x_max":  100000.0,
  "y_min":    919.950,
  "y_max":   1399.950,
  "z_min":    948.623,
  "z_max":   1752.212
}
```

- `x` 给一个覆盖整车长度的大区间即可。
- `y`（车高）框住梁所在的高度带。
- `z`（车宽）分左右：左梁取正侧，右梁取负侧。
- 仓库 `test_data/roi_left_beam.json` / `roi_right_beam.json` 是可直接用的样例。

约束：每轴 `min < max`，均为有限实数；非法 → `InvalidPointCloudError`。

---

## 3. 调用方式

### 3.1 命令行

```bash
underframe-measure \
  --input-cloud  train.ply \
  --left-roi     roi_left_beam.json \
  --right-roi    roi_right_beam.json \
  --cad          theoretical.stp \
  --out-dir      out/
```

默认 `--mode single`、默认**不配准**（点云已配准），`--cad` 的 stp 路径记录进报告。

可选开关：`--enable-registration`（§4）、`--config FILE.json`（覆盖参数）、
`--skip-excel`、`--skip-plot`、`--side left|right`（配 `--roi` 单根时用）。

### 3.2 Python API（推荐集成）

```python
from underframe_deflection import run_both_beams

summary = run_both_beams(
    input_cloud="train.ply",
    left_roi="roi_left_beam.json",
    right_roi="roi_right_beam.json",
    out_dir="out/",
    cad_path="theoretical.stp",     # 记录路径；配准默认关
    enable_registration=False,      # 见 §4
)

for side in ("left", "right"):
    d = summary[side]["deflection"]
    print(side,
          "最大挠度(带符号) =", d["selected_signed_mm"], "mm",
          "@ x =", d["selected_x_mm"], "mm",
          "| RMS =", d["rms_mm"], "mm")
```

单根梁独立调用：

```python
from underframe_deflection import run_single_beam_pipeline

report = run_single_beam_pipeline(
    input_cloud="train.ply",
    roi_path="roi_left_beam.json",
    out_dir="out/left",
    side="left",
    cad_path="theoretical.stp",
)
```

---

## 4. 配准开关

挠度测量的完整物理流程：**扫描点云 → 用 CAD 配准到标准姿态 → 测梁下表面相对理想基准的偏差**。
配准消除安装 / 摆放 / 扫描姿态引入的整体倾斜。

| `enable_registration` | 行为 | 适用 |
| --- | --- | --- |
| `False`（默认） | 不配准，点云按原样裁剪测量 | **点云已预配准**（本实例） |
| `True` | 先把整车点云刚性对齐到 CAD，再裁剪测量 | 点云未配准 |

配准开启时对 CAD 的要求：
- 必须是**可读的点云 / 网格**（`.ply / .xyz / .stl / .obj`）。
- `.stp` **不直接解析**（STEP 解析需重型依赖）。若只有 stp，先用
  `tools/cad_sampling/step_to_pointcloud.py` 离线采样成 `.ply` 再传 `--cad`。
- 传 stp + 开配准时**不会崩溃**，而是记录提示"STEP not parsed; convert first"并跳过配准。

> 本次交付的测试样本点云**已配准**，所以默认关。配准算法（ICP）已完整保留，随时可启用。

---

## 5. 输出 Excel（report.xlsx，左右各一份）

### Sheet「检测报表」（核心交付，6 列）

| 列 | 本项目取值 |
| --- | --- |
| 项点名称 | 纵向梁到直线的垂直偏差（挠度） |
| 理论尺寸 | 0 |
| 公差要求 | 左梁 ±7mm / 右梁 ±12mm |
| 测量结果 | 实测最大挠度（mm） |
| 误差结果 | 与理论 0 的误差（= 测量结果，因理论值为 0） |
| 测量结论 | 误差 ≤ 公差 → **合格**，否则 → **不合格** |

**左右判定**：面朝 x 正方向，`z > 0` 为左梁（公差 7mm），`z < 0` 为右梁（公差 12mm）。
程序按 ROI 的 z 中心**自动判定**，不依赖文件名——即使左右 ROI 文件传反也不会用错公差。

公差可覆盖：命令行 `--left-tolerance` / `--right-tolerance`（两梁模式）或 `--tolerance`（单梁模式）；
Python API 同名参数 `left_tolerance_mm` / `right_tolerance_mm` / `tolerance_mm`。

### Sheet「明细」（溯源，key/value）

输入文件路径、是否配准、ROI 命中点数、切片数、参考线斜率、最大下凹/上凸、RMS、质量警告等。

### Sheet「挠度曲线」

沿车长逐点表：`x_mm, underside_height_mm, reference_height_mm, deflection_mm, kept`。

---

## 6. 异常与质量标记

| 异常 | 触发 |
| --- | --- |
| `InvalidPointCloudError` | 点云 / ROI 格式非法、AABB 反转 |
| `InsufficientPointsError` | ROI 命中点过少（< 2000） |

非致命质量标记（写进 `quality_flags`，不抛异常）：
`many_underside_spikes`（悬挂物/噪点偏多，已鲁棒剔除）、`low_surface_support`（下表面支撑点偏少）、
`insufficient_valid_slices` / `fit_unstable`（有效切片不足）。

集成方建议：外层 `try / except DeflectionError` 兜底，并把 `quality_flags` 落日志。

---

## 7. 算法原理

沿车长（x）分细切片 → 每片取**下表面主平面高度**（下半部直方图主峰，对悬挂物 / 噪点鲁棒）→
鲁棒拟合一条直线作理论基准 → 挠度 = 下表面高度 − 基准线。理论平直的梁，挠度 ≈ 0。

> 设计与验证的完整记录见 [`DEV_NOTES.md`](./DEV_NOTES.md)。

---

## 附录：双梁模式（legacy）

输入一片含左右两梁的车底点云 + CAD 基准 + ROI，自动配准 + 双梁追踪 + 样条拟合 + 孔参考线。

```bash
underframe-measure --mode dual \
  --input-cloud scan.ply --cad reference.ply --roi roi.json \
  --out-dir out/ --input-axis y_up
```

- `--input-axis {y_up,z_up}`：高度轴约定，默认 `y_up`（CAD/扫描约定 y=高度）。
- 输出 5-sheet Excel + 5 PNG + 4 PLY 叠加图。
- 该模式针对"双梁车底slab"，与单梁模式互不影响。