# 使用说明

## 环境安装

### 1. 创建 Conda 环境
```bash
conda create -n pcc-experiment python=3.9
conda activate pcc-experiment
```

### 2. 安装依赖包

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

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

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

安装项目会自动安装所有依赖包，并将项目添加到 Python 环境中。

## 配置测量任务

编辑 `config/measurements.yaml` 文件：

### 1. 设置点云文件路径
```yaml
# 支持相对路径（相对于配置文件）或绝对路径
pointcloud_file: "../../head_train_pointcloud/train_2_100M.ply"
```

### 2. 配置测量任务
```yaml
tasks:
  - name: "任务名称"
    type: "plane_to_plane"  # 任务类型: plane_to_plane, point_to_plane, point_to_point
    enabled: true            # 是否启用
    description: "任务描述"
    visualization_dir: "visualizations"  # 可视化输出目录（可选）
    
    # 根据任务类型配置相应参数
    source_roi:
      bbox_min: [x_min, y_min, z_min]
      bbox_max: [x_max, y_max, z_max]
    
    target_roi:
      bbox_min: [x_min, y_min, z_min]
      bbox_max: [x_max, y_max, z_max]
    
    params:
      sample_points: 100
      ransac_threshold: 2.0
      ransac_max_iterations: 1000
      min_inlier_ratio: 0.6
```

## 运行测量

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

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

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

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

# 组合使用
python main.py -c config/custom.yaml -p data/train.ply -o results/
```

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

## 查看结果

### Excel 结果文件
位置: `results/measurement_results_YYYYMMDD_HHMMSS.xlsx`

包含内容:
- 任务名称、类型、描述
- 点位参数（ROI 范围、目标点坐标等）
- 测量数据（平均距离、标准差、最小/最大距离）
- 采样点数、ROI 点数、内点率
- 错误信息（如果失败）

### 可视化文件
位置: `visualizations/*.ply`

使用 CloudCompare 或 MeshLab 打开查看：
- 蓝色：源平面点云
- 绿色：目标平面点云
- 红色：采样点

## 常见问题

### 任务没有执行
检查配置文件中 `enabled: true` 是否设置

### 点云文件找不到
- 使用绝对路径，或
- 使用相对于配置文件的相对路径，或
- 使用 `-p` 参数指定点云文件

### 测量结果异常
- 检查 ROI 包围盒是否正确
- 查看 Excel 中的内点率（建议 >70%）
- 打开 PLY 文件检查 ROI 提取是否准确