# 目标检测指标详解

本文档详细解释了 `EasyMetrics` 平台输出的各项检测指标含义，帮助你更好地理解模型性能。所有指标均遵循 COCO 评估标准。

## 1. 平均精度 (Average Precision, AP)

AP 是目标检测中最重要的指标，它综合了**精度 (Precision)** 和 **召回率 (Recall)**。

- **Precision (查准率)**: 预测为正样本中，真正正确的比例。 $P = \frac{TP}{TP + FP}$
- **Recall (查全率)**: 所有真实正样本中，被正确预测出的比例。 $R = \frac{TP}{TP + FN}$

我们使用 **IoU (Intersection over Union)** 来判定预测框是否正确。如果 `IoU(Pred, GT) >= 阈值`，则视为 TP (True Positive)。

### 主要指标

| 指标键名 | 含义 | 详细解释 |
| :--- | :--- | :--- |
| **mAP** | **平均 AP** | **最重要的综合指标**。它是在 IoU 阈值从 0.50 到 0.95（步长 0.05）共 10 个阈值下计算出的 AP 的平均值，并且对所有类别取平均。它反映了模型在不同严格程度下的综合表现。在 COCO 竞赛中简称为 AP。 |
| **mAP_50** | IoU=0.50 的 mAP | PASCAL VOC 竞赛的标准指标。只要求 IoU > 0.5 就算正确，相对宽松。 |
| **mAP_75** | IoU=0.75 的 mAP | 严格模式下的指标。要求检测框与真值重叠度很高才算正确。 |
| **AP_<class_id>** | 特定类别的 AP | 该类别的 Average Precision (IoU 0.5:0.95)。 |
| **AP_50_<class_id>** | 特定类别的 AP@50 | 该类别在 IoU=0.50 下的 AP。 |
| **AP_75_<class_id>** | 特定类别的 AP@75 | 该类别在 IoU=0.75 下的 AP。 |

### 不同尺度的 AP

为了分析模型对不同大小物体的检测能力，我们将物体按面积（像素数）分为三类：

| 指标键名 | 含义 | 定义 (面积 = 宽 × 高) |
| :--- | :--- | :--- |
| **mAP_s** | 小目标 mAP | 面积 < $32^2$ (小于 1024 像素) |
| **mAP_m** | 中目标 mAP | $32^2 \le$ 面积 < $96^2$ (1024 ~ 9216 像素) |
| **mAP_l** | 大目标 mAP | 面积 $\ge 96^2$ (大于 9216 像素) |

通常小目标检测 (mAP_s) 是最难的。

## 2. 平均召回率 (Average Recall, AR)

AR 反映了模型发现目标的能力，不考虑分数的排序，主要关注有多少真值被覆盖了。

EasyMetrics 按照每张图片允许的最大检测数 (Max Dets) 来计算 AR：

| 指标键名 | 含义 | 详细解释 |
| :--- | :--- | :--- |
| **AR_1** | MaxDets=1 的 AR | 每张图只取置信度最高的 1 个框来计算召回率。 |
| **AR_10** | MaxDets=10 的 AR | 每张图取前 10 个框计算召回率。 |
| **AR_100** | MaxDets=100 的 AR | 每张图取前 100 个框计算召回率。通常接近模型能达到的召回率上限。 |

## 3. 计算细节

1. **101点插值法**:
   我们在计算 AP 时，采用 COCO 标准的 101 点插值法。即在 recall = [0.00, 0.01, ..., 1.00] 这 101 个点上取对应的最大 precision 并求平均。这比传统的 11 点插值法更精确。

2. **多尺度评估逻辑**:
   - 计算 `mAP_s` 时，我们只保留真实面积在 `[0, 32^2)` 范围内的 GT，并且只考虑面积在该范围内的预测框。
   - 如果某张图片没有该尺度的目标，则不参与该尺度的计算。

## 4. 总结建议

### 通用场景

