738 lines
20 KiB
Markdown
738 lines
20 KiB
Markdown
# USAGE
|
||
|
||
本文档面向后续开发人员，说明本项目的运行环境、数据约定、命令输入输出、常用工作流和排错方法。
|
||
|
||
项目根目录下的 `main.py` 是统一命令行入口。除非特别说明，所有命令都建议在项目根目录执行。
|
||
|
||
```bash
|
||
python main.py --help
|
||
```
|
||
|
||
当前公开命令：
|
||
|
||
```text
|
||
translate-align
|
||
cad2mesh
|
||
denoise
|
||
registration
|
||
contour
|
||
curvature
|
||
plane
|
||
full
|
||
```
|
||
|
||
## 1. 环境准备
|
||
|
||
推荐使用独立 conda 环境。不要直接在 `base` 环境中安装，尤其不要在 Python 3.12 的 base 环境里安装 `pythonocc-core`。
|
||
|
||
```bash
|
||
conda env create -f environment.yml
|
||
conda activate point-porj
|
||
pip install -r requirements.txt
|
||
pip install git+https://github.com/AutodeskAILab/occwl
|
||
```
|
||
|
||
如果环境已经存在：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
验证依赖：
|
||
|
||
```bash
|
||
python -c "import open3d, trimesh, torch, yaml, OCC.Core.STEPControl; print('env ok')"
|
||
```
|
||
|
||
如果 `torch` 提示 CUDA driver 版本过旧，程序会退回 CPU。功能不受影响，但点云到三角面的距离计算会慢。
|
||
|
||
## 2. 数据目录约定
|
||
|
||
默认示例数据放在 `datasets/`：
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
同一编号的数据通常应成组存在：
|
||
|
||
```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
|
||
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. 输出目录约定
|
||
|
||
建议保留以下输出目录：
|
||
|
||
```text
|
||
vis/ # 日志、热力图点云、曲率点云、中间结果
|
||
excel/ # contour 输出的 Excel 表
|
||
results/ # translate-align 默认输出目录
|
||
```
|
||
|
||
可以手动创建：
|
||
|
||
```bash
|
||
mkdir -p vis excel results
|
||
```
|
||
|
||
常见输出：
|
||
|
||
```text
|
||
*.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 窗口。
|
||
|
||
输出：
|
||
|
||
```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 # 输入点云车尾区域采样点，用于检查质心计算
|
||
```
|
||
|
||
示例：
|
||
|
||
```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 \
|
||
--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 写入进度。
|
||
|
||
示例：
|
||
|
||
```bash
|
||
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。
|
||
- 当前主流程不会自动保存滤波后的点云文件。
|
||
|
||
示例：
|
||
|
||
```bash
|
||
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
|
||
|
||
示例：
|
||
|
||
```bash
|
||
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 格式：
|
||
|
||
```text
|
||
任务号 | 最大值 | 平均值 | 状态
|
||
```
|
||
|
||
任务号从 CAD 文件名提取。例如：
|
||
|
||
```text
|
||
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`
|
||
|
||
快速查看统计结果：
|
||
|
||
```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 11_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
|
||
```
|
||
|
||
显存或内存不足时调小分块：
|
||
|
||
```bash
|
||
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。
|
||
|
||
示例：
|
||
|
||
```bash
|
||
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。
|
||
|
||
示例：
|
||
|
||
```bash
|
||
python main.py plane --no-visualize
|
||
```
|
||
|
||
带输入点云：
|
||
|
||
```bash
|
||
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 调用时会返回一个结果字典。
|
||
|
||
示例：
|
||
|
||
```bash
|
||
python main.py --config config.yaml full --no-visualize
|
||
```
|
||
|
||
## 6. 配置文件
|
||
|
||
默认配置在 `config.yaml`。
|
||
|
||
常用字段：
|
||
|
||
```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
|
||
```
|
||
|
||
命令行参数优先级高于配置文件。例如：
|
||
|
||
```bash
|
||
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 中调用：
|
||
|
||
```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. 打包使用
|
||
|
||
生成可安装包源码：
|
||
|
||
```bash
|
||
python packaging/build_package.py
|
||
```
|
||
|
||
本地开发安装：
|
||
|
||
```bash
|
||
pip install -e packaging/build
|
||
geometry-measure --help
|
||
```
|
||
|
||
安装后命令与 `main.py` 对应：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
每次修改根目录源码后，如果需要同步到打包目录，重新运行：
|
||
|
||
```bash
|
||
python packaging/build_package.py
|
||
```
|
||
|
||
## 9. 辅助脚本说明
|
||
|
||
辅助脚本放在 `archive/`。常用流程推荐优先使用 `main.py` 统一入口。
|
||
|
||
`archive/Contour_Flatness.py` 可用于批量轮廓/平整度/平面度评估：
|
||
|
||
```bash
|
||
python archive/Contour_Flatness.py \
|
||
--tasks "11,31,40" \
|
||
--data_root High_Speed_Data \
|
||
--pointcloud_kind noise \
|
||
--excel_output vis/flatness.xlsx
|
||
```
|
||
|
||
单任务模式：
|
||
|
||
```bash
|
||
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` 调用；需要单独运行脚本时也可以直接执行：
|
||
|
||
```bash
|
||
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`：
|
||
|
||
```text
|
||
datasets/CAD/45.step
|
||
datasets/Mesh/45.stl
|
||
datasets/PointCloud/45.ply
|
||
datasets/Noise_PointCloud/45_noisy.ply
|
||
```
|
||
|
||
运行评估：
|
||
|
||
```bash
|
||
python main.py contour \
|
||
--tasks 45 \
|
||
--data-root datasets \
|
||
--pointcloud-kind noise \
|
||
--save vis/contour \
|
||
--excel-output 45_contour.xlsx \
|
||
--no-visualize
|
||
```
|
||
|
||
### 保存命令日志
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
### 内存不足或显存不足
|
||
|
||
优先调小：
|
||
|
||
```bash
|
||
--point-chunk-size 512
|
||
--triangle-chunk-size 1024
|
||
```
|
||
|
||
如果 CAD 三角面过多，也可以增大：
|
||
|
||
```bash
|
||
--mesh-deflection 0.5
|
||
```
|
||
|
||
注意：`mesh_deflection` 越大，CAD 三角化越粗，速度更快但几何近似更粗。
|
||
|
||
## 11. 排错
|
||
|
||
### `No module named OCC`
|
||
|
||
说明 CAD 依赖未安装或当前 Python 环境不对。
|
||
|
||
```bash
|
||
conda activate point-porj
|
||
conda env update -n point-porj -f environment.yml
|
||
```
|
||
|
||
### `pythonocc-core` 无法通过 pip 安装
|
||
|
||
这是正常情况。`pythonocc-core` 应通过 conda 安装，不要放进纯 pip 安装流程里。
|
||
|
||
### 找不到文件
|
||
|
||
检查当前工作目录是否为项目根目录。相对路径都按当前运行目录解析。
|
||
|
||
推荐：
|
||
|
||
```bash
|
||
pwd
|
||
python main.py --help
|
||
```
|
||
|
||
Windows PowerShell 下可以使用：
|
||
|
||
```powershell
|
||
Get-Location
|
||
python main.py --help
|
||
```
|
||
|
||
### Open3D 可视化窗口影响自动化运行
|
||
|
||
加 `--no-visualize`。
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
python main.py contour \
|
||
--cad datasets/CAD/11.step \
|
||
--pointcloud datasets/Noise_PointCloud/11_noisy.ply \
|
||
--excel-output \
|
||
--no-visualize
|
||
```
|
||
|
||
默认输出：
|
||
|
||
```text
|
||
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` 产生歧义。
|