引用

如果您在研究中使用此代码，请考虑引用以下内容：

@Article{electronics10030279,
AUTHOR = {Padilla, Rafael and Passos, Wesley L. and Dias, Thadeu L. B. and Netto, Sergio L. and da Silva, Eduardo A. B.},
TITLE = {一种基于开源工具包的对象检测指标比较分析},
JOURNAL = {Electronics},
VOLUME = {10},
YEAR = {2021},
NUMBER = {3},
ARTICLE-NUMBER = {279},
URL = {https://www.mdpi.com/2079-9292/10/3/279},
ISSN = {2079-9292},
DOI = {10.3390/electronics10030279}
}

您可以通过此处或此处下载该论文。

@INPROCEEDINGS {padillaCITE2020,
    author    = {R. {Padilla} and S. L. {Netto} and E. A. B. {da Silva}},
    title     = {目标检测算法性能指标综述}, 
    booktitle = {2020年国际系统、信号与图像处理会议（IWSSIP）}, 
    year      = {2020},
    pages     = {237-242},}

您可以通过此处下载该论文。

---

注意！本工具的新版本已在这里发布。

新版本包含所有COCO指标，支持其他文件格式，提供一个用户界面（UI）来指导评估过程，并引入了用于评估视频中目标检测的STT-AP指标。

---

目标检测指标

本项目的出发点在于，不同研究和实现之间对于目标检测问题的评价指标缺乏共识。尽管在线竞赛会采用各自的指标来评估目标检测任务，但只有少数竞赛提供了用于计算检测精度的参考代码片段。
希望使用不同于竞赛所提供数据集的研究人员，往往需要自行实现相应的指标计算方法。然而，错误或不一致的实现方式可能会导致结果偏差。理想情况下，为了确保不同方法之间的可比性，有必要开发一种灵活且通用的实现方案，以便无论使用何种数据集都能进行准确的基准测试。

本项目提供易于使用的函数，实现了当前最流行的目标检测竞赛所采用的相同指标。我们的实现无需对您的检测模型进行复杂输入格式的修改，也避免了将数据转换为XML或JSON文件的麻烦。我们简化了输入数据（真实框和预测框），并将学术界及各类挑战赛中常用的主流指标整合到一个统一的项目中。经过与官方实现的仔细对比，我们的结果完全一致。

在下文中，您将找到关于不同竞赛和研究中常用指标的概述，以及如何使用我们代码的示例。

目录

• 项目背景
• 不同竞赛，不同指标
• 重要定义
• 指标
  • 精确率-召回率曲线
  • 平均精度
    • 11点插值法
    • 全点插值法
• 如何使用本项目
• 参考文献

不同竞赛，不同指标

• PASCAL VOC挑战赛 提供了一个Matlab脚本，用于评估检测结果的质量。参赛者可以在提交结果之前，利用该脚本测量其检测精度。有关其目标检测指标标准的官方文档可在此处查阅。目前PASCAL VOC目标检测挑战赛所采用的指标包括精确率-召回率曲线和平均精度。
  PASCAL VOC的Matlab评估代码从XML文件中读取真实框，若要将其应用于其他数据集或特定场景，则需对代码进行相应修改。尽管像Faster-RCNN这样的项目已经实现了PASCAL VOC的评估指标，但仍需将检测到的边界框转换为特定格式。TensorFlow框架也提供了PASCAL VOC指标的实现。

• COCO目标检测挑战赛 使用不同的指标来评估各种算法的目标检测精度。在这里可以找到一份文档，详细介绍了用于表征COCO数据集上目标检测器性能的12种指标。该竞赛提供了Python和Matlab代码，方便用户在提交结果前验证自己的分数。不过，仍需将结果转换为竞赛要求的特定格式。

• Google Open Images Dataset V4竞赛 同样使用500个类别的平均精度（mAP）来评估目标检测任务。

• ImageNet物体定位挑战赛 根据每个图像的真实框与预测框之间的类别匹配情况及重叠区域大小来计算误差。最终的总误差是所有测试图像中最小误差的平均值。此处提供了更多关于其评估方法的详细信息。

重要定义

交并比（IOU）

交并比（IOU）是一种基于Jaccard指数的度量方法，用于评估两个边界框之间的重叠程度。它需要一个真实边界框 和一个预测边界框 。通过计算IOU，我们可以判断检测结果是否有效（真正例）或无效（假正例）。

IOU的计算公式是：预测边界框与真实边界框的交集面积除以它们的并集面积：  

下图展示了真实边界框（绿色）与检测到的边界框（红色）之间的IOU。

真正例、假正例、假负例和真负例

指标中使用的一些基本概念：

• 真正例（TP）：正确的检测。IOU ≥ 阈值 的检测
• 假正例（FP）：错误的检测。IOU < 阈值 的检测
• 假负例（FN）：未被检测到的真实目标
• 真负例（TN）：不适用。它表示对误检的纠正。在目标检测任务中，图像中有很多不应被检测到的候选边界框。因此，TN将代表所有正确未被检测到的候选边界框（即图像中的大量可能边界框）。这就是为什么该指标不使用真负例的原因。

阈值：根据不同的指标，通常设置为50%、75%或95%。

精确率

精确率是指模型仅识别相关目标的能力。它是正确正例预测所占的百分比，计算公式如下：

召回率

召回率是指模型找到所有相关样本（所有真实边界框）的能力。它是真正例占所有相关真实目标的百分比，计算公式如下：

指标

在下面的主题中，我们将介绍一些用于目标检测的最常用指标。

精确率-召回率曲线

精确率-召回率曲线是一种很好的方式，可以通过绘制每个类别对象的曲线来评估目标检测器在不同置信度下的性能。如果随着召回率的增加，精确率仍然保持较高，则认为该类别的目标检测器表现良好。这意味着当调整置信度阈值时，精确率和召回率仍能维持在较高水平。另一种判断优秀目标检测器的方法是寻找能够仅识别相关目标（假正例为0，即高精确率），同时又能找到所有真实目标（假负例为0，即高召回率）的检测器。

而性能较差的目标检测器则需要通过增加检测到的对象数量（从而导致假正例增多，精确率降低）来获取所有真实目标（高召回率）。因此，精确率-召回率曲线通常从较高的精确率开始，随着召回率的增加而逐渐下降。您可以在下一节（平均精度）中看到精确率-召回率曲线的示例。这种类型的曲线被PASCAL VOC 2012挑战赛所采用，并且在我们的实现中也有提供。

平均精度

比较目标检测器性能的另一种方法是计算精确率-召回率曲线下的面积（AUC）。由于AP曲线通常是上下波动的锯齿状曲线，在同一张图上比较不同曲线（即不同检测器）往往并不容易——因为这些曲线经常会相互交叉。因此，平均精度（AP）这一数值型指标也可以帮助我们比较不同的检测器。实际上，AP是在召回率从0到1的所有取值范围内对精确率求平均得到的值。

自2010年起，PASCAL VOC挑战赛计算AP的方法发生了变化。目前，PASCAL VOC挑战赛采用的插值方法会使用所有数据点，而不是像其论文中所述那样仅插值11个等间距的点。为了重现他们的默认实现，我们的默认代码（见后文）遵循他们最新的应用方式（插值所有数据点）。不过，我们也提供了11点插值的方法。

11点插值

11点插值试图通过在一组11个等间距的召回率水平 [0, 0.1, 0.2, ... , 1] 上对精确率求平均来概括精确率-召回率曲线的形状：

其中

这里 是在召回率 处测得的精确率。

与直接使用每个点的精确率不同，AP是通过对11个召回率 进行插值来获得的，取的是召回值大于 的最大精确率。

插值所有点

与其仅在11个等间距的点上进行插值，你也可以通过所有点来进行插值，使得：

其中

这里是在召回率下的实测精度。

在这种情况下，不再只使用少数几个点上的精度，而是通过对每个级别的精度进行插值来计算AP，即取那些召回值大于或等于的最高精度。这样我们就能计算出曲线下方的估计面积。

为了更清楚地说明，我们提供了一个比较两种插值方法的示例。

一个图解示例

通过一个例子可以帮助我们更好地理解插值平均精度的概念。考虑以下检测结果：

这里有7张图片，共包含15个真实标注目标（用绿色框表示）和24个检测到的目标（用红色框表示）。每个检测到的目标都有一个置信度，并用字母（A, B, ..., Y）来标识。

下表展示了各个边界框及其对应的置信度。最后一列标明了这些检测是TP还是FP。在这个例子中，如果IOU 30%，则视为TP；否则为FP。通过观察上面的图片，我们可以大致判断哪些检测是TP，哪些是FP。

在某些图片中，多个检测框会与同一个真实标注框重叠（图片2、3、4、5、6和7）。对于这种情况，我们以具有最高IOU的预测框作为TP（例如，在图片1中，“E”是TP而“D”是FP，因为E与真实标注框的IOU大于D与真实标注框的IOU）。这一规则也适用于PASCAL VOC 2012指标：“例如，对单个物体的5次正确检测，只计为1次正确检测和4次错误检测”。

精确率与召回率曲线是通过计算累计TP或FP检测的精确率和召回率来绘制的。为此，我们首先需要按照置信度对检测结果进行排序，然后为每次累积检测计算精确率和召回率，如下表所示（请注意，对于召回率的计算，分母项（“累计TP + 累计FN”或“所有真实标注”）始终为15，因为无论检测结果如何，真实标注框的数量都是固定的）：

以第二行（图片7）为例进行计算：精确率 = TP/(TP+FP) = 1/2 = 0.5，召回率 = TP/(TP+FN) = 1/15 = 0.066。

绘制精确率和召回率的数值后，我们得到如下的精确率与召回率曲线：

正如前面提到的，测量插值平均精度有两种不同的方法：11点插值和对所有点进行插值。下面我们对这两种方法进行比较：

计算11点插值

11点插值平均精度的思想是在一组11个召回率水平（0, 0.1, ..., 1）上对精度进行平均。插值后的精度值通过取当前召回率以上所有召回率对应的最高精度来获得，具体如下：

通过应用11点插值法，我们得到：

计算所有点上的插值

通过对所有点进行插值，平均精度（AP）可以被解释为精度-召回率曲线的近似AUC。其目的是减少曲线中波动的影响。通过应用前面介绍的公式，我们可以计算出各个区域的面积，如下所示。此外，我们也可以通过观察从最高召回率（0.4666）到0的召回率变化（即从右向左看图），收集每个召回率对应的最高精度值，从而直观地看到插值后的精度点，如图下所示：

观察上图，我们可以将AUC分为4个区域（A1、A2、A3和A4）：

计算总面积后，即可得到AP：

两种不同插值方法的结果略有差异：每点插值法得到24.56%，而11点插值法得到26.84%。

我们的默认实现与PASCAL VOC一致，采用每点插值法。如果希望使用11点插值法，只需将使用参数method=MethodAveragePrecision.EveryPointInterpolation的函数改为method=MethodAveragePrecision.ElevenPointInterpolation即可。

若想复现这些结果，请参阅**示例2**。

如何使用本项目

本项目旨在以非常简便的方式评估你的检测结果。如果你希望使用最常用的目标检测指标来评估你的算法，那么这里正是你需要的地方。

示例1 和 示例2 是实际案例，展示了如何直接调用本项目的核心函数，从而在使用指标时提供更大的灵活性。但如果你不想花时间理解我们的代码，可以按照以下说明轻松评估你的检测结果：

请按照以下步骤开始评估你的检测结果：

1. 创建真实标注文件
2. 创建你的检测文件
3. 对于Pascal VOC指标，运行命令：python pascalvoc.py
   如果你想复现上面的例子，运行命令：python pascalvoc.py -t 0.3
4. （可选）你可以使用参数来控制IOU阈值、边界框格式等

创建真实标注文件

• 在文件夹**groundtruths/**中，为每张图片创建一个单独的真实标注文本文件。
• 每个文件中的每一行应采用以下格式： 。
• 例如，图像“2008_000034.jpg”的真实标注边界框在文件“2008_000034.txt”中表示如下：

  bottle 6 234 45 362
  person 1 156 103 336
  person 36 111 198 416
  person 91 42 338 500
  

如果你愿意，也可以使用 的格式（详见此处*的使用方法）。在这种情况下，“2008_000034.txt”将表示为：

bottle 6 234 39 128
person 1 156 102 180
person 36 111 162 305
person 91 42 247 458

创建你的检测文件

• 在文件夹**detections/**中，为每张图片创建一个单独的检测文本文件。
• 检测文件的名称必须与其对应的真实标注文件匹配（例如，“detections/2008_000182.txt”表示与“groundtruths/2008_000182.txt”相对应的检测结果）。
• 每个检测文件中的每一行应采用以下格式： （详见此处*的使用方法）。
• 例如，“2008_000034.txt”：

  bottle 0.14981 80 1 295 500  
  bus 0.12601 36 13 404 316  
  horse 0.12526 430 117 500 307  
  pottedplant 0.14585 212 78 292 118  
  tvmonitor 0.070565 388 89 500 196  
  

同样，如果你更喜欢，也可以使用 的格式。

可选参数

可选参数：

参数	描述	示例	默认值
-h, --help	显示帮助信息	python pascalvoc.py -h
-v, --version	检查版本	python pascalvoc.py -v
-gt, --gtfolder	包含真实框文件的文件夹	python pascalvoc.py -gt /home/whatever/my_groundtruths/	/Object-Detection-Metrics/groundtruths
-det, --detfolder	包含检测框文件的文件夹	python pascalvoc.py -det /home/whatever/my_detections/	/Object-Detection-Metrics/detections/
-t, --threshold	IOU 阈值，用于判断检测结果是真正例还是假正例	python pascalvoc.py -t 0.75	0.50
-gtformat	真实框坐标格式 *	python pascalvoc.py -gtformat xyrb	xywh
-detformat	检测框坐标格式 *	python pascalvoc.py -detformat xyrb	xywh
-gtcoords	真实框坐标参考。 如果标注的坐标是相对于图像尺寸的（如 YOLO 中使用），则设置为 rel。 如果坐标是绝对值，不依赖于图像尺寸，则设置为 abs	python pascalvoc.py -gtcoords rel	abs
-detcoords	检测框坐标参考。 如果坐标是相对于图像尺寸的（如 YOLO 中使用），则设置为 rel。 如果坐标是绝对值，不依赖于图像尺寸，则设置为 abs	python pascalvoc.py -detcoords rel	abs
-imgsize	图像尺寸，格式为 width,height <int,int>。 如果 -gtcoords 或 -detcoords 设置为 rel，则此参数为必填项	python pascalvoc.py -imgsize 600,400
-sp, --savepath	保存图表的文件夹	python pascalvoc.py -sp /home/whatever/my_results/	Object-Detection-Metrics/results/
-np, --noplot	如果存在，则执行过程中不显示任何图表	python pascalvoc.py -np	不显示。 因此，默认会显示图表

(*) 如果格式为 <left> <top> <width> <height>，则设置 -gtformat xywh 和/或 -detformat xywh。
如果格式为 <left> <top> <right> <bottom>，则设置 -gtformat xyrb 和/或 -detformat xyrb。

参考文献

• 精确率-召回率曲线与 ROC 曲线之间的关系（Jesse Davis 和 Mark Goadrich）
  威斯康星大学计算机科学系及生物统计学与医学信息学系
  http://pages.cs.wisc.edu/~jdavis/davisgoadrichcamera2.pdf

• PASCAL 视觉目标类别（VOC）挑战赛
  http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.157.5766&rep=rep1&type=pdf

• 排序检索结果的评估（Salton 和 McGill，1986 年）
  https://www.amazon.com/Introduction-Information-Retrieval-COMPUTER-SCIENCE/dp/0070544840
  https://nlp.stanford.edu/IR-book/html/htmledition/evaluation-of-ranked-retrieval-results-1.html

Object-Detection-Metrics 快速上手指南

Object-Detection-Metrics 是一个开源工具包，旨在统一并简化目标检测算法的性能评估。它实现了 PASCAL VOC、COCO 等主流竞赛使用的评估指标（如 mAP），无需将数据转换为复杂的 XML 或 JSON 格式，直接支持简单的文本输入。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：Python 3.6 或更高版本
• 前置依赖：
  • numpy
  • matplotlib (用于绘制 Precision-Recall 曲线)
  • scipy (可选，用于部分插值计算)

建议创建一个虚拟环境以避免依赖冲突：

python -m venv od_metrics_env
source od_metrics_env/bin/activate  # Windows 用户使用: od_metrics_env\Scripts\activate

安装依赖库：

pip install numpy matplotlib scipy
# 国内用户推荐使用清华源加速安装
# pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy matplotlib scipy

安装步骤

该项目主要通过直接克隆源码使用，无需通过 pip 安装包。

1. 克隆仓库：

   git clone https://github.com/rafaelpadilla/Object-Detection-Metrics.git
   cd Object-Detection-Metrics
   

2. 验证目录结构： 进入目录后，您应看到 metrics.py（核心逻辑）、samples（示例数据）等文件。

基本使用

该工具的核心使用流程分为三步：准备数据 -> 调用评估函数 -> 获取结果。

1. 数据格式准备

工具接受简单的文本文件或内存列表作为输入，无需转换格式。每行代表一个检测框或真实框。

格式说明： <image_name> <class_id> <confidence> <x_left> <y_top> <x_right> <y_bottom>

• Ground Truth (真实值)：confidence 字段通常设为 0 或忽略（代码中处理为无置信度）。
• Detections (预测值)：包含模型输出的置信度。

示例文件 (groundtruths.txt):

img_001 0 0 10 10 50 50
img_001 1 0 20 20 60 60
img_002 0 0 5 5 45 45

示例文件 (detections.txt):

img_001 0 0.95 12 12 52 52
img_001 0 0.80 100 100 150 150
img_002 0 0.85 6 6 46 46

2. 运行评估脚本

项目根目录下提供了示例脚本 main.py（或在 samples 文件夹中），您可以直接运行它来测试功能，或者参考其逻辑编写自己的评估代码。

直接运行示例：

python main.py

注：如果根目录没有直接的 main.py，请运行 python samples/sample_1.py (具体文件名视版本而定，通常 samples 目录下有演示如何加载 txt 文件并计算 mAP 的脚本)。

3. 代码集成示例

如果您想在 Python 代码中直接调用，可以参考以下简化逻辑：

from metrics import *

# 创建评估器对象
# 参数：IOU 阈值 (例如 0.5), 是否使用 COCO 风格评估等
evaluator = Evaluator()

# 添加真实框 (Ground Truth)
# 格式：(imageName, classId, x_left, y_top, x_right, y_bottom)
gt = GroundTruths()
gt.addGroundTruth("img_001", "class_0", 10, 10, 50, 50)

# 添加检测结果 (Detections)
# 格式：(imageName, classId, confidence, x_left, y_top, x_right, y_bottom)
det = Detections()
det.addDetection("img_001", "class_0", 0.95, 12, 12, 52, 52)

# 执行评估
results = evaluator.GetPascalVOCMetrics(gt, det, IOUThreshold=0.5)

# 打印平均精度 (AP)
for r in results:
    print(f"Class: {r['class']}, AP: {r['AP']}")
    
# 绘制 Precision-Recall 曲线 (可选)
plot_precision_recall_curve(results)

注意事项

• 坐标系统：默认支持 (x_left, y_top, x_right, y_bottom) 格式。
• 新版提示：如果您需要评估视频数据 (STT-AP) 或使用更完善的图形界面 (UI)，请参考 README 中提到的新版本仓库：review_object_detection_metrics。