massive-cloud/alg/delivery_v1.2.1/coupler_panel_release/README.md

coupler-panel-validation

高铁车钩面板偏转角测量算法。输入待测点云 + ROI + 理论 CAD，输出面板相对车体纵轴的两个方向偏转角及最大偏差，并生成 Excel 报表。

这个项目做什么

给定一块车钩安装面板的扫描点云，算法测量它相对理论安装姿态的偏转：

• θ_right —— 面板法向在一个方向上的偏转角（度）
• θ_ref —— 面板法向在另一个方向上的偏转角（度）
• dx_y_max / dx_z_max —— 由偏转引起的最大 x 向偏差（mm）

支持两种输入规模：

• 单零件点云（对零件 STP 采样得到的稠密点云）
• 整车扫描点云（GB 级 PLY，用 ROI 框出车钩区域后内部流式裁剪）

三件套输入（集成主路径）

输入	说明
ROI JSON	6 个数的轴对齐包围盒，框出待测面板区域（即裁剪超参数）
点云 PLY	待测点云，可为整车（多 GB），算法内部按 ROI 流式裁剪
CAD STP	理论模型，作辅助 / 审计

输出：eval_report.xlsx（含两个偏转角的 GT / 预测 / 误差 + 中间量 + 运行时间）。

快速开始

# 安装（锁定版本见 requirements.txt）
python -m pip install -r requirements.txt
pip install -e ".[all]"

# 三件套集成入口
python examples/run_integration.py \
    --roi   examples/roi_train2_coupler.json \
    --cloud /path/to/train_2_1T.ply \
    --stp   /path/to/asm.stp \
    --out   runs/train2 \
    --profile train2_coupler

库调用：

from coupler_panel.pipeline import run_coupler_measurement_pipeline
from coupler_panel.roi_select import load_roi_json

result = run_coupler_measurement_pipeline(
    input_cloud = "train_2_1T.ply",
    out_dir     = "runs/train2",
    profile     = "train2_coupler",
    roi_spec    = load_roi_json("roi_train2_coupler.json"),
)
print(result.theta_right_deg, result.theta_ref_deg)

文档

文档	内容
USAGE.md	集成方使用指南 —— 三件套输入、API、ROI JSON、profile、输出、坐标系
CHANGES.md	修改记录 —— 每轮改了什么、为什么、遇到的问题与定位解决

坐标系约定

• 算法以面板法向 n=(n_x,n_y,n_z) 相对 x 轴的夹角定义偏转，强制 n_x>0。
• 坐标轴含义由数据集决定：项目标称约定为 x=纵向、y=宽度、z=高度；但某些整车数据集为 x=车长、y=车高、z=车宽（y/z 对调）。偏转角公式对称、理论 0 不受影响，但 D_y_max/D_z_max 对应的物理轴随之对调。ROI JSON 的六个边界必须与点云自身坐标系一致。详见 USAGE.md。