Keras RetinaNet

Keras 中实现的 RetinaNet 目标检测模型，如 Tsung-Yi Lin、Priya Goyal、Ross Girshick、Kaiming He 和 Piotr Dollár 在论文《用于密集目标检测的焦点损失》（Focal Loss for Dense Object Detection）中所述。

:warning: 已弃用

此仓库已被弃用，建议使用 torchvision 模块。
该项目应能与 Keras 2.4 和 TensorFlow 2.3.0 兼容，更高版本可能会导致支持中断。
更多信息请参阅 此处。

安装

1. 克隆本仓库。
2. 在仓库目录下执行 pip install . --user。
   注意：由于 TensorFlow 的安装方式存在不一致性，本包未将 TensorFlow 定义为依赖项，因为这会导致尝试自动安装 TensorFlow（至少在 Arch Linux 上会导致错误安装）。请确保根据您的系统要求正确安装 TensorFlow。
3. 或者，您也可以直接从克隆的仓库运行代码，但需要先运行 python setup.py build_ext --inplace 编译 Cython 代码。
4. 如果希望在 MS COCO 数据集上进行训练或测试，可选择安装 pycocotools，方法是运行 pip install --user git+https://github.com/cocodataset/cocoapi.git#subdirectory=PythonAPI。

测试

网络测试的示例可在 此 Notebook 中查看。
通常，网络推理的流程如下：

boxes, scores, labels = model.predict_on_batch(inputs)

其中 boxes 的形状为 (None, None, 4)（表示 (x1, y1, x2, y2)），scores 的形状为 (None, None)（分类得分），labels 的形状为 (None, None)（与得分对应的标签）。在三个输出中，第一个维度表示批次大小，第二个维度索引检测结果列表。

加载模型的方式如下：

from keras_retinanet.models import load_model
model = load_model('/path/to/model.h5', backbone_name='resnet50')

在 NVIDIA Pascal Titan X 上，处理一张 1000x800x3 大小的图像大约需要 75 毫秒。

将训练模型转换为推理模型

keras-retinanet 的训练过程使用的是“训练模型”。这些模型相比“推理模型”进行了精简，仅包含训练所需的层（回归和分类分支）。如果您希望对模型进行推理（即在图像上执行目标检测），则需要将训练好的模型转换为推理模型。转换方法如下：

# 直接从仓库运行：
keras_retinanet/bin/convert_model.py /path/to/training/model.h5 /path/to/save/inference/model.h5

# 使用已安装的脚本：
retinanet-convert-model /path/to/training/model.h5 /path/to/save/inference/model.h5

大多数脚本（如 retinanet-evaluate）也支持通过 --convert-model 参数即时转换。

训练

keras-retinanet 可以使用 此脚本 进行训练。
请注意，该训练脚本使用相对导入，因为它位于 keras_retinanet 包内。
如果您希望在本仓库之外自定义使用该脚本，则需要将其改为使用绝对导入。

如果正确安装了 keras-retinanet，训练脚本将被安装为 retinanet-train。
然而，如果您对 keras-retinanet 仓库进行了本地修改，则应直接从仓库运行该脚本，以确保训练脚本能够应用您的更改。

默认骨干网络为 resnet50。您可以通过运行脚本时添加 --backbone=xxx 参数来更改骨干网络。
xxx 可以是 ResNet 模型中的任一种骨干（resnet50、resnet101、resnet152）、MobileNet 模型（mobilenet128_1.0、mobilenet128_0.75、mobilenet160_1.0 等）、DenseNet 模型或 VGG 模型。不同选项由各自模型的 Python 脚本（如 resnet.py、mobilenet.py 等）定义。

训练好的模型不能直接用于推理。要将训练模型转换为推理模型，请参阅 此处。

使用方法

在 Pascal VOC 数据集上训练

# 直接从仓库运行：
keras_retinanet/bin/train.py pascal /path/to/VOCdevkit/VOC2007

# 使用已安装的脚本：
retinanet-train pascal /path/to/VOCdevkit/VOC2007

