massive-cloud/alg/平整度、平面度、轮廓测量v1.5/Readme.md

# 测量工具

这是一个面向工业零件点云、网格和 CAD STEP 模型的几何测量工具。项目支持 CAD 转 STL、点云加噪/滤波、点云配准、点云到 Mesh/CAD 的距离评估、点云到 CAD 的仅平移对齐、曲率估计和平面拟合。

正式代码位于项目根目录，辅助脚本放在 `archive/`，示例数据放在 `datasets/`，打包工具放在 `packaging/`。推荐在项目根目录执行命令。

面向开发人员的完整使用说明见 [USAGE.md](USAGE.md)。

## 1. 项目结构

```text
.
  main.py                  # 命令行入口
  pipeline.py              # MeasurementPipeline，总流程入口类
  io_handler.py            # 输入检查、点云/Mesh/CAD 读取
  config_loader.py         # YAML 配置加载
  config.yaml              # 默认配置
  cad_converter.py         # STEP -> STL
  registration.py          # RANSAC + ICP 配准
  evaluation.py            # Chamfer、点云到 Mesh 距离、统计指标
  visualization.py         # Open3D 可视化
  preprocessing/           # 加噪、滤波、曲率、平面拟合
  datasets/                # 示例 CAD、Mesh、PointCloud、Noise_PointCloud
  vis/                     # 建议保存命令日志、可视化点云和中间结果
  results/                 # translate-align 默认输出目录
  archive/                 # 辅助脚本
  packaging/               # pip 打包文件夹
```

## 2. 环境安装

建议使用独立的 Python 3.10 环境。当前项目建议使用 `High-Speed` 环境运行，不要直接安装到 conda 的 `base` 环境。`pythonocc-core` 需要通过 conda 安装，`requirements.txt` 只管理 pip 依赖。

```bash
conda env create -n High-Speed -f environment.yml
conda activate High-Speed
pip install -r requirements.txt
pip install git+https://github.com/AutodeskAILab/occwl
```

如果已经创建过环境，需要补装或更新 CAD 转 Mesh 依赖：

```bash
conda env update -n High-Speed -f environment.yml
conda activate High-Speed
pip install git+https://github.com/AutodeskAILab/occwl
```

如果当前终端显示 `(base)`，并且 base 环境是 Python 3.12，直接安装 `pythonocc-core=7.5.1` 会失败；该版本只支持 Python 3.7 到 3.10。

验证环境：

```bash
python -c "import open3d, trimesh, torch, yaml, OCC.Core.STEPControl; print('env ok')"
```

如果日志里出现 CUDA driver 版本过旧的 warning，程序会退回 CPU 计算。当前配准流程本身主要使用 Open3D CPU 管线；点云到 Mesh/CAD 的距离计算使用 torch，理论上可用 GPU，但取决于 `torch.cuda.is_available()`。

## 3. 数据要求

默认数据目录结构如下：

```text
datasets/
  CAD/                 # STEP CAD 文件，示例：11.step、40.step
  Mesh/                # STL/OBJ/PLY Mesh 文件，示例：11.stl、40.stl
  PointCloud/          # 原始/干净点云 PLY，示例：11.ply、40.ply
  Noise_PointCloud/    # 加噪或待配准点云 PLY，示例：11_noisy.ply、40_noisy.ply
  shift_test_output/   # translate-align 测试点云目录，默认读取 shifted_whole_pointcloud.ply
```

当前批量评估示例数据包含编号 `11`、`13`、`17`、`20`、`22`、`23`、`25`、`26`、`27`、`31`、`34`、`35`、`36`、`37`、`38`、`39`、`40`、`41`、`42`、`45`，同一编号通常应同时存在：

```text
datasets/CAD/11.step
datasets/Mesh/11.stl
datasets/PointCloud/11.ply
datasets/Noise_PointCloud/11_noisy.ply
```

同一任务可以包含多个样本，样本名使用下划线后缀区分；例如 `13_1.stl` 和 `13_2.stl` 都归属任务 `13`，并分别匹配 `13_1_noisy.ply`、`13_2_noisy.ply`。

`translate-align` 默认使用：

```text
datasets/CAD/M02.stp  #标准CAD
datasets/shift_test_output/shifted_whole_pointcloud.ply  #实际采集点云
```

