lipan
cec0766e67
- 算法包替换为 delivery_v1.2（coupler_panel 新增 autotune/layer_select，underframe_deflection 新增 single_beam 管线），删除 delivery_v1.1 - manifests/adapters 的 PYTHONPATH 与版本说明同步更新到 v1.2 - 新增任务级 CAD 文件支持（task_cad_files 表、上传/读取路由、TaskManager 全选与加载显示） - 新增 train-measurement 自定义前端面板（YAML 编辑器 + 可视化 ROI 配置 + 3D 取点） - PointCloudViewer 支持 PLY 叠加层渲染与 ROI 拾取 - Dockerfile 改用 Miniforge 安装 pythonocc-core，修复 libgomp/libstdc++ 依赖
197 lines
6.7 KiB
Markdown
197 lines
6.7 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「Summary」（key/value）
|
||
|
||
| 字段 | 含义 |
|
||
| --- | --- |
|
||
| `mode` / `side` | `single_beam` / `left`、`right` |
|
||
| `input_cloud` / `roi_source` / `cad_reference` | 三个输入文件的绝对路径 |
|
||
| `registration_performed` / `registration_note` | 是否配准 + 说明 |
|
||
| `roi_point_count` | ROI 裁剪命中点数 |
|
||
| `n_slices` / `n_kept` | 沿车长切片数 / 鲁棒拟合保留的切片数 |
|
||
| `reference_slope_mm_per_m` | 拟合参考线斜率 |
|
||
| **`selected_signed_deflection_mm`** | **最大绝对挠度（带符号）← 核心结果** |
|
||
| `selected_absolute_deflection_mm` | 最大绝对挠度 |
|
||
| `selected_x_mm` | 该点的车长位置 |
|
||
| `max_downward_mm` / `max_upward_mm` | 最大下凹 / 上凸挠度 |
|
||
| `rms_mm` | 挠度 RMS |
|
||
| `quality_flags` | 质量警告（空 = 正常） |
|
||
|
||
### Sheet「Deflection_Curve」
|
||
|
||
沿车长逐点表：`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"，与单梁模式互不影响。
|