# underframe-deflection

**从扫描点云测量高铁底架纵梁挠度的 Python 算法包：接受"CAD 基准 + 扫描点云 + ROI JSON"三件套输入，自动配准、去噪、识别梁、出 Excel 误差报表。**

[![python](https://img.shields.io/badge/python-3.10%2B-blue)]() [![version](https://img.shields.io/badge/version-1.1.0-green)]() [![status](https://img.shields.io/badge/status-beta-yellow)]()

---

## 这是什么

输入一份现场扫描点云（`.ply / .xyz`），一份 CAD 基准（`.ply / .stl / .obj`），一份描述测量区域的 ROI JSON，本包会：

1. **去噪**：passthrough → 统计离群 → 半径离群 → 双边滤波 → 体素降采样
2. **配准**：用 ICP 把扫描点云刚性对齐到 CAD 坐标系
3. **识别梁**：沿车长切片、Beam-search 跟踪左右纵梁
4. **拟合**：鲁棒样条拟合代表线
5. **找参考**：基于车体孔特征或线端点定参考线
6. **算挠度**：沿 X 轴逐点计算并选出绝对值最大的测量点

输出：完整 JSON 报告、Excel 误差报表（5 sheet）、沿 X 的挠度 CSV、候选切片诊断 CSV、5 张诊断 PNG、4 个着色 PLY 叠加图。

---

## 安装

```bash
# 进入本目录后
pip install -e .[all]              # 推荐：core + matplotlib + openpyxl

# 或仅安装核心 + 自己选 extra
pip install -e .                   # 仅 numpy + scipy（只能调用 compute_deflection）
pip install -e .[viz]              # +matplotlib（PNG 诊断图）
pip install -e .[excel]            # +openpyxl（.xlsx 报表）

# 或直接用 requirements 锁版本
pip install -r requirements.txt
```

安装后会注册命令行 `underframe-measure`，Python 内可直接 `import underframe_deflection`。

---

## 上手

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

或者 Python 调用：

```python
from underframe_deflection import run_measurement_pipeline

report = run_measurement_pipeline(
    input_cloud="scan.ply",
    cad_path="reference.ply",
    roi_path="roi.json",
    out_dir="out/",
)

print(report["deflection"]["left"]["selected_measurement"]["signed_deflection_mm"])
print(report["deflection"]["right"]["selected_measurement"]["signed_deflection_mm"])
```

`test_data/` 自带可直接运行的样例：

```bash
underframe-measure \
  --input-cloud test_data/m000004802409t02_asm_100000pts.ply \
  --cad         test_data/m000004802409t02_asm_100000pts.ply \
  --roi         test_data/sample_roi.json \
  --out-dir     test_data/runs/demo
```

---

## 文档导览

| 文件 | 用途 |
| --- | --- |
| **`README.md`** (本文件) | 仓库概览，30 秒上手 |
| **`USAGE.md`** | 集成开发者完整指南：三种调用方式、输入格式、读结果、异常、配置覆盖、模板 |
| `requirements.txt` | 锁定版本的依赖清单 |
| `pyproject.toml` | 打包描述（pip install 的入口） |

---

## 仓库结构

```
underframe_deflection/
├── README.md                  ← 本文件
├── USAGE.md                   ← 集成开发者文档
├── requirements.txt
├── pyproject.toml             ← pip 打包描述（无需 setup.py）
├── _version.py                ← __version__ / ALGORITHM_VERSION / SCHEMA_VERSION
├── __init__.py                ← 公开 API 出口
│
├── api.py                     ← compute_deflection() 主入口
├── pipeline.py                ← run_measurement_pipeline() 端到端编排
├── cli.py                     ← 命令行入口（underframe-measure）
│
├── config.py                  ← DEFAULT_CONFIG 与档位
├── preprocess.py              ← SOR / radius / voxel / normals / bilateral
├── cad_io.py                  ← CAD 读取 (PLY/XYZ/STL/OBJ)
├── registration.py            ← PCA 粗对齐 + trimmed ICP
├── roi.py                     ← ROI JSON 读取 + AABB passthrough
│
├── frame.py                   ← 车体坐标系推断 + ROI mask
├── beams.py                   ← 切片 + 候选条带 + Beam-search 跟踪
├── fitting.py                 ← 代表点 + 鲁棒样条拟合
├── reference.py               ← 参考线检测（孔 / 端点）
│
├── artifacts.py               ← JSON / CSV / PNG / PLY writer
├── excel_report.py            ← Excel 写入器 (5 sheet)
├── ply_overlay.py             ← 着色 PLY 叠加图
├── visualization.py           ← 诊断 PNG 绘图
│
├── io.py                      ← 文件 I/O 工具
├── exceptions.py              ← 公开异常层级
├── structures.py              ← 内部数据类
│
└── test_data/
    ├── m000004802409t02_asm.stp                    ← 原始 STEP（仅参考，不被解析）
    ├── m000004802409t02_asm_100000pts.ply          ← STEP 采样得到的 CAD 基准点云
    └── sample_roi.json                             ← 样例 ROI（AABB）
```

---

## 输入约定

所有点云的坐标轴必须：

- **X**：纵向（车长）
- **Y**：横向（车宽）
- **Z**：高度，**向上为正**
- 单位：**毫米**

CAD 基准也必须遵循同样的轴向；ROI JSON 中的 bbox 字段在 CAD 坐标系下。
如果你的扫描设备轴向不同，请在调用前自行做旋转/置换。

---

## 公开 API

```python
from underframe_deflection import (
    # 主入口
    compute_deflection,            # 纯内存计算
    run_measurement_pipeline,      # 文件读 + 算 + 文件写

    # 单步工具（高级用法）
    load_point_cloud,              # 读扫描点云
    read_cad_reference,            # 读 CAD
    load_roi_aabb,                 # 读 ROI JSON
    register_to_cad,               # ICP 配准
    bilateral_filter_points,       # 双边滤波
    apply_passthrough,             # AABB 过滤

    # 结果数据类
    DeflectionResult,
    SideDeflection,
    DeflectionCurves,
    RegistrationResult,

    # 异常
    DeflectionError,
    InvalidPointCloudError,
    InsufficientPointsError,
    UnsupportedFormatError,
    FrameInferenceError,

    # 版本
    __version__,
    ALGORITHM_VERSION,
    SCHEMA_VERSION,
)
```

详见 [`USAGE.md`](./USAGE.md)。

---

## 状态与版本

- **当前版本**：1.1.0
- **算法版本**：0.1.0（v1.1 没有动算法主流程，仅扩展 I/O / 预处理 / 配准）
- **Schema 版本**：1.0（v1.1 仅新增可选字段，向后兼容）
- **Python**：≥ 3.10（Windows / Linux / macOS 通用）

---

## License

Proprietary — PKU High-Speed Train Project.