输入格式要求：

- CAD：推荐 STEP，扩展名通常为 `.step` 或 `.stp`。用于 `cad2mesh` 和 `contour`。
- Mesh：支持 `trimesh` 能读取的格式，常用 `.stl`、`.obj`、`.ply`。Mesh 必须包含顶点和三角面。
- PointCloud：推荐 ASCII 或 binary `.ply`，必须包含三维点坐标。曲率、配准、距离评估都需要非空点云。
- 路径：可以使用相对路径或绝对路径；相对路径按当前运行目录解析，建议在项目根目录执行。
- 单位：示例数据按毫米量级处理。CAD、Mesh 和点云必须使用同一坐标系和同一单位，否则距离、配准结果没有可比性。
- 对齐关系：`contour` 假设点云已经与 Mesh/CAD 在同一坐标系下；`registration` 会模拟旋转后做配准。

数据规模注意：

- 百万级点云可以运行，但 `registration` 和 `contour` 会比较慢。
- `evaluation.chunk_size` 控制点云分块大小。
- `evaluation.triangle_chunk_size` 控制 Mesh/CAD 三角面分块大小。内存或显存不足时调小，例如 `1024` 或 `2048`。
- `evaluation.cad_mesh_deflection` 控制 STEP 三角化精度。越小越精细，但三角面更多、计算更慢。

## 4. 输出说明

建议将通用实验结果放到 `vis/`，Excel 结果放到 `excel/`，`translate-align` 默认写入 `results/`：

```bash
mkdir -p vis excel results
```

常见输出包括：

- `.log`：命令行指标输出。
- `.time`：命令耗时记录。
- `.stl`：CAD 转 Mesh 结果。
- `.ply`：带颜色的点云结果，例如曲率点云或 CAD 距离热力图。
- `.xlsx`：`contour --excel-output` 生成的 Excel，默认保存到 `excel/contour.xlsx`；默认按 `excel/测量结果.xlsx` 模板迁移对应任务行，并写入本次测量均值和测量结论。
- `results/aligned_pointcloud_translation_only.ply`：`translate-align` 默认输出的对齐后点云。
- `results/T_translation_only.txt`：`translate-align` 默认输出的 4x4 平移矩阵。

本项目不会自动把所有命令结果写入 `vis/`；如果需要保留日志，可以用 shell 重定向：

```bash
python main.py contour --pointcloud datasets/PointCloud/11.ply --cad datasets/CAD/11.step --no-visualize > vis/contour.log 2>&1
```

## 5. 方法输入输出总览

| 方法 | 功能 | 输入 | 输出 |
|------|------|------|------|
| `cad2mesh` | 将 STEP CAD 转成 STL 三角网格 | `--cad`：STEP 文件 | `--mesh`：STL 文件 |
| `denoise` | 给干净点云加噪，并运行配置中的滤波方法 | `--pointcloud`：干净 PLY 点云；`--noise-std`：噪声标准差 | 终端输出点数、平均噪声偏移、滤波保留比例、Chamfer Distance；当前不自动保存滤波点云 |
| `registration` | 模拟旋转后进行点云到 Mesh 的配准，并评估配准后距离 | `--pointcloud`：待配准 PLY 点云；`--mesh`：参考 STL/OBJ/PLY Mesh | 终端输出 fitness、RMSE、变换矩阵、配准后点云到 Mesh 的距离统计 |
| `contour` | 轮廓/平整度/平面度评估，计算点云到 STEP CAD 三角面的距离 | 单任务：`--pointcloud` 和 `--cad`；批量：`--tasks` 或 `--all`，并指定 `--data-root`、`--pointcloud-kind` | 终端输出 Mean、Max、RMSE、Min、Std；可用 `--save` 保存热力图 PLY；可用 `--excel-output` 保存 Excel |
| `curvature` | 估计点云局部曲率并着色 | `--pointcloud`：PLY 点云；`--radius`：邻域半径；`--max-nn`：最大邻居数 | 终端输出曲率 mean/max；可用 `--save` 保存彩色曲率 PLY |
| `plane` | 使用 RANSAC 拟合平面 | 可选 `--pointcloud`：PLY 点云；不传则生成模拟带噪平面 | 终端输出平面模型、内点比例、法向角度误差、RMSE；可视化拟合结果 |
| `full` | 按配置串联运行加噪/滤波、配准和距离评估 | `--config`：YAML 配置文件；默认使用 `config.yaml` | 返回完整流程结果；终端输出各阶段指标；默认不自动执行 CAD 转 Mesh |