在 MS COCO 数据集上训练

# 直接从仓库运行：
keras_retinanet/bin/train.py coco /path/to/MS/COCO

# 使用已安装的脚本：
retinanet-train coco /path/to/MS/COCO

在 Open Images Dataset (OID) 上训练

或参加 OID 挑战赛，可以按以下方式训练：

# 直接从仓库运行：
keras_retinanet/bin/train.py oid /path/to/OID

# 使用已安装的脚本：
retinanet-train oid /path/to/OID

# 如果只想在特定子集上训练，可以添加 `labels_filter` 参数指定标签列表：
keras_retinanet/bin/train.py oid /path/to/OID --labels-filter=Helmet,Tree

# 如果想基于语义层次树的一个父节点及其所有子节点进行训练，可以添加 `parent-label` 参数：
keras_retinanet/bin/train.py oid /path/to/OID --parent-label=Boat

在 KITTI 数据集上训练

# 直接从仓库运行：
keras_retinanet/bin/train.py kitti /path/to/KITTI

# 使用已安装的脚本：
retinanet-train kitti /path/to/KITTI

# 如果需要准备数据集，可以使用以下脚本：
https://github.com/NVIDIA/DIGITS/blob/master/examples/object-detection/prepare_kitti_data.py

在自定义数据集上训练

可以使用 CSV 文件作为数据输入方式。
有关 CSV 文件格式的详细信息，请参见下文。
使用 CSV 文件训练的方法如下：

# 直接从仓库运行：
keras_retinanet/bin/train.py csv /path/to/csv/file/containing/annotations /path/to/csv/file/containing/classes

# 使用已安装的脚本：
retinanet-train csv /path/to/csv/file/containing/annotations /path/to/csv/file/containing/classes

一般来说，使用自己的数据集进行训练的步骤如下：

1. 创建一个模型，例如通过调用 keras_retinanet.models.backbone('resnet50').retinanet(num_classes=80) 并对其进行编译。 根据经验，以下编译参数表现良好：

model.compile(
    loss={
        'regression'    : keras_retinanet.losses.smooth_l1(),
        'classification': keras_retinanet.losses.focal()
    },
    optimizer=keras.optimizers.Adam(lr=1e-5, clipnorm=0.001)
)

2. 为训练和测试数据创建生成器（示例可见于 keras_retinanet.preprocessing.pascal_voc.PascalVocGenerator）。
3. 使用 model.fit_generator 开始训练。

预训练模型

所有模型均可从 releases 页面 下载。

MS COCO

使用 cocoapi 得到的结果如下所示（注意：根据论文，此配置应达到 mAP 0.357）。

 平均精度 (AP) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.350
 平均精度 (AP) @[ IoU=0.50      | area=   all | maxDets=100 ] = 0.537
 平均精度 (AP) @[ IoU=0.75      | area=   all | maxDets=100 ] = 0.374
 平均精度 (AP) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.191
 平均精度 (AP) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.383
 平均精度 (AP) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.472
 平均召回率 (AR) @[ IoU=0.50:0.95 | area=   all | maxDets=  1 ] = 0.306
 平均召回率 (AR) @[ IoU=0.50:0.95 | area=   all | maxDets= 10 ] = 0.491
 平均召回率 (AR) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.533
 平均召回率 (AR) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.345
 平均召回率 (AR) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.577
 平均召回率 (AR) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.681

Open Images 数据集

基于 ResNet50、ResNet101 和 ResNet152 的 3 个 RetinaNet 模型已在 Open Images 数据集的所有 500 个类别 上进行了训练（感谢 @ZFTurbo）。

主干网络	图像尺寸 (px)	小验证集 mAP	LB (公开)
ResNet50	768 - 1024	0.4594	0.4223
ResNet101	768 - 1024	0.4986	0.4520
ResNet152	600 - 800	0.4991	0.4651

更多信息请查看 @ZFTurbo 的仓库。

CSV 数据集

