sam_crack/README.md

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 和相关依赖：

# 激活 conda 环境
conda activate sam2

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

2. 下载模型权重

cd sam2/checkpoints
./download_ckpts.sh
cd ../..

或手动下载：

• sam2.1_hiera_small.pt

3. 运行完整评估

# 运行完整流程（推理 + 评估 + 可视化）
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. 查看结果

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

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

🧩 TaskRunner 工作流

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

• 边界框评估（推理 + 评估 + 可视化）

  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 调整）

  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 然后执行

  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，针对细长裂缝的特殊指标

🎯 命令行参数

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	跳过可视化步骤

使用示例

# 只运行推理
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 推理流程

# 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: 模型加载失败

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

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

Q2: CUDA 内存不足

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

Q3: 导入错误

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

📚 参考资料

• SAM2 官方仓库
• SAM2 论文
• Crack500 数据集

📄 许可证

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

🙏 致谢

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