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

USAGE

本文档面向后续开发人员，说明本项目的运行环境、数据约定、命令输入输出、常用工作流和排错方法。

项目根目录下的 main.py 是统一命令行入口。除非特别说明，所有命令都建议在项目根目录执行。

python main.py --help

当前公开命令：

translate-align
cad2mesh
denoise
registration
contour
curvature
plane
full

1. 环境准备

推荐使用独立 conda 环境。当前项目建议使用 High-Speed 环境运行；不要直接在 base 环境中安装，尤其不要在 Python 3.12 的 base 环境里安装 pythonocc-core。

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

如果环境已经存在：

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

验证依赖：

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

如果 torch 提示 CUDA driver 版本过旧，程序会退回 CPU。功能不受影响，但点云到三角面的距离计算会慢。

2. 数据目录约定

默认示例数据放在 datasets/：

datasets/
  CAD/                 # STEP CAD，例如 11.step
  Mesh/                # STL/OBJ/PLY Mesh，例如 11.stl
  PointCloud/          # 原始/干净点云 PLY，例如 11.ply
  Noise_PointCloud/    # 加噪或待配准点云 PLY，例如 11_noisy.ply
  shift_test_output/   # translate-align 测试输出，默认读取 shifted_whole_pointcloud.ply

同一编号的数据通常应成组存在：

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

translate-align 默认使用下面这组输入：

datasets/CAD/M02.stp
datasets/shift_test_output/shifted_whole_pointcloud.ply

数据要求：

• CAD 使用 STEP，扩展名通常是 .step 或 .stp。
• Mesh 使用 trimesh 可读取的格式，例如 .stl、.obj、.ply。
• PointCloud 推荐 PLY，必须包含三维点坐标。
• CAD、Mesh、PointCloud 必须处于同一坐标系和同一单位。
• 示例数据按毫米量级处理。
• contour 假设点云已与 CAD/Mesh 对齐。
• registration 会模拟旋转后做配准。

3. 输出目录约定

建议保留以下输出目录：

vis/       # 日志、热力图点云、曲率点云、中间结果
excel/     # contour 输出的 Excel 表
results/   # translate-align 默认输出目录

可以手动创建：

mkdir -p vis excel results

常见输出：

*.stl      # CAD 转 Mesh 结果
*.ply      # 彩色点云、热力图点云
*.xlsx     # 轮廓/平整度/平面度 Excel 汇总
*.log      # shell 重定向保存的终端输出
results/T_translation_only.txt
results/aligned_pointcloud_translation_only.ply

4. 方法输入输出总览

方法	用途	输入	输出
translate-align	点云到标准CAD的配准	默认 --cad datasets/CAD/M02.stp --pointcloud datasets/shift_test_output/；可调头尾截取和采样参数	默认写入 results/，输出对齐后点云、4x4 平移矩阵和头尾采样检查文件
cad2mesh	STEP CAD 转 STL Mesh	--cad STEP 文件	--mesh STL 文件
denoise	给干净点云加噪，并运行滤波方法	--pointcloud 干净 PLY；--noise-std 噪声标准差	终端输出点数、平均噪声偏移、滤波保留比例、Chamfer Distance
registration	点云到 Mesh 配准与距离评估	--pointcloud 待配准 PLY；--mesh 参考 Mesh	终端输出 fitness、RMSE、变换矩阵、配准后距离统计
contour	轮廓/平整度/平面度评估	单任务：--pointcloud 和 --cad；批量：--tasks 或 --all，并指定 --data-root、--pointcloud-kind	终端输出 Mean、Max、RMSE、Min、Std；可保存热力图 PLY 和 Excel
curvature	点云曲率估计	--pointcloud PLY；--radius 邻域半径；--max-nn 最大邻居数	终端输出曲率 mean/max；可保存彩色曲率 PLY
plane	RANSAC 平面拟合	可选 --pointcloud PLY；不传则生成模拟带噪平面	终端输出平面模型、内点比例、法向角度误差、RMSE
full	配置驱动的完整流程	--config YAML 配置；默认 config.yaml	串联输出加噪/滤波、配准和距离评估结果

