underframe-deflection
从扫描点云测量高铁底架纵梁挠度的 Python 算法包：接受"CAD 基准 + 扫描点云 + ROI JSON"三件套输入，自动配准、去噪、识别梁、出 Excel 误差报表。
这是什么
输入一份现场扫描点云（.ply / .xyz），一份 CAD 基准（.ply / .stl / .obj），一份描述测量区域的 ROI JSON，本包会：
- 去噪：passthrough → 统计离群 → 半径离群 → 双边滤波 → 体素降采样
- 配准：用 ICP 把扫描点云刚性对齐到 CAD 坐标系
- 识别梁：沿车长切片、Beam-search 跟踪左右纵梁
- 拟合：鲁棒样条拟合代表线
- 找参考：基于车体孔特征或线端点定参考线
- 算挠度：沿 X 轴逐点计算并选出绝对值最大的测量点
输出：完整 JSON 报告、Excel 误差报表（5 sheet）、沿 X 的挠度 CSV、候选切片诊断 CSV、5 张诊断 PNG、4 个着色 PLY 叠加图。
安装
# 进入本目录后
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。
上手
underframe-measure \
--input-cloud scan.ply \
--cad reference.ply \
--roi roi.json \
--out-dir out/
或者 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/ 自带可直接运行的样例：
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
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。
状态与版本
- 当前版本：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.