massive-cloud/alg/delivery_v1.2.1/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「检测报表」（核心交付，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。

---

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