- **如果只看一个数**: 关注 **mAP**。
- **如果定位精度很重要**: 关注 **mAP_75**。
- **如果漏检代价很大** (如自动驾驶): 关注 **AR_100**。
- **如果发现小物体检测很差**: 关注 **mAP_s**，可能需要调整数据增强或模型结构。

### 具体应用场景的指标选择

#### 1. 自动驾驶

**关键指标**: `mAP_50`, `mAP_75`, `AR_100`

**选择理由**:
- 自动驾驶场景对安全性要求极高，漏检代价巨大，因此需要关注 `AR_100` 确保高召回率
- 同时，定位精度也很重要，特别是对于行人、车辆等关键目标，需要关注 `mAP_75`
- `mAP_50` 作为基础指标，确保模型在宽松条件下的基本性能

#### 2. 安防监控

**关键指标**: `mAP_75`, `AR_100`, `mAP_s`

**选择理由**:
- 安防监控需要高精度的目标定位，因此关注 `mAP_75`
- 漏检可能导致安全隐患，因此需要关注 `AR_100`
- 监控场景中常常包含远距离小目标，因此需要关注 `mAP_s`

#### 3. 零售分析

**关键指标**: `mAP`, `mAP_50`, `mAP_m`

**选择理由**:
- 零售分析场景对整体性能要求均衡，因此关注 `mAP`
- 商品检测通常是中等大小目标，因此关注 `mAP_m`
- `mAP_50` 作为基础指标，确保模型在宽松条件下的基本性能

#### 4. 医疗影像

**关键指标**: `mAP_75`, `mAP_90`, `AR_10`

**选择理由**:
- 医疗影像对定位精度要求极高，因此关注 `mAP_75` 甚至 `mAP_90`
- 医疗场景中通常目标数量有限，因此关注 `AR_10` 而非 `AR_100`
- 假阳性可能导致不必要的检查，因此需要高精度的定位

#### 5. 工业检测

**关键指标**: `mAP_75`, `mAP_s`, `AR_100`

**选择理由**:
- 工业检测对缺陷定位精度要求高，因此关注 `mAP_75`
- 工业场景中常常包含微小缺陷，因此需要关注 `mAP_s`
- 漏检可能导致产品质量问题，因此需要关注 `AR_100`

### 模型开发阶段的指标关注

#### 1. 训练初期

**关注指标**: `mAP_50`

**理由**: 训练初期模型性能不稳定，`mAP_50` 作为宽松指标，能够快速反映模型的基本学习情况。

#### 2. 训练中期

**关注指标**: `mAP`, `mAP_75`

**理由**: 训练中期模型性能逐渐稳定，需要关注综合指标 `mAP` 和严格指标 `mAP_75`，评估模型的整体性能和定位精度。

#### 3. 训练后期

**关注指标**: `mAP_s`, `mAP_m`, `mAP_l`, `AR_100`

**理由**: 训练后期需要关注模型在不同尺度目标上的表现，以及召回率，确保模型的全面性能。

#### 4. 模型选择

**关注指标**: 根据具体应用场景选择相应的关键指标

**理由**: 不同应用场景对模型性能的要求不同，需要根据实际需求选择合适的指标进行模型评估和选择。

## 5. 最佳阈值推荐 (Best Score Suggestion)

### 功能说明

EasyMetrics 支持根据指定的精度 (Precision) 要求，自动寻找最佳的置信度阈值。这对于实际部署模型时设定阈值非常有帮助。

### 工作原理

最佳阈值推荐的工作原理是：

1. **生成候选阈值**：在 0-1 范围内生成一系列候选置信度阈值
2. **评估每个阈值**：对每个候选阈值，计算模型在该阈值下的精度
3. **寻找最佳阈值**：找到满足指定精度要求的最低置信度阈值
4. **按类别返回**：为每个类别独立计算最佳阈值

### 结果解读

