massive-cloud/alg/train_measurement_system_v3.2_0629/README.md

# 列车点云测量系统 V3

基于配置驱动的点云测量系统，支持多种测量任务类型和ROI提取方法。通过YAML配置文件定义测量任务，自动完成ROI提取、平面拟合、孔中心检测、距离计算，并生成Excel报告和可视化点云文件。

## 项目结构

```
train_measurement_system_v3_0626/
├── main.py                        # 主程序入口
├── requirements.txt               # 依赖清单
├── setup.py                       # 安装脚本
├── pyproject.toml                # 项目配置
├── README.md                      # 本文件
├── config/                        # 配置文件目录
│   ├── measurements.yaml     # 主配置文件
├── src/                           # 源代码目录
│   ├── __init__.py
│   ├── config_loader.py           # 配置加载器
│   ├── task_manager.py            # 任务管理器
│   ├── pointcloud_loader.py       # 点云加载器
│   ├── roi_extractor.py           # ROI提取器
│   ├── plane_fitter.py            # 平面拟合器（RANSAC）
│   ├── hole_detector.py           # 高精度孔检测器 V2
│   ├── hole_center_fitter.py      # 孔中心拟合适配器
│   ├── excel_exporter.py          # Excel结果导出器
│   ├── visualizer.py              # 可视化工具
│   ├── performance_logger.py      # 性能日志记录器
│   ├── measurement_logger.py      # 详细测量日志记录器
│   ├── measurements/              # 测量类型模块
│   │   ├── __init__.py
│   │   ├── base.py                # 测量任务基类
│   │   ├── plane_distance.py      # 平面到平面距离测量
│   │   ├── point_to_plane.py      # 点到平面距离测量
│   │   ├── point_to_point.py      # 点到点距离测量
│   │   ├── plane_with_holes.py    # 带孔平面测量
│   │   ├── point_to_plane_with_holes.py
│   │   └── point_to_point_with_holes.py
│   └── spatial_index/             # 空间索引模块（ROI提取优化）
│       ├── __init__.py
│       ├── base.py                # 索引基类
│       ├── linear_scan.py         # 线性扫描（无索引）
│       ├── grid_index.py          # Grid网格索引
│       ├── grid_index_optimized.py # Grid网格索引（优化版）
│       ├── octree_index.py        # Octree八叉树索引
│       └── kdtree_index.py        # KDTree索引
├── results/                       # 测量结果输出目录（自动创建）
└── visualizations/                # 可视化点云输出目录（自动创建）
```

## 功能特性

- **配置驱动**: 通过YAML配置文件定义测量任务，无需修改代码
- **多任务类型**: 支持平面到平面、点到平面、点到点三种测量类型，以及带孔中心检测的测量
- **多种ROI提取方法**: Linear、Grid、Grid优化版、Octree、KDTree，性能和精度可调
- **高精度孔检测**: 基于RANSAC和几何优化的孔中心检测算法（V2），精度<0.1mm
- **宽度差值检查**: 支持门口宽度差值自动检查（任务19）
- **批量处理**: 一次运行可执行多个测量任务，点云只加载一次
- **自动可视化**: 可选保存每个任务的ROI点云（PLY格式）
- **结果导出**: 自动生成格式化的Excel报告和详细日志
- **鲁棒性强**: RANSAC平面拟合，自动处理离群点和噪声
- **性能优化**: 点云缓存、空间索引加速、详细性能分析报告
- **错误处理**: 单个任务失败不影响其他任务执行

## 环境要求

- Python 3.9+
- 推荐使用 conda 环境管理

## 快速开始

### 1. 创建并激活环境

```bash
# 创建 conda 环境
conda create -n pcc-measurement python=3.9
conda activate pcc-measurement
```

### 2. 安装依赖

**方式一：使用 requirements.txt**
```bash
pip install -r requirements.txt
```

**方式二：安装项目**
```bash
# 正常安装
pip install .

# 或开发模式安装（代码修改立即生效）
pip install -e .
```

### 3. 准备点云文件

确保你有完整的列车点云文件（PLY格式），例如：
```
/path/to/your/train_pointcloud.ply
```

### 4. 配置测量任务

编辑 `config/measurements.yaml`，设置点云文件路径和测量任务。

**基本配置示例：**

```yaml
# 点云文件路径（支持相对路径或绝对路径）
pointcloud_file: "/path/to/your/train_pointcloud.ply"

# ROI提取方法配置
roi_extraction:
  method: "grid"              # 可选: linear, grid, octree, kdtree
  grid_size: 100.0            # Grid方法的网格大小（mm）
  use_optimized: true         # 使用优化版Grid（numpy向量化）

# 测量任务列表
tasks:
  - name: "任务43_窗口下沿高度"
    type: "plane_to_plane"
    enabled: true
    description: "测量窗口下沿到地面的距离"
    theoretical_dimension: 803
    tolerance:
      upper: 6.5
      lower: -4

    source_roi:
      bbox_min: [5562, 1981, 1672]
      bbox_max: [6772, 1983, 1677]

    target_roi:
      bbox_min: [-10222, 1179, -302]
      bbox_max: [12428, 1181, 302]

    params:
      sample_points: 100
      ransac_threshold: 0.5
      ransac_max_iterations: 1000
      min_inlier_ratio: 0.6

    visualization: false         # 是否保存可视化点云
```