5. 命令详解

5.1 轮廓/平整度/平面度评估：contour

功能：统一的轮廓/平整度/平面度评估入口。默认读取 STEP CAD，三角化后计算点云到 CAD 三角面的最近距离。

输入：

• --pointcloud：待评估 PLY 点云。
• --cad：参考 STEP CAD。
• --mesh：可传参考 STL/OBJ/PLY Mesh。传了 --mesh 时会走点云到 Mesh 距离计算。
• --tasks：批量执行指定任务编号，用英文逗号分隔，例如 11,31,40。
• --all：批量执行 --data-root 下 CAD/ 中的全部 STEP 数据。
• --data-root：批量数据根目录，默认 datasets。
• --pointcloud-kind：批量点云来源，noise 读取 Noise_PointCloud/{id}_noisy.ply，clean 读取 PointCloud/{id}.ply。
• --mesh-deflection：STEP 三角化精度，越小越精细，但三角面更多、计算更慢。
• --point-chunk-size：点云分块大小。
• --triangle-chunk-size：三角面分块大小。
• --save：保存距离热力图 PLY。
• --excel-output：保存 Excel。
• --result-template：Excel 参考模板，默认 excel/测量结果.xlsx。
• --combined-context-pointcloud：合并热力图时一起加入的完整点云，默认 datasets/train/train_2_10M.ply。可指定 datasets/train/train_2_1T_配准.ply；保存合并 PLY 时会按块流式写入，避免整体加载完整点云。
• --no-visualize：禁用 Open3D 窗口。使用 train_2_1T_配准.ply 时必须加该参数，否则窗口展示仍会尝试加载超大点云。

输出：

• 终端距离统计：Mean、Max、RMSE、Min、Std。
• 如果传 --save：保存彩色热力图 PLY。
• 如果传 --excel-output：保存 Excel。
• 批量模式：所有成功执行的热力图会按原始坐标额外保存成一个合并 PLY；保存阶段支持对 datasets/train/train_2_1T_配准.ply 进行流式合并。未传 --no-visualize 时也会按原始坐标合并到一个 Open3D 窗口展示，但超大背景点云不适合窗口展示。
• 批量模式会在终端最后打印总执行时间 Contour batch total execution time，该时间包含任务计算、Excel 保存和合并 PLY 保存。

Excel 格式：

任务号 | 项点名称 | 公差要求 | 理论尺寸 | 测量结果 | 误差结果 | 测量结论

默认读取 excel/测量结果.xlsx 作为模板，按 任务号 迁移对应行到新 Excel。程序只填本次的 测量结果 和 测量结论：测量结果为本次测量均值；测量成功填 成功，否则填 失败。如果需要使用其它模板，传 --result-template path/to/template.xlsx。

任务号从 CAD 文件名提取。例如：

datasets/CAD/11.step -> 11

Excel 路径规则：

• --excel-output 不带值：保存到 excel/contour.xlsx
• --excel-output 11_contour.xlsx：保存到 excel/11_contour.xlsx
• --excel-output reports/11.xlsx：保存到 reports/11.xlsx
• --result-template 不传：默认读取 excel/测量结果.xlsx

批量模式路径规则：