`contour --excel-output` 生成的 Excel 默认读取 `excel/测量结果.xlsx` 作为模板，按 `任务号` 迁移对应行，新表头保持模板一致：`任务号、项点名称、公差要求、理论尺寸、测量结果、误差结果、测量结论`。脚本只写入 `测量结果` 和 `测量结论`：测量结果填本次测量均值，测量成功填 `成功`，否则填 `失败`。`--excel-output` 不带值时保存为 `excel/contour.xlsx`；只传文件名时会自动保存到 `excel/` 文件夹。可用 `--result-template` 指定其它模板。

## 6. 快速使用

查看所有命令：

```bash
python main.py --help
```

查看某个命令参数：

```bash
python main.py registration --help
```

## 7. 常用命令
轮廓/平整度/平面度评估（全部数据）：

```bash
python main.py contour --all --data-root datasets --pointcloud-kind noise --save vis/contour --excel-output all_contour.xlsx --no-visualize
```

批量模式会优先从 `datasets/Mesh/{样本名}.stl` 读取 Mesh，并按样本名匹配点云。`--tasks 13` 会匹配 `13_1.stl`、`13_2.stl` 等同属任务 13 的样本；`--tasks 13_1` 只运行该样本。`--pointcloud-kind noise` 读取 `datasets/Noise_PointCloud/{样本名}_noisy.ply`；`--pointcloud-kind clean` 读取 `datasets/PointCloud/{样本名}.ply`。如果没有找到 Mesh 样本，则退回 `datasets/CAD/{任务号}.step`。批量模式下 `--save vis/contour` 会按样本名保存为 `vis/contour/{样本名}_contour.ply`，并按原始坐标额外保存合并点云 `vis/contour/combined_contour.ply`；未传 `--save` 时合并点云默认保存到 `vis/combined_contour.ply`。合并点云默认会加入完整点云 `datasets/train/train_2_10M.ply`，可用 `--combined-context-pointcloud datasets/train/train_2_100M.ply` 或 `datasets/train/train_2_1T_配准.ply` 切换；保存合并 PLY 时会按块流式读取大背景点云，不再整体加载进内存。Excel 会按任务号把模板中的对应行迁移到新表；批量模式会在终端最后打印总执行时间 `Contour batch total execution time`，该时间包含任务计算、Excel 保存和合并 PLY 保存。未传 `--no-visualize` 时，所有成功热力图会按原始坐标合并到一个 Open3D 窗口中展示。使用 `train_2_1T_配准.ply` 时必须加 `--no-visualize`，只保存合并结果，不打开窗口。

使用 `datasets/train/train_2_1T_配准.ply` 作为完整背景点云保存合并结果：
注意：使用时，利用combined-context-pointcloud指定配准后的点云路径

```bash
conda activate High-Speed
python main.py contour --all --data-root datasets --pointcloud-kind noise --save vis/contour --excel-output all_contour.xlsx --combined-context-pointcloud datasets/train/train_2_1T_配准.ply --no-visualize
```

CAD 转 Mesh：

```bash
python main.py cad2mesh --cad datasets/CAD/11.step --mesh vis/11_cad2mesh.stl --precision 1.0
```

加噪与去噪：

```bash
python main.py denoise --pointcloud datasets/PointCloud/11.ply --noise-std 4 --no-visualize
```

点云配准与 Mesh 距离评估：

```bash
python main.py registration --pointcloud datasets/Noise_PointCloud/11_noisy.ply --mesh datasets/Mesh/11.stl --no-visualize
```

轮廓/平整度/平面度评估（快速查看统计结果）：

```bash
python main.py contour --pointcloud datasets/PointCloud/11.ply --cad datasets/CAD/11.step --no-visualize
```

轮廓/平整度/平面度评估（保存热力图和 Excel）：

