feat: initial commit - massive-cloud point cloud processing system
This commit is contained in:
200
alg/delivery_v1.1/underframe_deflection/README.md
Normal file
200
alg/delivery_v1.1/underframe_deflection/README.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user