• CAD：{data_root}/CAD/{任务号}.step
• 加噪点云：{data_root}/Noise_PointCloud/{任务号}_noisy.ply
• 干净点云：{data_root}/PointCloud/{任务号}.ply
• 如果 --save 是目录，例如 --save vis/contour，每个任务会保存为 vis/contour/{任务号}_contour.ply
• 如果 --save 是带 {task_id} 的文件模板，例如 --save vis/{task_id}_contour.ply，会替换任务号
• 如果 --save 是普通 PLY 文件，例如 --save vis/contour.ply，批量模式会保存为 vis/contour_{任务号}.ply
• 合并点云保存规则：未传 --save 时保存为 vis/combined_contour.ply；--save vis/contour 时保存为 vis/contour/combined_contour.ply；--save vis/{task_id}_contour.ply 时保存为 vis/combined_contour.ply；--save vis/contour.ply 时保存为 vis/contour_combined.ply
• 合并点云默认会加入 datasets/train/train_2_10M.ply；可用 --combined-context-pointcloud datasets/train/train_2_100M.ply 或 datasets/train/train_2_1T_配准.ply 切换。保存合并 PLY 时，大背景点云按块从输入文件写入输出文件，不再用 Open3D 整体读入内存；输出文件会比原始背景点云更大，因为会额外写入 RGB 颜色。注意：由于 train_2_100M.ply 或 train_2_1T_配准.ply 太大，通常需要使用者自行导入或修改地址。
• 如果没有传 --no-visualize，批量模式会把所有成功热力图合并显示在一个窗口里。使用 train_2_1T_配准.ply 时不要打开窗口，必须保留 --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 11_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

执行全部任务：

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

注意：使用时，利用combined-context-pointcloud指定配准后的点云路径 该模式只保存合并 PLY，不打开 Open3D 展示窗口。train_2_1T_配准.ply 会被流式读取，适合用于生成最终大文件；不要去掉 --no-visualize。

显存或内存不足时调小分块：

python main.py contour \
  --cad datasets/CAD/11.step \
  --pointcloud datasets/Noise_PointCloud/11_noisy.ply \
  --mesh-deflection 0.5 \
  --point-chunk-size 512 \
  --triangle-chunk-size 1024 \
  --excel-output \
  --no-visualize

5.2 CAD 转 Mesh：cad2mesh

功能：读取 STEP CAD，离散成 STL 三角网格。

输入：

• --cad：输入 STEP 文件。
• --mesh：输出 STL 文件。
• --precision：离散精度，单位为 mm。值越小通常越精细，生成文件也可能越大。

输出：

• 一个 STL 文件。
• 终端输出 STEP 读取、网格化和 STL 写入进度。

示例：

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

5.3 加噪与滤波：denoise

功能：读取干净点云，加高斯噪声，并按配置运行滤波方法。

输入：

• --pointcloud：干净 PLY 点云。
• --noise-std：高斯噪声标准差。
• --no-visualize：禁用 Open3D 窗口。

输出：

• 终端输出干净点数、加噪点数、平均噪声偏移。
• 对每个滤波方法输出保留比例和 Chamfer Distance。
• 当前主流程不会自动保存滤波后的点云文件。

示例：

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

5.4 配准：registration

功能：对输入点云模拟旋转，然后通过 RANSAC + ICP 配准到 Mesh，并计算配准后距离。

输入：

