feat: 算法升级、整车配准集成与性能分析文档
算法更新: delivery v1.2.1、平整度v1.5、测距v2.2、整车配准v1.3 适配器: vehicle-registration 新增、各算法 manifest 和 adapter 更新 后端: taskCadFiles/source 字段迁移、derivedPointClouds 注册、取消任务联动 前端: ElapsedTime 时长显示、两步算法流程、canRun 逻辑修复 文档: 新增5份算法性能分析报告
This commit is contained in:
720
alg/平整度、平面度、轮廓测量v1.5/USAGE.md
Normal file
720
alg/平整度、平面度、轮廓测量v1.5/USAGE.md
Normal file
@@ -0,0 +1,720 @@
|
||||
# USAGE
|
||||
|
||||
本文档面向后续开发人员，说明本项目的运行环境、数据约定、命令输入输出、常用工作流和排错方法。
|
||||
|
||||
项目根目录下的 `main.py` 是统一命令行入口。除非特别说明，所有命令都建议在项目根目录执行。
|
||||
|
||||
```bash
|
||||
python main.py --help
|
||||
```
|
||||
|
||||
当前公开命令：
|
||||
|
||||
```text
|
||||
translate-align
|
||||
cad2mesh
|
||||
denoise
|
||||
registration
|
||||
contour
|
||||
curvature
|
||||
plane
|
||||
full
|
||||
```
|
||||
|
||||
## 1. 环境准备
|
||||
|
||||
推荐使用独立 conda 环境。当前项目建议使用 `High-Speed` 环境运行；不要直接在 `base` 环境中安装，尤其不要在 Python 3.12 的 base 环境里安装 `pythonocc-core`。
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
如果环境已经存在：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
验证依赖：
|
||||
|
||||
```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 轮廓/平整度/平面度评估：`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 格式：
|
||||
|
||||
```text
|
||||
任务号 | 项点名称 | 公差要求 | 理论尺寸 | 测量结果 | 误差结果 | 测量结论
|
||||
```
|
||||
|
||||
默认读取 `excel/测量结果.xlsx` 作为模板，按 `任务号` 迁移对应行到新 Excel。程序只填本次的 `测量结果` 和 `测量结论`：测量结果为本次测量均值；测量成功填 `成功`，否则填 `失败`。如果需要使用其它模板，传 `--result-template path/to/template.xlsx`。
|
||||
|
||||
任务号从 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`
|
||||
- `--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`。
|
||||
|
||||
快速查看统计结果：
|
||||
|
||||
```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
|
||||
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`。
|
||||
|
||||
显存或内存不足时调小分块：
|
||||
|
||||
```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.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 曲率估计：`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.6 平面拟合：`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.7 完整流程：`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",
|
||||
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. 打包使用
|
||||
|
||||
生成可安装包源码：
|
||||
|
||||
```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 三角化越粗，速度更快但几何近似更粗。
|
||||
|
||||
如果内存错误发生在批量合并完整背景点云阶段，并且使用的是 `datasets/train/train_2_1T_配准.ply`，请确认命令包含 `--no-visualize`。保存合并 PLY 已支持流式写入；Open3D 窗口展示仍不适合 10 亿点背景点云。
|
||||
|
||||
## 11. 排错
|
||||
|
||||
### `No module named OCC`
|
||||
|
||||
说明 CAD 依赖未安装或当前 Python 环境不对。
|
||||
|
||||
```bash
|
||||
conda activate High-Speed
|
||||
conda env update -n High-Speed -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
|
||||
```
|
||||
|
||||
默认模板：
|
||||
|
||||
```text
|
||||
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` 产生歧义。
|
||||
Reference in New Issue
Block a user