CSVGenerator 提供了一种简便的方式来定义您自己的数据集。 它使用两个 CSV 文件：一个包含标注信息，另一个包含类别名称到 ID 的映射。

标注格式

包含标注信息的 CSV 文件应每行一条标注。 对于有多个人物框的图像，每个人物框应占一行。 请注意，像素值的索引从 0 开始。 每行的预期格式为：

path/to/image.jpg,x1,y1,x2,y2,class_name

默认情况下，CSV 生成器会相对于标注文件所在的目录查找图像。

有些图像可能不包含任何标记的对象。 要将这些图像作为负样本添加到数据集中， 可以添加一条标注，其中 x1、y1、x2、y2 和 class_name 均为空：

path/to/image.jpg,,,,,

完整示例：

/data/imgs/img_001.jpg,837,346,981,456,cow
/data/imgs/img_002.jpg,215,312,279,391,cat
/data/imgs/img_002.jpg,22,5,89,84,bird
/data/imgs/img_003.jpg,,,,,

这定义了一个包含 3 张图像的数据集。 img_001.jpg 包含一头牛。 img_002.jpg 包含一只猫和一只鸟。 img_003.jpg 不包含任何感兴趣的物体或动物。

类别映射格式

类别名称到 ID 的映射文件应每行一条映射。 每行应采用以下格式：

class_name,id

类别的索引从 0 开始。 不要包含背景类，因为它默认存在。

例如：

cow,0
cat,1
bird,2

锚点优化

在某些情况下，默认的锚点配置不适合检测您数据集中的目标，例如当您的目标小于 32×32 像素（最小锚点的尺寸）时。在这种情况下，修改锚点配置可能是合适的，可以通过遵循 anchor-optimization 仓库中的步骤自动完成。要使用生成的配置，请参阅 此处 的示例配置文件，然后使用 --config 参数将其传递给 train.py。

调试

创建您自己的数据集并不总是能立即成功。有一个名为 debug.py 的工具可以帮助您找到最常见的错误。 特别是 --annotations 标志非常有用，它可以将您的标注显示在数据集中的图像上。当有可用的锚点时，标注会以绿色显示；如果没有可用的锚点，则以红色显示。如果某个标注没有可用的锚点，那么它将不会对训练产生贡献。少量标注显示为红色是正常的，但如果大多数或全部标注都显示为红色，则需要引起重视。最常见的问题是标注太小或形状过于奇怪（拉长变形）。

结果

MS COCO

状态

下面展示了使用 keras-retinanet 的示例输出图像。

使用 keras-retinanet 的项目

• 使用 RetinaNet 改进苹果检测与计数。该项目旨在通过部署 Keras RetinaNet 来研究苹果检测问题。
• 利用弱 RECIST 标注生成的密集掩码改进 CT 病灶检测的 RetinaNet。一项使用 keras-retinanet 进行 CT 图像病灶检测的研究项目。
• NudeNet。一个专注于检测和屏蔽裸露内容的项目。
• 基于自监督深度学习神经网络的 RGB 影像个体树冠检测。一项专注于提升遥感树木调查性能的研究项目。
• ESRI 对象检测挑战赛 2019。ESRI 对象检测挑战赛 2019 的获奖实现。
• 月球落石检测项目。该项目旨在利用现有的超过 200 万张卫星图像，在全球范围内绘制月球落石分布图。
• 火星落石检测项目。该项目的目标是绘制火星上的落石分布图。
• 北约创新挑战赛。北约创新挑战赛的获胜团队使用 keras-retinanet 在航拍图像中检测车辆（COWC 数据集）。
• 微软研究院关于 Azure 上 Horovod 的研究。微软的一项研究项目，利用 keras-retinanet 结合 Azure 上的 Horovod 将训练分布式到多块 GPU 上。
• Anno-Mage。一款借助 keras-retinanet COCO 模型的建议来帮助标注图像的工具。
• Telenav.AI。用于使用 keras-retinanet 检测交通标志。
• 迈向深度胎盘组织学表型分析。该研究项目使用 keras-retinanet 在细胞水平上分析胎盘。
• 4K 视频示例。该演示展示了在 4K 输入视频上使用 keras-retinanet 的效果。
• boring-detector。我想并非所有项目都需要解决人生的重大问题。该项目用于检测视频中的“The Boring Company”帽子。
• comet.ml。将 keras-retinanet 与 comet.ml 结合使用，以交互方式检查和比较实验。
• Weights and Biases。从头开始在 resnet50 和 resnet101 后端上训练了 keras-retinanet，并在 coco 数据集上进行微调。
• Google Open Images 挑战赛 2018 第 15 名解决方案。基于 ResNet50、ResNet101 和 ResNet152 预训练的 keras-retinanet 权重，这些权重是在 Open Images 数据集上训练得到的。
• poke.AI。一款尝试掌握第三代宝可梦游戏的实验性 AI。使用 keras-retinanet 进行游戏内地图构建和定位。
• retinanetjs。一个用于在浏览器或 Node.js 中运行 RetinaNet 推理的封装库。你也可以查看其示例应用。
• CRFNet。该网络融合雷达和摄像头数据，用于自动驾驶场景下的目标检测。
• LogoDet。一个用于检测图像中公司 logo 的项目。
• AIR: 航空巡检 RetinaNet。一种利用无人机支持陆地搜救任务的深度学习解决方案。

