# SAM2 Crack500 评估项目

使用 SAM2（Segment Anything Model 2）在 Crack500 数据集上进行裂缝分割评估。

## 📋 项目概述

本项目实现了 **方式 1：基于边界框提示（Bounding Box Prompting）** 来评估 SAM2 在混凝土裂缝分割任务上的性能。

### 核心思路

1. 从 Ground Truth 掩码中提取裂缝区域的边界框（连通域分析）
2. 将边界框作为提示输入 SAM2 模型
3. 评估 SAM2 的分割结果与 GT 的差异
4. 计算多种评估指标（IoU, Dice, F1-Score 等）

## 🏗️ 项目结构

```
sam_crack/
├── crack500/                    # Crack500 数据集
│   ├── test.txt                 # 测试集文件列表
│   ├── testcrop/                # 测试图像
│   └── testdata/                # 测试掩码
├── sam2/                        # SAM2 模型库
│   └── checkpoints/             # 模型权重
├── src/                         # 源代码
│   ├── bbox_prompt.py           # 边界框提示推理
│   ├── evaluation.py            # 评估指标计算
│   └── visualization.py         # 可视化工具
├── results/                     # 结果输出
│   └── bbox_prompt/
│       ├── predictions/         # 预测掩码
│       ├── visualizations/      # 可视化图像
│       ├── evaluation_results.csv
│       └── evaluation_summary.json
├── run_bbox_evaluation.py       # 主运行脚本
└── README.md                    # 本文件
```

## 🚀 快速开始

### 1. 环境准备

确保已安装 SAM2 和相关依赖：

```bash
# 激活 conda 环境
conda activate sam2

# 安装额外依赖
pip install opencv-python scikit-image pandas matplotlib seaborn tqdm
```

### 2. 下载模型权重

```bash
cd sam2/checkpoints
./download_ckpts.sh
cd ../..
```

或手动下载：

