feat: 算法升级、整车配准集成与性能分析文档

算法更新: delivery v1.2.1、平整度v1.5、测距v2.2、整车配准v1.3
适配器: vehicle-registration 新增、各算法 manifest 和 adapter 更新
后端: taskCadFiles/source 字段迁移、derivedPointClouds 注册、取消任务联动
前端: ElapsedTime 时长显示、两步算法流程、canRun 逻辑修复
文档: 新增5份算法性能分析报告

alg/平整度、平面度、轮廓测量v1.5/archive/Readme.md

@@ -0,0 +1,280 @@
+# 工业零件几何测量工具使用指南
+> 支持测量种类：平整度、平面度、轮廓测量、曲率分析、点云去噪、平面拟合、点云配准评估
+> 支持测量任务编号：11、13、17、20、25、26、27、31、34、35、36、37、38、39、40、41、42、45
+
+## 一、环境配置
+### 基础环境要求
+- Python 3.10.8
+- CUDA 11.8（建议，无CUDA时自动降级为CPU计算）
+- PyTorch 2.2
+
+### 依赖安装
+```bash
+conda install -f requirements.txt
+```
+> 注：需确保环境中已安装OCC Core（STEP/STL处理）、trimesh、open3d、numpy、scipy等依赖
+
+---
+
+## 二、CAD转轻量化Mesh（CAD2Mesh.py）
+### 功能说明
+将STEP格式的CAD模型转换为轻量化STL网格文件，通过调整网格精度控制文件体积（精度值越大，文件越小，精度越低），纯后台处理无界面显示，转换效率高。
+
+### 输入输出
+- **输入**：STEP格式CAD文件（路径示例：`High_Speed_Data/CAD/11.step`）
+- **输出**：STL格式轻量化网格文件（路径示例：`High_Speed_Data/Mesh/11.stl`）
+
+### 命令行参数说明
+| 参数         | 简写 | 类型   | 默认值                          | 说明                                   |
+|--------------|------|--------|---------------------------------|----------------------------------------|
+| --precision  | -p   | float  | 1.0                             | 网格精度（单位：mm），值越大文件体积越小 |
+| --input      | -i   | string | High_Speed_Data/CAD/11.step     | 输入STEP文件路径                       |
+| --output     | -o   | string | High_Speed_Data/Mesh/11.stl     | 输出STL文件路径                        |
+
+### 运行示例
+```bash
+# 完整参数形式
+python CAD2Mesh.py --precision 1 --input "High_Speed_Data/CAD/11.step" --output "High_Speed_Data/Mesh/11.stl"
+
+# 简写参数形式
+python CAD2Mesh.py -p 1 -i "High_Speed_Data/CAD/11.step" -o "High_Speed_Data/Mesh/11.stl"
+```
+
+### 运行日志说明
+程序会输出三步处理日志及耗时：
+1. STEP文件读取阶段
+2. 网格离散化（轻量化）阶段
+3. STL文件保存阶段
+转换完成后会提示总耗时及STL文件打开工具建议（FreeCAD/MeshLab/3D Viewer）。
+
+---
+
+## 三、轮廓-平整度测量（Contour_Flatness.py）
+### 功能说明
+高精度计算点云到 CAD STEP 模型三角化表面的最近距离，输出平均距离（mean_dist）、最大距离（max_dist）和最小距离（min_dist），用于评估零件的平整度、平面度、轮廓偏差等几何精度指标；支持 CUDA 加速（自动检测），采用 torch.float64 高精度计算。
+
+脚本现在支持两种模式：
+- 默认批量模式：按任务编号从 `High_Speed_Data/CAD/` 和点云目录中读取多组数据，并输出 Excel 汇总。
+- 单任务模式：添加 `--single` 后，使用 `--CAD` 和 `--pointcloud` 计算一组文件，可选 `--visualize` 显示热力图。批量模式会把所有成功执行的热力图和完整点云按原始坐标合并保存为一个 PLY，默认 `vis/combined_contour.ply`；使用 `--visualize` 时还会合并到一个窗口展示。
+
+批量模式会优先使用 `Mesh/{样本名}.stl`，并按样本名匹配点云。例如 `13_1.stl` 和 `13_2.stl` 都属于任务 `13`，对应点云分别为 `13_1_noisy.ply`、`13_2_noisy.ply`；Excel 会按任务 `13` 汇总并记录样本数。没有匹配到 Mesh 样本时，脚本会退回旧的 `CAD/{任务号}.step` 模式。
+
+距离计算流程已参考 `test8.py` 更新：默认先用点到三角形 AABB 的距离为每个点筛选候选三角面，再对候选三角面计算精确点到三角形距离。可通过 `--candidate_triangle_count` 控制候选数量；设为 `0` 或负数时退回旧的全量三角面分块精确搜索。
+
+### 输入输出
+- **输入**：
+  - CAD STEP 文件：路径示例 `High_Speed_Data/CAD/11.step`
+  - Mesh 文件：路径示例 `High_Speed_Data/Mesh/13_1.stl`
+  - 点云 PLY 文件：批量模式默认读取 `High_Speed_Data/Noise_PointCloud/{样本名}_noisy.ply`，也可用 `--pointcloud_kind clean` 读取 `High_Speed_Data/PointCloud/{样本名}.ply`
+- **输出**：
+  - 平均距离（mean_dist）：点云中所有点到 CAD 三角面的平均最近距离（单位：mm）
+  - 最大距离（max_dist）：点云中所有点到 CAD 三角面的最大最近距离（单位：mm）
+  - 最小距离（min_dist）：点云中所有点到 CAD 三角面的最小最近距离（单位：mm）
+  - 批量模式会生成 Excel 汇总文件，默认 `平整度.xlsx`
+  - 批量模式会保存合并热力图 PLY，默认 `vis/combined_contour.ply`，并默认加入完整点云 `datasets/train/train_2_10M.ply`
+
+### 命令行参数说明
+| 参数 | 简写 | 类型 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| --CAD | -c | string | High_Speed_Data/CAD/11.step | 单任务模式 CAD STEP 文件路径，仅 `--single` 时使用 |
+| --pointcloud | -p | string | High_Speed_Data/Noise_PointCloud/11_noisy.ply | 单任务模式点云路径，仅 `--single` 时使用 |
+| --tasks | - | string | 11,13,17,20,25,26,27,31,34,35,36,37,38,39,40,41,42,45 | 批量任务编号或样本名，多个值用英文逗号分隔；`13` 匹配 `13_1/13_2`，`13_1` 只匹配该样本 |
+| --data_root | - | string | High_Speed_Data | 批量任务数据根目录 |
+| --pointcloud_kind | - | string | noise | 批量模式点云来源：`noise` 读取 Noise_PointCloud，`clean` 读取 PointCloud |
+| --excel_output | - | string | 平整度.xlsx | 批量结果 Excel 输出路径 |
+| --combined_output | - | string | vis/combined_contour.ply | 批量合并热力图 PLY 输出 |
+| --combined_context_pointcloud | - | string | datasets/train/train_2_10M.ply | 合并热力图时一起加入的完整点云，可切换为 `train_2_100M.ply` 或 `train_2_1T.ply` |
+| --single | - | flag | false | 启用单任务模式 |
+| --visualize | - | flag | false | 显示距离热力图；批量模式会合并所有成功结果 |
+| --mesh_deflection | - | float | 0.1 | CAD 三角化精度，越小越精细但越慢 |
+| --point_chunk_size | - | int | 2048 | 点云分块大小，显存/内存不足时可调小 |
+| --triangle_chunk_size | - | int | 4096 | 全量精确搜索模式下的三角面分块大小；`candidate_triangle_count <= 0` 时使用 |
+| --candidate_triangle_count | - | int | 32 | 每个点按 AABB 预筛的候选三角面数量；设为 0 或负数则使用全量精确搜索 |
+
+### 运行示例
+```bash
+# 默认批量模式，使用 DEFAULT_TASK_IDS 并输出 平整度.xlsx
+python Contour_Flatness.py
+
+# 指定批量任务、点云来源、Excel 输出和候选三角面数量
+python Contour_Flatness.py --tasks "13,31,40" --data_root "High_Speed_Data" --pointcloud_kind noise --excel_output "vis/flatness.xlsx" --candidate_triangle_count 32
+
+# 单任务模式
+python Contour_Flatness.py --single --CAD "High_Speed_Data/CAD/11.step" --pointcloud "High_Speed_Data/Noise_PointCloud/11_noisy.ply" --candidate_triangle_count 32
+
+# 单任务模式并显示热力图
+python Contour_Flatness.py --single -c "High_Speed_Data/CAD/11.step" -p "High_Speed_Data/PointCloud/11.ply" --candidate_triangle_count 32 --visualize
+```
+
+### 计算说明
+1. CAD 读取：通过 pythonocc-core 读取 STEP，并使用 `mesh_deflection` 三角化。
+2. 点云读取：优先使用 open3d（若安装），否则使用 trimesh 兼容读取。
+3. 样本匹配：批量模式优先扫描 `Mesh` 文件夹，按样本名匹配 `PointCloud` 或 `Noise_PointCloud`；任务号取样本名下划线前的部分。
+4. 距离计算：默认使用 AABB 候选三角面预筛，减少每个点参与精确距离计算的三角面数量；如果 `candidate_triangle_count <= 0`，则使用全量三角面分块精确搜索。
+5. 批量结果：每个任务会记录成功/失败状态，成功样本会按任务号汇总并缓存在 `task_distance_data` 中；合并热力图会保存到 `--combined_output`，使用 `--visualize` 时会统一合并展示。
+6. 精度保障：采用 torch.float64 高精度计算，支持 GPU/CPU 自动切换。
+
+---
+
+## 四、点云曲率估计（curvature_estimation.py）
+### 功能说明
+基于Open3D对工业零件点云进行曲率计算，通过邻域协方差矩阵分解获取曲率值，支持曲率彩色可视化，用于识别零件边缘、棱角、曲面等特征区域，为表面缺陷检测提供依据。
+
+### 输入输出
+- **输入**：PLY格式点云文件（路径示例：`High_Speed_Data/PointCloud/11.ply`）
+- **输出**：曲率统计值、彩色可视化点云、可保存带曲率信息的PLY文件
+
+### 命令行参数说明
+| 参数         | 简写 | 类型   | 默认值                          | 说明                                   |
+|--------------|------|--------|---------------------------------|----------------------------------------|
+| --ply_path   | —    | string | ./High_Speed_Data/PointCloud/11.ply | 输入点云路径                      |
+| --radius     | —    | float  | 2.0                             | 邻域搜索半径                           |
+| --max_nn     | —    | int    | 30                              | 最大邻域点数                           |
+| --color_scale| —    | float  | 3.0                             | 曲率颜色缩放因子                       |
+| --save       | —    | string | None                            | 保存着色点云路径（可选）|
+
+### 运行示例
+```bash
+# 基础运行
+python curvature_estimation.py --ply_path "High_Speed_Data/PointCloud/11.ply"
+
+# 保存结果
+python curvature_estimation.py --ply_path "High_Speed_Data/PointCloud/11.ply" --save "High_Speed_Data/Result/11_curvature.ply"
+```
+
+### 计算说明
+1. 自动估计法线并构建KD-Tree加速邻域搜索
+2. 邻域点不足3个时自动标记为高曲率
+3. 颜色映射：红色=高曲率，绿色=低曲率
+
+---
+
+## 五、点云去噪处理（denoise.py）
+### 功能说明
+集成SOR、ROR、PF、VGF、BF五种去噪与滤波算法，自动添加高斯噪声并对比效果，通过Chamfer Distance量化评估去噪质量，用于扫描点云预处理，提升测量精度。
+
+### 输入输出
+- **输入**：PLY格式干净点云（路径示例：`High_Speed_Data/PointCloud/11.ply`）
+- **输出**：各算法去噪指标、保留率、移除点数、CD距离、可视化对比
+
+### 命令行参数说明
+| 参数         | 简写 | 类型   | 默认值                          | 说明                                   |
+|--------------|------|--------|---------------------------------|----------------------------------------|
+| --ply_path   | -p   | string | ./High_Speed_Data/PointCloud/11.ply | 输入点云路径                       |
+| --noise_std  | -n   | float  | 4.0                             | 高斯噪声标准差                         |
+| --voxel_size | -v   | float  | 0.05                            | 体素滤波大小                           |
+| --no_visualize | —  | bool   | False                           | 关闭可视化窗口                        |
+
+### 运行示例
+```bash
+# 基础去噪对比
+python denoise.py -p "High_Speed_Data/PointCloud/11.ply" --noise_std 2.0
+
+# 无可视化运行
+python denoise.py -p "High_Speed_Data/PointCloud/11.ply" --no_visualize
+```
+
+### 计算说明
+1. 自动给点云加噪，模拟真实扫描噪声
+2. 依次运行SOR/ROR/PF/VGF/BF算法
+3. 输出保留率、移除点数、Chamfer Distance评估结果
+
+---
+
+## 六、平面拟合估计（plane_estimation.py）
+### 功能说明
+基于Open3D内置RANSAC算法自动拟合点云中平面结构，输出平面方程、内点占比、法线误差、拟合RMSE，用于提取零件基准平面。
+
+### 输入输出
+- **输入**：可自定义生成带噪平面点云
+- **输出**：平面方程、误差统计、拟合可视化
+
+### 命令行参数说明
+| 参数           | 简写 | 类型   | 默认值 | 说明                     |
+|----------------|------|--------|--------|--------------------------|
+| --threshold_mm | -t   | float  | 0.5    | 平面距离阈值（mm）|
+| --max_iterations | -i | int    | 2000   | RANSAC迭代次数           |
+
+### 运行示例
+```bash
+# 默认运行
+python plane_estimation.py
+
+# 自定义参数
+python plane_estimation.py --threshold_mm 0.3 --max_iterations 1500
+```
+
+### 计算说明
+1. 支持生成带噪声标准平面用于测试
+2. 输出平面法向量与理想Z轴夹角误差、偏移误差、拟合RMSE
+
+---
+
+## 七、点云配准与适应度评估（point-fitness.py）
+### 功能说明
+对点云执行旋转/平移变换，通过RANSAC+ICP完成高精度配准，输出配准适应度Fitness、RMSE，并计算配准后点云到参考网格的距离，用于评估配准精度与零件偏差。
+
+### 输入输出
+- **输入**：待配准PLY点云、参考STL网格
+- **输出**：变换矩阵、配准分数、误差、点云到网格距离统计、配准可视化
+
+### 命令行参数说明
+| 参数         | 简写 | 类型   | 默认值                                      | 说明               |
+|--------------|------|--------|---------------------------------------------|--------------------|
+| --ply_path   | -p   | string | ./High_Speed_Data/Noise_PointCloud/11_noisy.ply | 点云路径       |
+| --mesh_path  | -m   | string | ./High_Speed_Data/Mesh/11.stl               | 网格路径           |
+| --voxel_size | -v   | float  | 10                                          | 配准下采样大小     |
+| --no_visualize | —  | bool   | False                                       | 关闭可视化         |
+
+### 运行示例
+```bash
+# 完整配准+距离计算
+python point-fitness.py -p "High_Speed_Data/Noise_PointCloud/11_noisy.ply" -m "High_Speed_Data/Mesh/11.stl" -v 5
+
+# 无可视化
+python point-fitness.py -p "High_Speed_Data/Noise_PointCloud/11_noisy.ply" -m "High_Speed_Data/Mesh/11.stl" --no_visualize
+```
+
+### 计算说明
+1. 支持指定XYZ三轴旋转与随机平移
+2. RANSAC粗配准 → ICP精配准
+3. 输出Fitness（越高越好）、RMSE（越低越好）
+
+---
+
+## 八、完整工作流程示例（任务11全流程）
+1. CAD转轻量化网格
+```bash
+python CAD2Mesh.py -p 0.5 -i "High_Speed_Data/CAD/11.step" -o "High_Speed_Data/Mesh/11.stl"
+```
+2. 点云去噪预处理
+```bash
+python denoise.py -p "High_Speed_Data/PointCloud/11.ply" --noise_std 2.0
+```
+3. 平面基准拟合
+```bash
+python plane_estimation.py
+```
+4. 曲率特征分析
+```bash
+python curvature_estimation.py --ply_path "High_Speed_Data/PointCloud/11.ply"
+```
+5. 轮廓-平整度测量
+```bash
+python Contour_Flatness.py --tasks "13,31,40" --data_root "High_Speed_Data" --excel_output "vis/flatness.xlsx" --candidate_triangle_count 32
+```
+6. 点云配准评估
+```bash
+python point-fitness.py -p "High_Speed_Data/Noise_PointCloud/11_noisy.ply" -m "High_Speed_Data/Mesh/11.stl"
+```
+
+---
+
+## 九、常见问题
+1. STEP文件读取失败：检查路径、文件完整性、OCC Core安装
+2. 点云读取报错：安装open3d（`pip install open3d`）
+3. CUDA Out of Memory：减小分块大小或降低点云密度
+4. 去噪效果差：调小SOR标准差、增大ROR半径
+5. 平面拟合失败：提高RANSAC迭代次数、降低距离阈值
+6. 配准Fitness低：减小voxel_size，降低旋转/平移幅度
+7. 可视化无窗口：服务器环境加`--no_visualize`参数