# coupler_panel — 集成开发者使用指南

> 高铁车钩面板偏转角与最大偏差测量算法
>
> 主输入：**CAD STP + 点云 PLY + ROI JSON**
>
> 主输出：两个方向偏转角 `θ_right` / `θ_ref`、最大 x 向偏差 `dx_y_max` / `dx_z_max`，以及一份完整可序列化的 `report.json`。

---

## 1. 一句话集成

```python
from coupler_panel.pipeline import run_coupler_measurement_pipeline

result = run_coupler_measurement_pipeline(
    input_cloud   = "scan.ply",          # 你的测量点云（已在 CAD 帧）
    cad_stp_path  = "panel.stp",         # 同款面板的 CAD STP
    roi_json      = "roi.json",          # ROI 描述（不裁剪就传 mode=all）
    out_dir       = "runs/today",        # 中间产物 + report.json 落盘目录
)

print(result.theta_right_deg, result.theta_ref_deg)     # 两个偏转角
print(result.dx_y_max_mm,     result.dx_z_max_mm)       # 最大 x 偏差
```

返回 `CouplerMeasurement`，全字段语义见 §4。`out_dir` 下额外得到 8 个文件（含 `report.json`，便于排查 / 后处理）。

---

## 2. 安装

```bash
# 全量安装（推荐）— core + 点云 IO + STP 解析 + 可视化 + Excel
python -m pip install -r requirements.txt
pip install -e ".[all]"

# 也可以按需取子集（见 pyproject.toml 的 extras）：
pip install -e ".[cloud]"     # 只要点云 + 去噪
pip install -e ".[cad]"       # 需要解析 STP
pip install -e ".[report]"    # 需要 Excel 报表
```

`requirements.txt` 锁定了端到端跑通过的版本（Python 3.10 验证）。

---

## 3. 三件输入的准备

### 3.1 CAD STP

- 提供面板的 STEP 文件路径。
- 算法用它做两件事：
  1. 从拓扑直接提 4 个定位孔 + 中心大孔 + 面板法向（写入 `01_gt.json`，作审计用）
  2. 把 CAD 法向作为 `panel_normal_seed` 喂给 hole-detection 的投影几何，加速并稳定 2D 网格化
- **可以不传**（`cad_stp_path=None`）—— 此时 hole detection 走 PCA 自行估法向；适用于你已经预先把法向算好/扫描坐标系本来就规范的场景。建议生产里**始终传**，便于审计。

### 3.2 点云 PLY

- 支持 `.ply` / `.pcd` / `.xyz` / `.txt` / `.csv`（PCD 与二进制 PLY 需要 open3d）。
- 数组形状 `(N, 3)`，单位 **mm**。
- **必须在 CAD 坐标系**：
  - x = 车体纵向，y = 车体宽度，z = 车体高度
  - 算法默认面板法向 `n_x > 0`
- **不再做配准**（参见 §6 "为什么不配准"）。这意味着上游扫描端外参必须已经标定 —— 把点云对齐到 CAD 帧是扫描软件的职责，不是本算法的职责。
- 可以带颜色 / 法向等额外列；算法只读前 3 列。

### 3.3 ROI JSON

定义"PLY 里哪些点要纳入后续算法"，**轴对齐 bounding box（AABB）**格式：

```json
{
  "x_min": -12500.0,
  "x_max":  12500.0,
  "y_min":    150.0,
  "y_max":   4100.0,
  "z_min":  -1680.0,
  "z_max":    200.0
}
```

六个 key 全部必填，单位 mm，坐标系 CAD 帧。点 `(x, y, z)` 被保留的条件是：

```
x_min <= x <= x_max  ∧  y_min <= y <= y_max  ∧  z_min <= z <= z_max
```

- **想保留全部点云**：把 6 个边界写得比点云自身 bbox 还宽即可（不需要任何 mode 切换）。
- **想不写文件**：传 `roi_json=None`，算法走"±∞" 默认（pass-through）。
- **想程序内构造**：传 `roi_spec=ROISpec(x_min=..., ...)`。

---

## 4. 公共 API 详解

### 4.1 主入口 `run_coupler_measurement_pipeline`

```python
def run_coupler_measurement_pipeline(
    input_cloud : str | Path,             # 必填：点云路径
    out_dir     : str | Path,             # 必填：输出目录（自动创建）
    *,
    config_path : str | Path | None = None,    # 可选：自定义 YAML
    profile     : str = "auto",                # 可选：preset profile
    cad_stp_path: str | Path | None = None,    # 推荐：CAD STP 路径
    roi_spec    : ROISpec | None    = None,    # 二选一：内存 ROI 对象
    roi_json    : str | Path | None = None,    # 二选一：ROI JSON 路径
    progress    : Callable[[str, float], None] | None = None,
) -> CouplerMeasurement
```