如果你有一个基于 keras-retinanet 的项目，并希望在此处发布，请在 Slack 上给我发消息。

注意事项

• 本仓库需要 Tensorflow 2.3.0 或更高版本。
• 本仓库已使用 OpenCV 3.4 进行测试。
• 本仓库已使用 Python 2.7 和 3.6 进行测试。

欢迎为该项目贡献代码。

讨论

欢迎加入 Keras Slack 的 #keras-retinanet 频道，参与讨论和提问。

常见问题解答

• 我收到警告 UserWarning: 在保存文件中未找到训练配置：模型未编译。请手动编译。，需要担心吗？ 在推理阶段，可以安全地忽略此警告。
• 我在推理时遇到错误 ValueError: 解包值不足（期望 3 个，得到 2 个），该怎么办？ 这是因为您正在使用训练好的模型进行推理。更多信息请参阅：https://github.com/fizyr/keras-retinanet#converting-a-training-model-to-inference-model。
• 如何进行迁移学习？ 最简单的方法是在训练时使用 --weights 参数。Keras 可以加载模型，即使类别数不匹配（它会自动跳过不匹配部分的权重加载）。例如，运行 retinanet-train --weights snapshots/some_coco_model.h5 pascal /path/to/pascal，即可将 COCO 模型的权重迁移到 Pascal VOC 数据集的训练中。如果您的数据集较小，还可以使用 --freeze-backbone 参数冻结骨干网络层。
• 如何更改锚框的数量或形状？ 训练工具允许传入一个配置文件，在其中可以调整锚框参数。示例配置文件请参见：这里。
• 损失值为 0，这是怎么回事？ 这通常是因为没有锚框能够与您的目标对象匹配，很可能是因为锚框太小或过于细长。您可以使用 调试工具 来验证这一点。
• 我有一个旧模型，在更新 keras-retinanet 后还能使用吗？ 这取决于具体发生了哪些变化。如果这些变化不影响权重，则可以通过创建一个新的 RetinaNet 模型，使用 model.load_weights(weights_path, by_name=True) 加载旧模型的权重，然后保存新模型来“更新”模型。如果变化较大，则建议重新训练模型（您可以在开始训练时尝试加载旧模型的权重，这可能比从 ImageNet 初始化有更好的起点）。
• 我收到错误 ModuleNotFoundError: 没有名为 'keras_retinanet.utils.compute_overlap' 的模块，该如何解决？ 很可能是您直接从克隆的仓库中运行代码。这样做是可以的，但需要编译一些扩展才能正常工作（执行 python setup.py build_ext --inplace）。
• 如何在我的数据集上训练模型？ 在自己的数据集上训练的步骤大致如下：
• 1. 将数据集准备成 CSV 格式（建议划分训练集和验证集）。
• 2. 使用 retinanet-debug 检查数据集是否正确。
• 3. 训练 RetinaNet，最好使用预训练的 COCO 权重（这样可以获得更好的起点，使训练更快且更准确）。您也可以在训练过程中对验证集进行评估，以跟踪模型的表现（建议）。
• 4. 将训练好的模型转换为推理模型。
• 5. 在测试集或验证集上评估您的推理模型。
• 6. 大功告成！