### 5. 运行测量

```bash
# 使用默认配置文件
python main.py

# 指定配置文件
python main.py -c config/measurements.yaml

# 指定点云文件（覆盖配置文件中的路径）
python main.py -p /path/to/your/pointcloud.ply

# 指定输出目录
python main.py -o /path/to/output

# 组合使用
python main.py -c config/measurements.yaml -o results/
```

**命令行参数：**
- `-c, --config`: 配置文件路径
- `-p, --pointcloud`: 点云文件路径（覆盖配置文件）
- `-o, --output`: 结果输出目录（默认: results/）

### 6. 查看结果

**Excel报告：** 保存在 `results/` 目录下
- 文件名格式：`measurement_results_YYYYMMDD_HHMMSS.xlsx`
- 包含每个任务的详细统计信息：
  - 项目名称、理论尺寸、公差要求
  - 测量结果（平均距离）、精度（标准差）
  - 误差范围、测量结论（通过/不通过）
  - 执行时间、错误信息（如有）

**详细日志：** `measurement_detail_YYYYMMDD_HHMMSS.log`
- 每个任务的详细执行过程
- ROI提取信息、RANSAC拟合详情
- 宽度差值检查详情（如适用）

**性能报告：** `performance_YYYYMMDD_HHMMSS.log`
- 各任务执行时间
- 详细的时间分布（ROI提取、平面拟合、距离计算等）
- 空间索引构建时间和方法

**可视化点云：** 保存在 `visualizations/` 目录下
- 文件格式：PLY
- 可使用CloudCompare或Open3D查看
- 用于验证ROI提取和测量点位置

## 测量类型

### 1. plane_to_plane（平面到平面距离）

从源平面采样点，计算到目标平面的距离。适用于测量车门高度、车体长度、窗口高度等。

### 2. point_to_plane（点到平面距离）

测量指定点到参考平面的距离。支持精确坐标查找和包围盒筛选模式。

### 3. point_to_point（点到点距离）

测量点对之间的欧氏距离。支持对称点自动配对。

### 4. 带孔中心检测的测量

支持基于孔中心的平面拟合和距离测量（`plane_with_holes`, `point_to_plane_with_holes`, `point_to_point_with_holes`）。

## ROI提取方法

系统支持多种空间索引方法，可在配置文件中选择：

- **linear**: 线性扫描（无索引）- 最简单，适合小点云
- **grid**: Grid网格索引 - 平衡性能和精度
- **grid (optimized)**: Grid网格索引优化版 - 使用numpy向量化，性能提升显著
- **octree**: Octree八叉树索引 - 适合大规模点云
- **kdtree**: KDTree索引 - 高效的空间查询

## 技术细节

### 平面拟合算法

系统使用Open3D的RANSAC算法进行平面拟合：
1. 随机采样3个点拟合平面
2. 统计内点（距离小于阈值）
3. 迭代优化选择最佳平面
4. 使用所有内点进行最小二乘拟合（SVD）

**平面方程：** ax + by + cz + d = 0

### 孔检测算法

高精度孔检测器V2特点：
- 自动检测圆柱轴向
- 多次RANSAC粗拟合
- 高质量点筛选
- 几何拟合精化
- 圆心精度 < 0.1mm

### 距离计算

**点到平面距离：**
```
distance = |ax + by + cz + d|
```

**点到点距离（欧氏距离）：**
```
distance = sqrt((x2-x1)² + (y2-y1)² + (z2-z1)²)
```

## 性能优化

- **点云缓存**: 点云文件只加载一次，所有任务共享
- **空间索引**: 使用Grid/Octree/KDTree加速ROI提取
- **自动降采样**: ROI超过10000点时自动降采样
- **并行安全**: 多个任务顺序执行，单个任务失败不影响其他任务

## 依赖包

- `numpy>=2.0.0` - 数值计算
- `open3d>=0.18.0` - 点云处理
- `scipy>=1.10.0` - 科学计算
- `pandas>=2.0.0` - 数据处理
- `openpyxl>=3.1.0` - Excel导出
- `PyYAML>=6.0.0` - 配置文件解析
- `matplotlib>=3.7.0` - 可视化（可选）
- `plotly>=5.0.0` - 可视化（可选）

## 版本更新

### V3 (2024-06-26)
- 重构代码结构，模块化更清晰
- 集成高精度孔检测器V2到src目录
- 优化导入路径，移除路径hack
- 精简配置文件
- 更新文档

---

**开发环境：** Python 3.9+
**推荐工具：** CloudCompare（点云查看）、VS Code（代码编辑）