massive-cloud/alg/point_porj/Readme.md

测量工具

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

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

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

1. 项目结构

.
  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 依赖。

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 依赖：

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。

验证环境：

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. 数据要求

默认数据目录结构如下：

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，同一编号通常应同时存在：

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

translate-align 默认使用：

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/：

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 重定向：

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. 快速使用

查看所有命令：

python main.py --help

查看某个命令参数：

python main.py registration --help

7. 常用命令

点云到 CAD 的配准：

python main.py translate-align --cad datasets/CAD/M02.stp --pointcloud datasets/shift_test_output/ --output-dir results --no-visualize

CAD 转 Mesh：

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

加噪与去噪：

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

点云配准与 Mesh 距离评估：

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

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

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

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

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 只包含四列：任务号、最大值、平均值、状态。

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

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

轮廓/平整度/平面度评估（全部数据）：

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 每个任务一行。

曲率估计：

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

平面拟合：

python main.py plane --no-visualize

完整流程：

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

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

8. 打包使用

生成独立 Python 包源码：

python packaging/build_package.py

本地开发安装：

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

构建 wheel：

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

打包说明见 packaging/README.md。

9. 输入不同数据

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

点云配准：

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

单个数据快速评估：

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

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

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

指定多个数据批量评估：

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

全部数据批量评估：

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

方式二：修改 config.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

然后运行：

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 与点云单位不一致时缩放点云。
• 输出文件：

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 存在旋转误差、裁剪区域不合适或单位不一致。
• 示例：

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

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

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 显示距离热力图。
• 示例：

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 依赖没有装好。执行：

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。功能不受影响，但速度会慢。