# underframe-deflection

**高铁底架纵梁挠度测量算法（基于点云）。** 输入待测点云 + 理论 CAD + ROI，输出含挠度核心数据的 Excel。

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

---

## 这是什么

两种测量模式：

- **单梁模式（默认）** — ROI 已框住单根纵梁（左右各一个 ROI），裁剪后直接测量。
  支持流式裁剪超大点云（实测 12GB / 10 亿点整车 PLY），左右各出一份 Excel。**这是当前交付的主模式。**
- **双梁模式（`--mode dual`）** — 一片含左右两梁的车底点云 + CAD 配准 + 双梁追踪（v1.1 算法，保留）。

原理（单梁）：沿车长切片 → 每片取下表面主平面高度 → 鲁棒拟合直线作理论基准 → 挠度 = 下表面 − 基准。
理论平直的梁，挠度 ≈ 0。

---

## 快速开始

```bash
pip install -e .[all]

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

→ `out/left/report.xlsx` 和 `out/right/report.xlsx`（左右各一份独立结果）。

`test_data/roi_left_beam.json` / `roi_right_beam.json` 是可直接用的样例 ROI。

---

## 文档

| 文档 | 面向 | 内容 |
| --- | --- | --- |
| **README.md**（本文件） | 所有人 | 项目总览、快速开始 |
| **[USAGE.md](./USAGE.md)** | 集成开发者 | 输入三件套、调用方式、输出 Excel 字段、配准开关、异常 |
| **[DEV_NOTES.md](./DEV_NOTES.md)** | 维护者 | 本次修改记录：改了什么、为什么、遇到什么问题、怎么解决 |

---

## 坐标系约定

`x = 车长（纵向）`，`y = 车高（挠度方向）`，`z = 车宽（横向）`，单位 mm。
ROI JSON 的 bbox 字段用同一坐标系。详见 USAGE.md。

---

## 安装

```bash
pip install -e .[all]      # core + matplotlib(图) + openpyxl(Excel)
pip install -e .           # 仅核心 numpy + scipy
```

安装后注册命令 `underframe-measure`，Python 内 `import underframe_deflection`。

---

## 状态与版本

- **当前版本**：1.2.0（单梁直接测量模式 + 流式裁剪超大点云）
- **Python**：≥ 3.10（Windows / Linux / macOS）
- License：Proprietary — PKU High-Speed Train Project