| 指标键名 | 含义 | 详细解释 |
| :--- | :--- | :--- |
| **BestScore_IoU0.50_P0.90_<class_id>** | 满足精度要求的最低阈值 | 在 IoU=0.50 的评估标准下，为了让该类别的预测精度达到 90%，建议设置的最低置信度阈值。 |
| **BestScore_IoU0.75_P0.80_<class_id>** | 满足精度要求的最低阈值 | 在 IoU=0.75 的评估标准下，为了让该类别的预测精度达到 80%，建议设置的最低置信度阈值。 |

### 应用场景

#### 1. 模型部署

**使用场景**：将模型部署到生产环境时，需要设定合适的置信度阈值

**示例**：
- **安防监控**：要求 IoU=0.5 时精度至少达到 95%，以减少误报
- **零售分析**：要求 IoU=0.5 时精度至少达到 90%，以确保商品识别的准确性
- **医疗影像**：要求 IoU=0.75 时精度至少达到 95%，以确保诊断的可靠性

#### 2. 类别不平衡场景

**使用场景**：当数据集中类别分布不平衡时，为不同类别设置不同的阈值

**示例**：
- 对于稀有类别（如异常检测），可以设置较低的阈值以提高召回率
- 对于常见类别，可以设置较高的阈值以减少误报

#### 3. 动态阈值调整

**使用场景**：根据应用场景的不同需求，动态调整阈值

**示例**：
- 白天场景：光线充足，目标清晰，可以设置较高的阈值
- 夜晚场景：光线较暗，目标模糊，可以设置较低的阈值

### 使用方法

```python
# 场景 1: IoU=0.5 时精度至少达到 90%
results = evaluate_detection(
    preds, targets,
    score_criteria=[(0.5, 0.9)]  # 格式: [(iou阈值, 最低精度要求)]
)

# 获取类别 0 的最佳阈值
best_thresh = results.get('BestScore_IoU0.50_P0.90_0')
print(f"类别 0 的推荐阈值: {best_thresh}")

# 场景 2: 多个精度要求
results = evaluate_detection(
    preds, targets,
    score_criteria=[(0.5, 0.9), (0.75, 0.8)]
)

# 获取不同要求下的阈值
best_thresh_50 = results.get('BestScore_IoU0.50_P0.90_0')
best_thresh_75 = results.get('BestScore_IoU0.75_P0.80_0')
print(f"IoU=0.5, P>=0.9 阈值: {best_thresh_50}")
print(f"IoU=0.75, P>=0.8 阈值: {best_thresh_75}")
```

### 阈值调优技巧

1. **从宽松到严格**：先设置宽松的精度要求，然后逐步提高，观察阈值的变化

2. **结合业务需求**：根据业务场景的具体需求，设置合理的精度要求

3. **考虑召回率**：设置阈值时需要平衡精度和召回率，根据业务需求确定优先级

4. **定期更新**：随着模型的迭代和数据的变化，定期重新计算最佳阈值

5. **可视化分析**：可以将不同阈值下的精度-召回率曲线可视化，帮助选择最佳阈值

### 实际应用示例

#### 安防监控场景

```python
# 安防监控要求高精度，减少误报
results = evaluate_detection(
    preds, targets,
    score_criteria=[(0.5, 0.95), (0.75, 0.9)]
)

# 获取不同要求下的阈值
thresh_50 = results.get('BestScore_IoU0.50_P0.95_0')  # 行人
thresh_50_vehicle = results.get('BestScore_IoU0.50_P0.95_1')  # 车辆

print(f"行人类别推荐阈值: {thresh_50}")
print(f"车辆类别推荐阈值: {thresh_50_vehicle}")
```

#### 自动驾驶场景

```python
# 自动驾驶要求高召回率，减少漏检
results = evaluate_detection(
    preds, targets,
    score_criteria=[(0.5, 0.85), (0.75, 0.75)]
)

# 获取不同要求下的阈值
thresh_50 = results.get('BestScore_IoU0.50_P0.85_0')  # 行人
thresh_50_vehicle = results.get('BestScore_IoU0.50_P0.85_1')  # 车辆

print(f"行人类别推荐阈值: {thresh_50}")
print(f"车辆类别推荐阈值: {thresh_50_vehicle}")
```
