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