```bash
python main.py contour --cad datasets/CAD/11.step --pointcloud datasets/Noise_PointCloud/11_noisy.ply --save vis/11_contour.ply --excel-output --no-visualize
```

`contour` 是轮廓/平整度/平面度评估的统一入口：不加导出参数时适合快速在命令行查看统计结果；添加 `--save` 时会保存距离热力图 PLY；添加 `--excel-output` 时会把统计结果保存到 `excel/contour.xlsx`。也可以写成 `--excel-output 11_contour.xlsx`，结果会保存到 `excel/11_contour.xlsx`。Excel 默认使用 `excel/测量结果.xlsx` 模板，可通过 `--result-template` 替换。

轮廓/平整度/平面度评估（指定多个数据）：

```bash
python main.py contour --tasks 13,31,40 --data-root datasets --pointcloud-kind noise --save vis/contour --excel-output selected_contour.xlsx --no-visualize
```

曲率估计：

```bash
python main.py curvature --pointcloud datasets/PointCloud/11.ply --radius 2 --max-nn 30 --save vis/11_curvature.ply --no-visualize
```

平面拟合：

```bash
python main.py plane --no-visualize
```

完整流程：

```bash
python main.py --config config.yaml full --no-visualize
```

`full` 会按配置串联加噪/滤波、配准和距离评估。默认 `cad.enabled: false`，不会自动执行 CAD 转 Mesh。

## 8. 打包使用

生成独立 Python 包源码：

```bash
python packaging/build_package.py
```

本地开发安装：

```bash
pip install -e packaging/build
geometry-measure --help
```

构建 wheel：

```bash
pip install build
python packaging/build_package.py
python -m build packaging/build
```

打包说明见 [packaging/README.md](packaging/README.md)。

## 9. 输入不同数据

方式一：命令行覆盖路径。

点云配准：

```bash
python main.py registration \
  --pointcloud datasets/Noise_PointCloud/40_noisy.ply \
  --mesh datasets/Mesh/40.stl \
  --no-visualize
```

单个数据快速评估：

```bash
python main.py contour \
  --pointcloud datasets/PointCloud/40.ply \
  --cad datasets/CAD/40.step \
  --no-visualize
```

单个数据保存热力图和 Excel：

```bash
python main.py contour \
  --cad datasets/CAD/40.step \
  --pointcloud datasets/Noise_PointCloud/40_noisy.ply \
  --save vis/40_contour.ply \
  --excel-output 40_contour.xlsx \
  --no-visualize
```

指定多个数据批量评估：

```bash
python main.py contour \
  --tasks 13,31,40 \
  --data-root datasets \
  --pointcloud-kind noise \
  --save vis/contour \
  --excel-output selected_contour.xlsx \
  --no-visualize
```

全部数据批量评估：

```bash
python main.py contour \
  --all \
  --data-root datasets \
  --pointcloud-kind noise \
  --save vis/contour \
  --excel-output all_contour.xlsx \
  --no-visualize
```

方式二：修改 `config.yaml`。

```yaml
paths:
  cad: datasets/CAD/40.step
  mesh: datasets/Mesh/40.stl
  pointcloud: datasets/PointCloud/40.ply
  noisy_pointcloud: datasets/Noise_PointCloud/40_noisy.ply
  output_mesh: vis/40_cad2mesh.stl
  curvature_output: vis/40_curvature.ply
```

然后运行：

```bash
python main.py --config config.yaml full --no-visualize
```

## 10. 参数配置

常用参数都在 `config.yaml`：

- `noise.std`：高斯噪声标准差。
- `filters.methods`：启用哪些滤波器。
- `registration.voxel_size`：配准下采样体素大小。
- `registration.roll/pitch/yaw`：模拟旋转角度。
- `registration.trans_range`：模拟平移范围。
- `evaluation.chunk_size`：点云到 Mesh 距离分块大小。
- `evaluation.triangle_chunk_size`：距离计算时三角面分块大小，显存/内存不足时调小。
- `evaluation.cad_mesh_deflection`：STEP CAD 三角化精度，越小越精细但越慢。
- `visualization.enabled`：是否默认开启可视化。

命令行参数优先级高于配置文件。

## 11. 命令说明

### 11.1 `translate-align`

