lipan
29f1d45d66
算法更新: delivery v1.2.1、平整度v1.5、测距v2.2、整车配准v1.3 适配器: vehicle-registration 新增、各算法 manifest 和 adapter 更新 后端: taskCadFiles/source 字段迁移、derivedPointClouds 注册、取消任务联动 前端: ElapsedTime 时长显示、两步算法流程、canRun 逻辑修复 文档: 新增5份算法性能分析报告
201 lines
7.0 KiB
Markdown
201 lines
7.0 KiB
Markdown
# underframe_deflection 使用指南
|
||
|
||
> 面向软件集成方。说明如何用「**待测整车点云 + 理论 CAD（stp）+ ROI JSON**」三件套输入，
|
||
> 调用算法，得到含挠度核心数据的 Excel 输出。
|
||
|
||
---
|
||
|
||
## 1. 输入与输出
|
||
|
||
### 输入（集成方提供）
|
||
|
||
| 文件 | 格式 | 必需 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| **待测整车点云** | `.ply`（ASCII 或 binary） | ✅ | 现场扫描的整车点云。支持超大文件（实测 12GB / 10 亿点，流式裁剪不爆内存） |
|
||
| **理论 CAD** | `.stp` | ✅（按需用） | 理论模型。**当前实例点云已配准**，CAD 仅记录路径作溯源；需重新配准时见 §4 |
|
||
| **ROI JSON** | `.json` | ✅ | 每根梁一个，描述该梁的轴对齐裁剪框（AABB） |
|
||
|
||
> 左右梁是**两次独立调用**：左梁一个 ROI → 一份输出；右梁一个 ROI → 一份输出。
|
||
|
||
### 输出（左右各一份）
|
||
|
||
```
|
||
out_dir/
|
||
├── left/
|
||
│ ├── report.xlsx ← 挠度核心数据 Excel（Summary + Deflection_Curve）
|
||
│ ├── report.json ← 完整结果（机器读）
|
||
│ ├── deflection_curve.csv ← 沿车长的逐点挠度
|
||
│ └── deflection_curve.png ← 诊断图
|
||
├── right/ ← 同上结构
|
||
└── summary.json ← 左右汇总
|
||
```
|
||
|
||
---
|
||
|
||
## 2. ROI JSON 格式
|
||
|
||
坐标系：**x = 车长（纵向），y = 车高（挠度方向），z = 车宽（横向）**，单位 mm。
|
||
|
||
```json
|
||
{
|
||
"x_min": -100000.0,
|
||
"x_max": 100000.0,
|
||
"y_min": 919.950,
|
||
"y_max": 1399.950,
|
||
"z_min": 948.623,
|
||
"z_max": 1752.212
|
||
}
|
||
```
|
||
|
||
- `x` 给一个覆盖整车长度的大区间即可。
|
||
- `y`（车高）框住梁所在的高度带。
|
||
- `z`（车宽）分左右：左梁取正侧，右梁取负侧。
|
||
- 仓库 `test_data/roi_left_beam.json` / `roi_right_beam.json` 是可直接用的样例。
|
||
|
||
约束：每轴 `min < max`，均为有限实数；非法 → `InvalidPointCloudError`。
|
||
|
||
---
|
||
|
||
## 3. 调用方式
|
||
|
||
### 3.1 命令行
|
||
|
||
```bash
|
||
underframe-measure \
|
||
--input-cloud train.ply \
|
||
--left-roi roi_left_beam.json \
|
||
--right-roi roi_right_beam.json \
|
||
--cad theoretical.stp \
|
||
--out-dir out/
|
||
```
|
||
|
||
默认 `--mode single`、默认**不配准**（点云已配准），`--cad` 的 stp 路径记录进报告。
|
||
|
||
可选开关：`--enable-registration`（§4）、`--config FILE.json`（覆盖参数）、
|
||
`--skip-excel`、`--skip-plot`、`--side left|right`（配 `--roi` 单根时用）。
|
||
|
||
### 3.2 Python API（推荐集成）
|
||
|
||
```python
|
||
from underframe_deflection import run_both_beams
|
||
|
||
summary = run_both_beams(
|
||
input_cloud="train.ply",
|
||
left_roi="roi_left_beam.json",
|
||
right_roi="roi_right_beam.json",
|
||
out_dir="out/",
|
||
cad_path="theoretical.stp", # 记录路径；配准默认关
|
||
enable_registration=False, # 见 §4
|
||
)
|
||
|
||
for side in ("left", "right"):
|
||
d = summary[side]["deflection"]
|
||
print(side,
|
||
"最大挠度(带符号) =", d["selected_signed_mm"], "mm",
|
||
"@ x =", d["selected_x_mm"], "mm",
|
||
"| RMS =", d["rms_mm"], "mm")
|
||
```
|
||
|
||
单根梁独立调用：
|
||
|
||
```python
|
||
from underframe_deflection import run_single_beam_pipeline
|
||
|
||
report = run_single_beam_pipeline(
|
||
input_cloud="train.ply",
|
||
roi_path="roi_left_beam.json",
|
||
out_dir="out/left",
|
||
side="left",
|
||
cad_path="theoretical.stp",
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 配准开关
|
||
|
||
挠度测量的完整物理流程：**扫描点云 → 用 CAD 配准到标准姿态 → 测梁下表面相对理想基准的偏差**。
|
||
配准消除安装 / 摆放 / 扫描姿态引入的整体倾斜。
|
||
|
||
| `enable_registration` | 行为 | 适用 |
|
||
| --- | --- | --- |
|
||
| `False`（默认） | 不配准，点云按原样裁剪测量 | **点云已预配准**（本实例） |
|
||
| `True` | 先把整车点云刚性对齐到 CAD，再裁剪测量 | 点云未配准 |
|
||
|
||
配准开启时对 CAD 的要求：
|
||
- 必须是**可读的点云 / 网格**（`.ply / .xyz / .stl / .obj`）。
|
||
- `.stp` **不直接解析**（STEP 解析需重型依赖）。若只有 stp，先用
|
||
`tools/cad_sampling/step_to_pointcloud.py` 离线采样成 `.ply` 再传 `--cad`。
|
||
- 传 stp + 开配准时**不会崩溃**，而是记录提示"STEP not parsed; convert first"并跳过配准。
|
||
|
||
> 本次交付的测试样本点云**已配准**，所以默认关。配准算法（ICP）已完整保留，随时可启用。
|
||
|
||
---
|
||
|
||
## 5. 输出 Excel（report.xlsx，左右各一份）
|
||
|
||
### Sheet「检测报表」（核心交付，6 列）
|
||
|
||
| 列 | 本项目取值 |
|
||
| --- | --- |
|
||
| 项点名称 | 纵向梁到直线的垂直偏差（挠度） |
|
||
| 理论尺寸 | 0 |
|
||
| 公差要求 | 左梁 ±7mm / 右梁 ±12mm |
|
||
| 测量结果 | 实测最大挠度（mm） |
|
||
| 误差结果 | 与理论 0 的误差（= 测量结果，因理论值为 0） |
|
||
| 测量结论 | 误差 ≤ 公差 → **合格**，否则 → **不合格** |
|
||
|
||
**左右判定**：面朝 x 正方向，`z > 0` 为左梁（公差 7mm），`z < 0` 为右梁（公差 12mm）。
|
||
程序按 ROI 的 z 中心**自动判定**，不依赖文件名——即使左右 ROI 文件传反也不会用错公差。
|
||
|
||
公差可覆盖：命令行 `--left-tolerance` / `--right-tolerance`（两梁模式）或 `--tolerance`（单梁模式）；
|
||
Python API 同名参数 `left_tolerance_mm` / `right_tolerance_mm` / `tolerance_mm`。
|
||
|
||
### Sheet「明细」（溯源，key/value）
|
||
|
||
输入文件路径、是否配准、ROI 命中点数、切片数、参考线斜率、最大下凹/上凸、RMS、质量警告等。
|
||
|
||
### Sheet「挠度曲线」
|
||
|
||
沿车长逐点表：`x_mm, underside_height_mm, reference_height_mm, deflection_mm, kept`。
|
||
|
||
---
|
||
|
||
## 6. 异常与质量标记
|
||
|
||
| 异常 | 触发 |
|
||
| --- | --- |
|
||
| `InvalidPointCloudError` | 点云 / ROI 格式非法、AABB 反转 |
|
||
| `InsufficientPointsError` | ROI 命中点过少（< 2000） |
|
||
|
||
非致命质量标记（写进 `quality_flags`，不抛异常）：
|
||
`many_underside_spikes`（悬挂物/噪点偏多，已鲁棒剔除）、`low_surface_support`（下表面支撑点偏少）、
|
||
`insufficient_valid_slices` / `fit_unstable`（有效切片不足）。
|
||
|
||
集成方建议：外层 `try / except DeflectionError` 兜底，并把 `quality_flags` 落日志。
|
||
|
||
---
|
||
|
||
## 7. 算法原理
|
||
|
||
沿车长（x）分细切片 → 每片取**下表面主平面高度**（下半部直方图主峰，对悬挂物 / 噪点鲁棒）→
|
||
鲁棒拟合一条直线作理论基准 → 挠度 = 下表面高度 − 基准线。理论平直的梁，挠度 ≈ 0。
|
||
|
||
> 设计与验证的完整记录见 [`DEV_NOTES.md`](./DEV_NOTES.md)。
|
||
|
||
---
|
||
|
||
## 附录：双梁模式（legacy）
|
||
|
||
输入一片含左右两梁的车底点云 + CAD 基准 + ROI，自动配准 + 双梁追踪 + 样条拟合 + 孔参考线。
|
||
|
||
```bash
|
||
underframe-measure --mode dual \
|
||
--input-cloud scan.ply --cad reference.ply --roi roi.json \
|
||
--out-dir out/ --input-axis y_up
|
||
```
|
||
|
||
- `--input-axis {y_up,z_up}`：高度轴约定，默认 `y_up`（CAD/扫描约定 y=高度）。
|
||
- 输出 5-sheet Excel + 5 PNG + 4 PLY 叠加图。
|
||
- 该模式针对"双梁车底slab"，与单梁模式互不影响。
|