303 lines
9.3 KiB
Markdown
303 lines
9.3 KiB
Markdown
# 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 数据集作者
|