- 用途：将 `archive/translate_align_pointcloud_to_cad.py` 接入统一入口，按车头/车尾局部点的质心差估计整体平移，只修正平移，不修正旋转。
- 默认输入：`--cad datasets/CAD/M02.stp --pointcloud datasets/shift_test_output/`。当 `--pointcloud` 传目录时，会优先读取目录下的 `shifted_whole_pointcloud.ply`。
- 默认输出目录：`results/`。
- 常用调参：`--axis` 指定车辆长度方向；`--crop-ratio` 控制头尾截取比例；`--cad-sample-points` 控制从 CAD mesh 采样的点数；`--local-sample-points` 控制头尾局部用于算质心的采样点数；`--scale-pointcloud` 用于 CAD 与点云单位不一致时缩放点云。
- 输出文件：

```text
results/aligned_pointcloud_translation_only.ply  # 最终配准后的完整点云
results/T_translation_only.txt                   # 4x4 平移矩阵，可复用到其它点云或评估流程
results/cad_sampled.ply                          # 从 CAD mesh 采样得到的 CAD 点云
results/cad_front_sample.ply                     # CAD 车头区域采样点，用于检查质心计算
results/cad_tail_sample.ply                      # CAD 车尾区域采样点，用于检查质心计算
results/source_front_sample.ply                  # 输入点云车头区域采样点，用于检查质心计算
results/source_tail_sample.ply                   # 输入点云车尾区域采样点，用于检查质心计算
```

- 终端输出：前端/后端质心、前端平移量 `t_front`、后端平移量 `t_tail`、二者差值、最终融合平移 `t_final` 和最终矩阵 `T_final`。如果前后端平移差值较大，通常说明点云和 CAD 存在旋转误差、裁剪区域不合适或单位不一致。
- 示例：

```bash
python main.py translate-align --cad datasets/CAD/M02.stp --pointcloud datasets/shift_test_output/ --output-dir results --axis x --crop-ratio 0.01 --no-visualize
```

也可以直接运行辅助脚本：

```bash
python archive/translate_align_pointcloud_to_cad.py -c datasets/CAD/M02.stp -p datasets/shift_test_output/ -o results --no_visualize
```

### 11.2 `cad2mesh`

- 输入：STEP 文件。
- 输出：STL 文件。
- 依赖：`pythonocc-core`。
- 典型用途：将 CAD 转成后续可用于 Mesh 距离评估的三角网格。

### 11.3 `denoise`

- 输入：干净点云。
- 输出：终端指标；当前不会自动保存滤波后的点云。
- 指标：点数、平均噪声偏移、滤波保留比例、Chamfer Distance。

### 11.4 `registration`

- 输入：点云和参考 Mesh。
- 输出：配准 fitness、RMSE、变换矩阵、配准后点云到 Mesh 距离统计。
- 注意：百万级点云可能耗时较长；当前 Open3D 配准部分主要走 CPU。

### 11.5 `contour`

- 用途：轮廓/平整度/平面度评估的统一入口。
- 输入：单任务使用点云和 STEP CAD；批量任务使用 `--tasks` 或 `--all` 从 `--data-root` 中读取多组 CAD/点云；如果显式传 `--mesh`，会走点云到 Mesh 距离计算。
- 输出：命令行打印点云到 CAD 三角面的 Mean、Max、RMSE、Min、Std；可通过 `--save` 保存距离热力图 PLY，可通过 `--excel-output` 保存 Excel。
- 注意：这是全量点到三角面的距离计算，数据越大越慢；STEP 三角化精度由 `--mesh-deflection` 控制。
- 常用调参：`--mesh-deflection`、`--point-chunk-size`、`--triangle-chunk-size`。
- 批量参数：`--tasks 13,31,40` 执行指定任务，其中 `13` 会自动展开 `13_1`、`13_2` 等样本；`--tasks 13_1` 只执行单个样本；`--all` 优先执行 `--data-root/Mesh` 下全部样本，没有 Mesh 时退回 CAD；`--pointcloud-kind noise|clean` 选择加噪点云或干净点云。
- 批量热力图：`--save vis/contour` 会为每个任务生成一个 PLY，并保存合并点云 `vis/contour/combined_contour.ply`；也可以用 `--save vis/{task_id}_contour.ply` 自定义文件名模板，合并点云会保存为 `vis/combined_contour.ply`。未传 `--save` 时，合并点云默认保存为 `vis/combined_contour.ply`。合并点云默认包含完整点云 `datasets/train/train_2_10M.ply`，可用 `--combined-context-pointcloud` 切换为 `train_2_100M.ply` 或 `train_2_1T_配准.ply`；保存合并 PLY 时大背景点云会流式写入，输出文件会因为追加 RGB 颜色而比原始背景点云更大。
- 批量可视化：未传 `--no-visualize` 时，所有成功执行的热力图会按原始坐标合并到一个窗口展示，不会为了展示改变点云位置。使用 `train_2_1T_配准.ply` 时必须传 `--no-visualize`，不要打开 Open3D 窗口。
- Excel 输出：`--excel-output` 不带值时保存为 `excel/contour.xlsx`；只传文件名时自动保存到 `excel/` 文件夹。默认读取 `excel/测量结果.xlsx` 作为模板，按 `任务号` 迁移对应行，表头保持模板一致，只写入 `测量结果` 和 `测量结论`。可用 `--result-template` 指定其它模板。