**算法链路（固定不可绕过）**：
```
load_point_cloud → apply_roi → [optional CAD parse → panel_normal_seed]
                 → denoise_cloud → compute_coupler_measurement
                                    ├─ validate
                                    ├─ detect 4 holes
                                    ├─ build reference frame
                                    ├─ extract panel ROI
                                    ├─ fit panel plane (RANSAC + SVD)
                                    └─ compute metrics
```

**Profile**：传 `"auto"` 即可；若你的面板型号对应到一个特定 profile，可指定 `profile="lu1_af4"` 等（详见 `configs/profiles/`）。

**配置覆盖**：
```python
result = run_coupler_measurement_pipeline(
    input_cloud="scan.ply",
    out_dir="runs/x",
    config_path={
        # 任何在 configs/default.yaml 里的字段都可以这样覆盖
        "denoise": {"steps": [{"type": "voxel", "voxel_mm": 0.3}]},
        "plane_fit": {"ransac_inlier_thresh_mm": 1.0},
        "metrics":   {"right_axis_sign": -1},
    },
)
```

### 4.2 返回值 `CouplerMeasurement`

```python
@dataclass
class CouplerMeasurement:
    # 版本号
    schema_version:    str       # 字段语义稳定性 → SCHEMA_VERSION
    algorithm_version: str       # 数值结果稳定性 → ALGORITHM_VERSION

    # === 6 个主测量量 ===
    theta_right_deg: float       # 右偏转角 atan2(n_y, n_x)，applied right_axis_sign
    theta_ref_deg:   float       # 上偏转角 atan2(n_z, n_x)
    D_y_max_mm:      float       # max |y_i - C_y|
    D_z_max_mm:      float       # max |z_i - C_z|
    dx_y_max_mm:     float       # |A| · D_y_max,  A = -n_y/n_x
    dx_z_max_mm:     float       # |B| · D_z_max,  B = -n_z/n_x

    # === 几何 ===
    center_C: tuple[float, float, float]    # 面板中心 (4 孔均值)
    normal:   tuple[float, float, float]    # 拟合面板法向，n_x > 0

    # === 详细子结构 ===
    holes:  HoleSet       # 检测到的 4 个定位孔 + 可选中心孔
    plane:  PanelPlane    # normal + offset + inlier_ratio + RMS
    frame:  ReferenceFrame  # C + 参考面 z=C_z + 纵向中面 y=C_y

    # === 诊断 ===
    quality_flags: list[str]      # 例如 'plane_inlier_ratio_low'
    timings:       list[StageTiming]   # 每阶段秒数 + 峰值内存
    report:        dict           # 全量可序列化，与 report.json 一致
```

```python
result.to_dict()    # 完全 JSON 化的 dict（落 DB / 网络传输用）
```

### 4.3 异常

```
CouplerError                          # 所有可预见异常的基类
├── InvalidPointCloudError           # 输入形状/dtype/NaN 非法
│   └── UnsupportedFormatError       # 文件后缀不支持
├── InsufficientPointsError          # 点数 < 200 或 ROI 后 < 100
├── CADParseError                    # STP 解析失败 / 找不到 4 孔
├── HoleDetectionError               # 点云上 4 孔检测失败
└── PlaneFitError                    # RANSAC 找不到平面
```

非致命问题通过 `result.quality_flags` 暴露：

| Flag | 含义 |
|---|---|
| `plane_inlier_ratio_low` | 平面拟合内点率低于 `plane_fit.min_inlier_ratio` |

### 4.4 进度回调

```python
def on_progress(stage: str, fraction: float) -> None:
    print(f"[{fraction:5.1%}] {stage}")

result = run_coupler_measurement_pipeline(..., progress=on_progress)
```

阶段顺序：`validate → detect_holes → build_frame → extract_roi → fit_plane → metrics`。

---

## 5. ROI JSON schema 详细

**完整字段**（6 个 key，全部必填，单位 mm，坐标系 CAD 帧）：

```json
{
  "x_min": -12500.0,
  "x_max":  12500.0,
  "y_min":    150.0,
  "y_max":   4100.0,
  "z_min":  -1680.0,
  "z_max":    200.0
}
```

**规则**：

- 必须满足 `x_min < x_max` 且 `y_min < y_max` 且 `z_min < z_max`，否则 `load_roi_json` 抛 `ValueError`
- 不在 [min, max] 闭区间内的点被丢弃（用 `>=` 与 `<=`，包含边界）
- 多余的 key（例如 `comment`、`source`）会被忽略，方便挂元数据

**手动构造 ROI（不读文件）**：

```python
from coupler_panel.roi_select import ROISpec, default_roi_spec

# 全保留默认（六个轴都是 ±∞）
spec = default_roi_spec()

# 自定义 bbox
spec = ROISpec(
    x_min=-12000, x_max=  100,
    y_min=  -300, y_max= 1200,
    z_min= -1000, z_max=  800,
)

result = run_coupler_measurement_pipeline(..., roi_spec=spec)
```

**诊断输出**：

每次运行后 `out_dir/roi.json` 写出实际生效的 spec + 应用诊断：

