455 lines
19 KiB
Markdown
455 lines
19 KiB
Markdown
# 测量工具
|
||
|
||
这是一个面向工业零件点云、网格和 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 环境，不要直接安装到 conda 的 `base` 环境。`pythonocc-core` 需要通过 conda 安装，`requirements.txt` 只管理 pip 依赖。
|
||
|
||
```bash
|
||
conda env create -f environment.yml
|
||
conda activate point-porj
|
||
pip install -r requirements.txt
|
||
pip install git+https://github.com/AutodeskAILab/occwl
|
||
```
|
||
|
||
如果已经创建过环境，需要补装或更新 CAD 转 Mesh 依赖：
|
||
|
||
```bash
|
||
conda env update -n point-porj -f environment.yml
|
||
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`、`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
|
||
```
|
||
|
||
`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`。
|
||
- `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. 方法输入输出总览
|
||
|
||
| 方法 | 功能 | 输入 | 输出 |
|
||
|------|------|------|------|
|
||
| `translate-align` | 按车头/车尾质心将点云与标准CAD进行配准 | 默认 `--cad datasets/CAD/M02.stp --pointcloud datasets/shift_test_output/`；可调 `--axis`、`--crop-ratio`、`--cad-sample-points`、`--local-sample-points` | 默认写入 `results/`，输出对齐后点云 `aligned_pointcloud_translation_only.ply`、变换矩阵 `T_translation_only.txt` 和局部采样检查文件 |
|
||
| `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-output` 不带值时保存为 `excel/contour.xlsx`；只传文件名时会自动保存到 `excel/` 文件夹。
|
||
|
||
## 6. 快速使用
|
||
|
||
查看所有命令：
|
||
|
||
```bash
|
||
python main.py --help
|
||
```
|
||
|
||
查看某个命令参数：
|
||
|
||
```bash
|
||
python main.py registration --help
|
||
```
|
||
|
||
## 7. 常用命令
|
||
|
||
点云到 CAD 的配准：
|
||
|
||
```bash
|
||
python main.py translate-align --cad datasets/CAD/M02.stp --pointcloud datasets/shift_test_output/ --output-dir results --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 只包含四列：任务号、最大值、平均值、状态。
|
||
|
||
轮廓/平整度/平面度评估（指定多个数据）：
|
||
|
||
```bash
|
||
python main.py contour --tasks 11,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
|
||
```
|
||
|
||
批量模式会从 `datasets/CAD/{任务号}.step` 读取 CAD。`--pointcloud-kind noise` 会读取 `datasets/Noise_PointCloud/{任务号}_noisy.ply`；`--pointcloud-kind clean` 会读取 `datasets/PointCloud/{任务号}.ply`。批量模式下 `--save vis/contour` 会按任务号保存为 `vis/contour/{任务号}_contour.ply`，Excel 每个任务一行。
|
||
|
||
曲率估计：
|
||
|
||
```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 11,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 11,31,40` 执行指定任务；`--all` 执行 `--data-root` 下全部 CAD；`--pointcloud-kind noise|clean` 选择加噪点云或干净点云。
|
||
- 批量热力图：`--save vis/contour` 会为每个任务生成一个 PLY；也可以用 `--save vis/{task_id}_contour.ply` 自定义文件名模板。
|
||
- Excel 输出：`--excel-output` 不带值时保存为 `excel/contour.xlsx`；只传文件名时自动保存到 `excel/` 文件夹。表格列为任务号、最大值、平均值、状态。
|
||
|
||
### 11.6 `archive/Contour_Flatness.py`
|
||
|
||
- 默认批量模式：从 `High_Speed_Data/CAD/{id}.step` 和 `High_Speed_Data/Noise_PointCloud/{id}_noisy.ply` 读取任务，输出 Excel 汇总。
|
||
- 单任务模式：加 `--single` 后使用 `--CAD/-c` 和 `--pointcloud/-p`，可加 `--visualize` 显示距离热力图。
|
||
- 示例：
|
||
|
||
```bash
|
||
python archive/Contour_Flatness.py --tasks "11,31,40" --data_root High_Speed_Data --excel_output vis/flatness.xlsx
|
||
python archive/Contour_Flatness.py --single -c High_Speed_Data/CAD/11.step -p High_Speed_Data/Noise_PointCloud/11_noisy.ply --visualize
|
||
```
|
||
|
||
### 11.7 `curvature`
|
||
|
||
- 输入：点云。
|
||
- 输出：曲率 mean/max；可通过 `--save` 保存彩色曲率点云。
|
||
|
||
### 11.8 `plane`
|
||
|
||
- 输入：可选点云；不传点云时会生成一块带噪平面用于测试。
|
||
- 输出：平面模型、内点比例、法向角度误差、RMSE。
|
||
|
||
## 12. 常见问题
|
||
|
||
`No module named OCC`：
|
||
|
||
说明 CAD 依赖没有装好。执行：
|
||
|
||
```bash
|
||
conda env update -n point-porj -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。功能不受影响，但速度会慢。
|