massive-cloud/alg/delivery_v1.2/underframe_deflection/USAGE.md

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。

{
  "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 命令行

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（推荐集成）

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")

单根梁独立调用：

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。

---

附录：双梁模式（legacy）

输入一片含左右两梁的车底点云 + CAD 基准 + ROI，自动配准 + 双梁追踪 + 样条拟合 + 孔参考线。

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"，与单梁模式互不影响。