Keras RetinaNet 快速上手指南

⚠️ 重要提示：本项目已停止维护（Deprecated），官方推荐使用 torchvision 模块。本项目仅兼容 Keras 2.4 和 TensorFlow 2.3.0，更高版本可能导致运行失败。如需在生产环境使用，请谨慎评估或迁移至 PyTorch 版本。

环境准备

• 操作系统: Linux / macOS (Windows 支持有限，需自行配置编译环境)
• Python: 3.6 - 3.8 (推荐)
• 核心依赖:
  • TensorFlow == 2.3.0
  • Keras == 2.4.3
  • Cython
  • opencv-python
  • pillow
  • matplotlib
• 可选依赖: pycocotools (如需使用 MS COCO 数据集)

国内加速建议： 在安装 Python 依赖时，建议使用清华或阿里镜像源以提升下载速度：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package_name>

安装步骤

1. 克隆仓库

git clone https://github.com/fizyr/keras-retinanet.git
cd keras-retinanet

2. 安装 TensorFlow (前置条件)

由于包内未强制指定 TensorFlow 版本以避免冲突，请先手动安装兼容版本：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple tensorflow==2.3.0 keras==2.4.3

3. 安装 keras-retinanet

在项目根目录下执行以下命令进行安装（包含 Cython 扩展编译）：

pip install . --user

或者，如果您希望直接运行源码而不进行全局安装，需先编译扩展：

python setup.py build_ext --inplace

4. (可选) 安装 COCO 工具

如果需要训练或测试 MS COCO 数据集：

pip install --user git+https://github.com/cocodataset/cocoapi.git#subdirectory=PythonAPI

注：国内网络若拉取 GitHub 失败，可尝试下载该仓库 zip 包解压后本地安装。

基本使用

1. 模型推理 (Inference)

训练好的模型不能直接用于推理，必须先转换为推理模型。

转换模型：

# 语法：retinanet-convert-model <训练模型路径> <保存路径>
retinanet-convert-model /path/to/training/model.h5 /path/to/inference_model.h5

执行预测： 您可以使用 Python 脚本加载模型并进行检测：

from keras_retinanet.models import load_model
import cv2

# 加载推理模型
model = load_model('/path/to/inference_model.h5', backbone_name='resnet50')

# 读取并预处理图片
image = cv2.imread('test.jpg')
image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
inputs = model.preprocess_image(image)
inputs, scale = model.resize_image(inputs)

# 执行预测
boxes, scores, labels = model.predict_on_batch(inputs)

# 结果处理 (boxes 格式为 x1, y1, x2, y2)
# 需根据 scale 还原坐标，并根据 scores 过滤低置信度框

2. 快速训练 (以自定义 CSV 数据集为例)

Keras RetinaNet 支持通过 CSV 文件定义自定义数据集。

数据格式准备：

1. annotations.csv: 每行格式为 图像路径,x1,y1,x2,y2,类别名
2. classes.csv: 每行格式为 类别名,ID (ID 从 0 开始)

启动训练：

# 语法：retinanet-train csv <标注文件> <类别映射文件>
retinanet-train csv /path/to/annotations.csv /path/to/classes.csv --backbone=resnet50

常用参数：

• --backbone: 选择骨干网络 (resnet50, resnet101, mobilenet128_1.0 等)
• --epochs: 训练轮数
• --snapshot-path: 模型保存路径

训练完成后，请使用上述“转换模型”步骤将生成的快照转换为推理模型即可使用。