- [sam2.1_hiera_small.pt](https://dl.fbaipublicfiles.com/segment_anything_2/092824/sam2.1_hiera_small.pt)

### 3. 运行完整评估

```bash
# 运行完整流程（推理 + 评估 + 可视化）
python run_bbox_evaluation.py

# 或使用自定义参数
python run_bbox_evaluation.py \
    --checkpoint ./sam2/checkpoints/sam2.1_hiera_small.pt \
    --expand_ratio 0.05 \
    --num_vis 20
```

### 4. 查看结果

```bash
# 评估结果
cat results/bbox_prompt/evaluation_summary.json

# 可视化图像
ls results/bbox_prompt/visualizations/
```

## 🧩 TaskRunner 工作流

项目已经迁移到任务编排模式，`run_bbox_evaluation.py` / `run_point_evaluation.py` 会在内部构建 `TaskRunner`：

- **边界框评估**（推理 + 评估 + 可视化）  
  ```bash
  python run_bbox_evaluation.py --data_root ./crack500 --test_file ./crack500/test.txt \
      --expand_ratio 0.05 --output_dir ./results/bbox_prompt
  ```
- **点提示多实验**（默认对 1/3/5 点进行评估，可通过 `--point_configs` / `--per_component` 调整）  
  ```bash
  python run_point_evaluation.py --data_root ./crack500 --test_file ./crack500/test.txt \
      --point_configs 1 3 5 --per_component
  ```
- **直接运行 TOML 任务**：在 `tasks/` 目录提供了 `bbox_eval.toml`、`point_eval.toml` 模板，可按需修改数据路径或 `extra_params` 然后执行  
  ```bash
  python -m src.tasks.run_task --task_file tasks/bbox_eval.toml
  ```

所有任务都会依赖 `ConfigRegistry` 中的配置（默认 `sam2_bbox_prompt`），如需自定义数据集位置或提示模式，可在 CLI 中通过参数覆盖，或在 TOML 的 `[task.dataset_overrides]` / `[task.dataset_overrides.extra_params]` 区域修改。

## 📊 评估指标

本项目计算以下评估指标：

| 指标             | 说明                                     |
| ---------------- | ---------------------------------------- |
| **IoU**          | Intersection over Union，交并比          |
| **Dice**         | Dice 系数，医学图像常用指标              |
| **Precision**    | 精确率，预测为正的样本中真正为正的比例   |
| **Recall**       | 召回率，真实为正的样本中被正确预测的比例 |
| **F1-Score**     | Precision 和 Recall 的调和平均           |
| **Skeleton IoU** | 骨架 IoU，针对细长裂缝的特殊指标         |

## 🎯 命令行参数

```bash
python run_bbox_evaluation.py --help
```

### 主要参数

| 参数             | 默认值                                     | 说明                 |
| ---------------- | ------------------------------------------ | -------------------- |
| `--data_root`    | `./crack500`                               | 数据集根目录         |
| `--test_file`    | `./crack500/test.txt`                      | 测试集文件           |
| `--checkpoint`   | `./sam2/checkpoints/sam2.1_hiera_small.pt` | 模型权重路径         |
| `--model_cfg`    | `sam2.1_hiera_s.yaml`                      | 模型配置文件         |
| `--output_dir`   | `./results/bbox_prompt`                    | 输出目录             |
| `--expand_ratio` | `0.05`                                     | 边界框扩展比例（5%） |
| `--num_vis`      | `20`                                       | 可视化样本数量       |
| `--vis_all`      | `False`                                    | 是否可视化所有样本   |

### 流程控制参数

| 参数                   | 说明                         |
| ---------------------- | ---------------------------- |
| `--skip_inference`     | 跳过推理步骤（使用已有预测） |
| `--skip_evaluation`    | 跳过评估步骤                 |
| `--skip_visualization` | 跳过可视化步骤               |

### 使用示例

```bash
# 只运行推理
python run_bbox_evaluation.py --skip_evaluation --skip_visualization

# 只运行评估（假设已有预测结果）
python run_bbox_evaluation.py --skip_inference --skip_visualization

# 使用不同的边界框扩展比例
python run_bbox_evaluation.py --expand_ratio 0.1

# 可视化所有样本
python run_bbox_evaluation.py --skip_inference --skip_evaluation --vis_all
```

## 📈 结果示例

### 评估结果统计

```
============================================================
评估结果统计:
============================================================
IoU            : 0.7234 ± 0.1456
Dice           : 0.8123 ± 0.1234
Precision      : 0.8456 ± 0.1123
Recall         : 0.7890 ± 0.1345
F1-Score       : 0.8156 ± 0.1234
Skeleton IoU   : 0.6789 ± 0.1567
============================================================
```

### 可视化说明

生成的可视化图像包含 4 个子图：

1. **Original Image**: 原始图像
2. **Ground Truth**: 真实掩码
3. **Prediction**: SAM2 预测掩码
4. **Overlay Visualization**: 叠加可视化
   - 🟡 黄色：True Positive（正确预测）
   - 🟢 绿色：False Negative（漏检）
   - 🔴 红色：False Positive（误检）

## 🔧 模块说明

### 1. bbox_prompt.py

边界框提示推理模块，核心功能：

- `extract_bboxes_from_mask()`: 从 GT 掩码提取边界框
- `predict_with_bbox_prompt()`: 使用边界框提示进行 SAM2 预测
- `process_test_set()`: 批量处理测试集

### 2. evaluation.py

评估指标计算模块，核心功能：

- `compute_iou()`: 计算 IoU
- `compute_dice()`: 计算 Dice 系数
- `compute_precision_recall()`: 计算 Precision 和 Recall
- `compute_skeleton_iou()`: 计算骨架 IoU
- `evaluate_test_set()`: 批量评估测试集

### 3. visualization.py

可视化模块，核心功能：

- `create_overlay_visualization()`: 创建叠加可视化
- `create_comparison_figure()`: 创建对比图
- `visualize_test_set()`: 批量可视化测试集
- `create_metrics_distribution_plot()`: 创建指标分布图

## 🔬 技术细节

### 边界框生成策略

1. 使用 `cv2.connectedComponentsWithStats()` 进行连通域分析
2. 为每个连通域计算最小外接矩形
3. 可选：扩展边界框 N% 模拟不精确标注
4. 过滤面积小于阈值的噪声区域

### SAM2 推理流程

```python
# 1. 设置图像
predictor.set_image(image)

# 2. 使用边界框提示预测
masks, scores, logits = predictor.predict(
    box=bbox,
    multimask_output=False
)

# 3. 合并多个边界框的预测结果
combined_mask = np.logical_or(mask1, mask2, ...)
```

## 📝 注意事项

1. **GPU 内存**: 推荐使用至少 8GB 显存的 GPU
2. **模型选择**:
   - `sam2.1_hiera_tiny`: 最快，精度较低
   - `sam2.1_hiera_small`: 平衡速度和精度（推荐）
   - `sam2.1_hiera_large`: 最高精度，速度较慢
3. **边界框扩展**:
   - 0%: 严格边界框
   - 5%: 轻微扩展（推荐）
   - 10%: 较大扩展，模拟粗略标注

## 🐛 常见问题

### Q1: 模型加载失败

```bash
# 检查模型文件是否存在
ls -lh sam2/checkpoints/

# 重新下载模型
cd sam2/checkpoints && ./download_ckpts.sh
```

### Q2: CUDA 内存不足

```python
# 使用更小的模型
--checkpoint ./sam2/checkpoints/sam2.1_hiera_tiny.pt
--model_cfg sam2.1_hiera_t.yaml
```

### Q3: 导入错误

```bash
# 确保 SAM2 已正确安装
cd sam2
pip install -e .
```

## 📚 参考资料

- [SAM2 官方仓库](https://github.com/facebookresearch/sam2)
- [SAM2 论文](https://arxiv.org/abs/2408.00714)
- [Crack500 数据集](https://github.com/fyangneil/pavement-crack-detection)

## 📄 许可证

本项目遵循 MIT 许可证。SAM2 模型遵循 Apache 2.0 许可证。

## 🙏 致谢

- Meta AI 的 SAM2 团队
- Crack500 数据集作者