```jsonc
{
  "spec": { "x_min": -12000.0, ... },
  "diagnostics": {
    "kind": "aabb",
    "n_in":  96662,
    "n_out": 96662,
    "kept_ratio": 1.0,
    "bounds": { "x_min": -12000.0, ... }
  }
}
```

---

## 6. 为什么主路径**不做配准**

车钩面板上的 4 个定位孔与面板一起刚体旋转。如果用"扫到的 4 孔 → CAD 原始 4 孔"做 Kabsch 配准，数学上会**精确解出**"扫描器位姿误差 · 面板偏转"的复合刚体变换并反向作用 —— 把面板偏转随同位姿误差**一起消掉**，下游平面拟合再读不到偏转信号。

这是几何性质，不是实现 bug。

工程上，主算法假设扫描端外参标定让点云已经在 CAD 帧。如果你的设备做不到位姿标定，要么：
1. 在面板**外**装基准（不动）做 Kabsch
2. 用 ICP 或其他不依赖 4 孔的方法

研究模式（`coupler_panel.pipeline.run_from_cad_pipeline`）保留了 4 孔 Kabsch + 注入偏转 oracle 的能力，用于上限对照实验；生产集成请用 `run_coupler_measurement_pipeline`。

---

## 7. 落盘产物（`out_dir/`）

| 文件 | 内容 |
|---|---|
| `config.resolved.yaml` | 解析合并后实际生效的完整配置 |
| `roi.json` | ROI spec + 应用诊断（n_in / n_out / kept_ratio） |
| `01_gt.json` | （传了 cad_stp_path 时）从 STP 提的审计用 GT |
| `02_sampled.ply` | ROI 裁剪后的点云 |
| `05_denoised.ply` | 去噪后点云（喂给测量算法的最终点云） |
| `10_metrics.json` | 等价于 `report.json` 的内部 report 部分 |
| `report.json` | **完整结果**，等于 `result.to_dict()`；schema 见 §4.2 |
| `images/` | 占位空目录（仅 `viz` 模块写图时会用） |

---

## 8. 集成模板

```python
import logging
from pathlib import Path

from coupler_panel.pipeline import run_coupler_measurement_pipeline
from coupler_panel.exceptions import CouplerError

log = logging.getLogger(__name__)


def measure_coupler(
    cloud_path: Path,
    cad_stp:    Path,
    roi_json:   Path,
    out_dir:    Path,
) -> dict | None:
    """主集成入口。失败时返回 None；成功时返回 6 个测量量 + flags。"""
    try:
        result = run_coupler_measurement_pipeline(
            input_cloud  = cloud_path,
            cad_stp_path = cad_stp,
            roi_json     = roi_json,
            out_dir      = out_dir,
            progress     = lambda s, f: log.debug("%s %.0f%%", s, f * 100),
        )
    except CouplerError as exc:
        log.error("coupler measurement failed: %s", exc)
        return None

    if result.quality_flags:
        log.warning("quality flags: %s", result.quality_flags)

    return {
        "schema_version":    result.schema_version,
        "algorithm_version": result.algorithm_version,
        "theta_right_deg":   result.theta_right_deg,
        "theta_ref_deg":     result.theta_ref_deg,
        "dx_y_max_mm":       result.dx_y_max_mm,
        "dx_z_max_mm":       result.dx_z_max_mm,
        "center_C_mm":       list(result.center_C),
        "normal":            list(result.normal),
        "flags":             result.quality_flags,
    }
```

---

## 9. 命令行（备用，非主集成路径）

```bash
# 等价于 run_coupler_measurement_pipeline(input_cloud=..., out_dir=...)
coupler-measure --input-cloud scan.ply --out-dir runs/today
```

> 当前 CLI 暂未把 `--cad` 与 `--roi` 暴露出来（设计上 CLI 主要给研究流程用）；集成方请直接用 Python API。

---

## 10. 版本兼容性

| 标识 | 在哪 | 含义 |
|---|---|---|
| `coupler_panel.__version__` | `coupler_panel._version` | 包版本，遵循语义化版本 |
| `coupler_panel.ALGORITHM_VERSION` | 同上 | 算法版本；升级算法时递增，**数值结果可能变化** |
| `coupler_panel.SCHEMA_VERSION` | 同上 | `CouplerMeasurement` / `report.json` 字段结构；只在破坏性变更时递增；**新增可选字段不递增** |

集成建议：
1. 落库时把 `algorithm_version` 写进每条记录，便于历史复现
2. 反序列化 `report.json` 时校验 `schema_version` 主版本号

---

## 11. 坐标 & 单位速查

| 量 | 单位 | 约定 |
|---|---|---|
| 点云坐标 | mm | x=纵向、y=宽度、z=高度 |
| 角度 | 度 (deg) | `θ_right` = atan2(n_y, n_x)、`θ_ref` = atan2(n_z, n_x) |
| 法向 | 单位向量 | 强制 `n_x > 0` |
| `right_axis_sign` | ±1 | 如果车体"右"是 +y 留 1；如果是 -y 则配置 -1 |