lipan/massive-cloud

Fork 0

Files

lipan 16811100d1 feat: initial commit - massive-cloud point cloud processing system

2026-05-27 09:51:42 +00:00

20 KiB

Raw Blame History

USAGE

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

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

python main.py --help

当前公开命令：

translate-align
cad2mesh
denoise
registration
contour
curvature
plane
full

1. 环境准备

推荐使用独立 conda 环境。不要直接在 base 环境中安装，尤其不要在 Python 3.12 的 base 环境里安装 pythonocc-core。

conda env create -f environment.yml
conda activate point-porj
pip install -r requirements.txt
pip install git+https://github.com/AutodeskAILab/occwl

如果环境已经存在：

conda env update -n point-porj -f environment.yml
conda activate point-porj
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 点云和标准CAD配准：`translate-align`

功能：调用 archive/translate_align_pointcloud_to_cad.py，从 CAD 和待对齐点云的车头/车尾区域各采样少量点，计算前后端质心差，并融合成一个整体平移矩阵。该方法只修正平移，不修正旋转。

输入：

--cad：参考 STEP CAD，默认 datasets/CAD/M02.stp。
--pointcloud：待对齐 PLY 点云或点云目录，默认 datasets/shift_test_output/。传目录时会优先读取 shifted_whole_pointcloud.ply。
--output-dir：输出目录，默认 results。
--axis：车辆长度方向，默认 x。
--crop-ratio：车头/车尾各截取整体长度的比例，默认 0.01。
--mesh-deflection：CAD 三角化精度。
--cad-sample-points：从 CAD mesh 采样的点数，默认 30000。
--local-sample-points：车头/车尾局部用于计算质心的采样点数，默认 1000。
--scale-pointcloud：点云缩放系数。例如点云是米、CAD 是毫米时可设为 1000。
--no-visualize：禁用 Open3D 窗口。

输出：

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                   # 输入点云车尾区域采样点，用于检查质心计算

示例：

python main.py translate-align \
  --cad datasets/CAD/M02.stp \
  --pointcloud datasets/shift_test_output/ \
  --output-dir results \
  --axis x \
  --crop-ratio 0.01 \
  --cad-sample-points 30000 \
  --local-sample-points 1000 \
  --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 轮廓/平整度/平面度评估：`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。
--no-visualize：禁用 Open3D 窗口。

输出：

终端距离统计：Mean、Max、RMSE、Min、Std。
如果传 --save：保存彩色热力图 PLY。
如果传 --excel-output：保存 Excel。

Excel 格式：

任务号 | 最大值 | 平均值 | 状态

任务号从 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

批量模式路径规则：

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

快速查看统计结果：

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

执行全部数据：

python main.py contour \
  --all \
  --data-root datasets \
  --pointcloud-kind noise \
  --save vis/contour \
  --excel-output all_contour.xlsx \
  --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.6 曲率估计：`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.7 平面拟合：`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.8 完整流程：`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",
    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 三角化越粗，速度更快但几何近似更粗。

11. 排错

`No module named OCC`

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

conda activate point-porj
conda env update -n point-porj -f environment.yml

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

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

找不到文件

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

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

`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 产生歧义。

20 KiB Raw Blame History Unescape Escape