### 11.6 `archive/Contour_Flatness.py`

- 默认批量模式：优先从 `Mesh/{样本名}.stl` 和 `Noise_PointCloud/{样本名}_noisy.ply` 读取样本；例如 `13_1.stl`、`13_2.stl` 都归属任务 `13`，Excel 会按任务号汇总。
- 单任务模式：加 `--single` 后使用 `--CAD/-c` 和 `--pointcloud/-p`，可加 `--visualize` 显示距离热力图；批量模式加 `--visualize` 会把所有成功热力图合并到一个窗口展示。使用 `datasets/train/train_2_1T_配准.ply` 作为 `--combined_context_pointcloud` 时不要加 `--visualize`。
- 距离计算：默认参考 `archive/test8.py`，先用点到三角形 AABB 的距离筛出每个点附近的候选三角面，再计算精确点到三角形距离；`--candidate_triangle_count 0` 可退回全量精确搜索。
- Excel 输出：默认读取 `excel/测量结果.xlsx` 作为模板，按 `任务号` 迁移对应行，新表头保持模板一致：`任务号、项点名称、公差要求、理论尺寸、测量结果、误差结果、测量结论`。脚本只写入 `测量结果` 和 `测量结论`：测量结果填本次测量均值，测量成功填 `成功`，否则填 `失败`。可用 `--result_template` 指定其它模板。
- 示例：

```bash
python archive/Contour_Flatness.py --tasks "13,31,40" --data_root datasets --pointcloud_kind noise --excel_output vis/flatness.xlsx --result_template excel/测量结果.xlsx --candidate_triangle_count 32
python archive/Contour_Flatness.py --single -c High_Speed_Data/CAD/11.step -p High_Speed_Data/Noise_PointCloud/11_noisy.ply --candidate_triangle_count 32 --visualize
```

### 11.7 `curvature`

- 输入：点云。
- 输出：曲率 mean/max；可通过 `--save` 保存彩色曲率点云。

### 11.8 `plane`

- 输入：可选点云；不传点云时会生成一块带噪平面用于测试。
- 输出：平面模型、内点比例、法向角度误差、RMSE。

## 12. 常见问题

`No module named OCC`：

说明 CAD 依赖没有装好。执行：

```bash
conda env update -n High-Speed -f environment.yml
```

`pythonocc-core` 无法通过 pip 安装：

这是正常的，`pythonocc-core` 应通过 conda 安装。不要把它放进 `requirements.txt`。

`pythonocc-core=7.5.1` 和 Python 3.12 冲突：

新建 Python 3.10 环境，不要在 base 里安装。

`registration` 或 `contour` 很慢：

这是因为示例点云超过百万点，且距离计算要比较大量三角面。可以先换小点云测试，或者调小点数、增大 `registration.voxel_size`、调小 `evaluation.chunk_size`/`triangle_chunk_size` 以降低内存压力。

CUDA warning：

如果 torch 提示 NVIDIA driver 太旧，距离计算会退回 CPU。功能不受影响，但速度会慢。