• --pointcloud：待配准 PLY 点云，通常使用 datasets/Noise_PointCloud/*_noisy.ply。
• --mesh：参考 STL/OBJ/PLY Mesh。
• --voxel-size：配准下采样体素大小。
• --roll、--pitch、--yaw：模拟旋转角度，单位为 degree。
• --trans-range：随机平移范围。
• --no-visualize：禁用 Open3D 窗口。

输出：

• Fitness
• RMSE
• 4x4 transformation matrix
• 配准后点云到 Mesh 的距离统计：Mean、Max、RMSE、Min、Std

示例：

python main.py registration \
  --pointcloud datasets/Noise_PointCloud/11_noisy.ply \
  --mesh datasets/Mesh/11.stl \
  --voxel-size 10 \
  --roll 10 \
  --pitch 10 \
  --yaw 10 \
  --no-visualize

5.5 曲率估计：curvature

功能：计算点云局部曲率，并按曲率着色。

输入：

• --pointcloud：PLY 点云。
• --radius：邻域搜索半径。
• --max-nn：最大邻居数。
• --color-scale：颜色缩放系数。
• --save：保存彩色曲率点云。
• --no-visualize：禁用 Open3D 窗口。

输出：

• 终端输出曲率 mean 和 max。
• 如果传 --save：保存彩色曲率 PLY。

示例：

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

5.6 平面拟合：plane

功能：使用 RANSAC 拟合平面。

输入：

• --pointcloud：可选 PLY 点云。不传时会根据 config.yaml 生成模拟带噪平面。
• --threshold-mm：RANSAC 距离阈值，单位 mm。
• --max-iterations：RANSAC 最大迭代次数。
• --no-visualize：禁用 Open3D 窗口。

输出：

• 平面模型参数。
• 内点比例。
• 法向角度误差。
• 平面 RMSE。

示例：

python main.py plane --no-visualize

带输入点云：

python main.py plane \
  --pointcloud datasets/PointCloud/11.ply \
  --threshold-mm 0.5 \
  --max-iterations 2000 \
  --no-visualize

5.7 完整流程：full

功能：按 config.yaml 串联运行流程。

当前默认行为：

• 如果 cad.enabled: false，不会自动执行 CAD 转 Mesh。
• 如果 noise.enabled: true，会先运行 denoise，再对加噪点云做配准。
• 最后运行 contour。

输入：

• --config：配置文件路径。不传时使用内置默认配置。
• --no-visualize：禁用 Open3D 窗口。

输出：

• 每个阶段的终端指标。
• Python 调用时会返回一个结果字典。

示例：

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

6. 配置文件

默认配置在 config.yaml。

常用字段：

paths:
  cad: datasets/CAD/11.step
  mesh: datasets/Mesh/11.stl
  pointcloud: datasets/PointCloud/11.ply
  noisy_pointcloud: datasets/Noise_PointCloud/11_noisy.ply
  output_mesh: datasets/Mesh/11.stl
  curvature_output:

cad:
  enabled: false
  precision: 1.0

noise:
  enabled: true
  std: 4.0

registration:
  voxel_size: 10.0
  roll: 10.0
  pitch: 10.0
  yaw: 10.0
  trans_range: 0.0

evaluation:
  chunk_size: 2048
  triangle_chunk_size: 4096
  cad_mesh_deflection: 0.1

visualization:
  enabled: true

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

python main.py --config config.yaml contour \
  --cad datasets/CAD/40.step \
  --pointcloud datasets/Noise_PointCloud/40_noisy.ply \
  --excel-output 40_contour.xlsx \
  --no-visualize

7. Python API 用法

除了命令行，也可以在 Python 中调用：

from pipeline import MeasurementPipeline

pipeline = MeasurementPipeline(config_path="config.yaml")

result = pipeline.run_contour(
    cad_path="datasets/CAD/11.step",
    pointcloud_path="datasets/Noise_PointCloud/11_noisy.ply",
    save_path="vis/11_contour.ply",
    excel_output_path="11_contour.xlsx",
    result_template_path="excel/测量结果.xlsx",
    no_visualize=True,
)

print(result["distance_stats"])

常用返回字段：

• run_contour：pointcloud、distances、distance_stats、cad_vertices、cad_faces、excel_output
• run_translate_align_pointcloud_to_cad：translation、T_final、aligned_path、matrix_path
• run_registration：source、registration、distance_stats
• run_curvature：pointcloud、curvatures
• run_plane：plane_result

8. 打包使用

生成可安装包源码：

python packaging/build_package.py

本地开发安装：

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

安装后命令与 main.py 对应：

geometry-measure contour \
  --cad datasets/CAD/11.step \
  --pointcloud datasets/Noise_PointCloud/11_noisy.ply \
  --save vis/11_contour.ply \
  --excel-output 11_contour.xlsx \
  --no-visualize

每次修改根目录源码后，如果需要同步到打包目录，重新运行：

python packaging/build_package.py

9. 辅助脚本说明

辅助脚本放在 archive/。常用流程推荐优先使用 main.py 统一入口。

archive/Contour_Flatness.py 可用于批量轮廓/平整度/平面度评估：

python archive/Contour_Flatness.py \
  --tasks "11,31,40" \
  --data_root High_Speed_Data \
  --pointcloud_kind noise \
  --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

archive/translate_align_pointcloud_to_cad.py 已接入统一入口，推荐用 main.py translate-align 调用；需要单独运行脚本时也可以直接执行：

python archive/translate_align_pointcloud_to_cad.py \
  -c datasets/CAD/M02.stp \
  -p datasets/shift_test_output/ \
  -o results \
  --axis x \
  --crop_ratio 0.01 \
  --no_visualize

10. 常见开发任务

添加一个新数据编号

例如添加编号 45：

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

运行评估：

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

保存命令日志

python main.py contour \
  --cad datasets/CAD/11.step \
  --pointcloud datasets/Noise_PointCloud/11_noisy.ply \
  --excel-output 11_contour.xlsx \
  --no-visualize > vis/11_contour.log 2>&1

内存不足或显存不足

优先调小：

--point-chunk-size 512
--triangle-chunk-size 1024

如果 CAD 三角面过多，也可以增大：

--mesh-deflection 0.5

注意：mesh_deflection 越大，CAD 三角化越粗，速度更快但几何近似更粗。

如果内存错误发生在批量合并完整背景点云阶段，并且使用的是 datasets/train/train_2_1T_配准.ply，请确认命令包含 --no-visualize。保存合并 PLY 已支持流式写入；Open3D 窗口展示仍不适合 10 亿点背景点云。

11. 排错

No module named OCC

说明 CAD 依赖未安装或当前 Python 环境不对。

conda activate High-Speed
conda env update -n High-Speed -f environment.yml

pythonocc-core 无法通过 pip 安装

这是正常情况。pythonocc-core 应通过 conda 安装，不要放进纯 pip 安装流程里。

找不到文件

检查当前工作目录是否为项目根目录。相对路径都按当前运行目录解析。

推荐：

pwd
python main.py --help

Windows PowerShell 下可以使用：

Get-Location
python main.py --help

Open3D 可视化窗口影响自动化运行

加 --no-visualize。

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

结果距离明显不合理

重点检查：

• CAD 和点云是否同单位。
• CAD 和点云是否已经对齐。
• 是否把干净点云和加噪点云用错目录。
• mesh_deflection 是否过大导致 CAD 近似过粗。

Excel 没有生成

contour 只有传了 --excel-output 才会生成 Excel：

python main.py contour \
  --cad datasets/CAD/11.step \
  --pointcloud datasets/Noise_PointCloud/11_noisy.ply \
  --excel-output \
  --no-visualize

默认输出：

excel/contour.xlsx

默认模板：

excel/测量结果.xlsx

输出表头保持模板一致，程序只更新 测量结果 和 测量结论。

registration 或 contour 很慢

原因通常是点云超过百万点，且距离计算要遍历大量三角面。可以：

• 调小点云规模。
• 调小 --point-chunk-size 和 --triangle-chunk-size 以降低内存压力。
• 增大 --mesh-deflection 减少 CAD 三角面数量。
• 对配准增加 --voxel-size 做更强下采样。

12. 开发约定

• 面向用户的新功能优先接入 main.py 和 MeasurementPipeline。
• contour 是轮廓/平整度/平面度评估的唯一公开入口，不再新增其它容易混淆的同类命令。
• 新增输出文件时优先放入已有输出目录：通用可视化和日志放 vis/，表格放 excel/，对齐结果放 results/。
• 修改根目录源码后，如果需要打包版本同步，运行 python packaging/build_package.py。
• 不要在文档中引入其它同类距离评估命令名，避免和 contour 产生歧义。