201 lines
6.5 KiB
Markdown
201 lines
6.5 KiB
Markdown
# underframe-deflection
|
||
|
||
**从扫描点云测量高铁底架纵梁挠度的 Python 算法包：接受"CAD 基准 + 扫描点云 + ROI JSON"三件套输入，自动配准、去噪、识别梁、出 Excel 误差报表。**
|
||
|
||
[]() []() []()
|
||
|
||
---
|
||
|
||
## 这是什么
|
||
|
||
输入一份现场扫描点云（`.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.
|