Shortcuts

使用已有模型在标准数据集上进行推理

MMDetection 提供了许多预训练好的检测模型,可以在 Model Zoo 查看具体有哪些模型。

推理具体指使用训练好的模型来检测图像上的目标,本文将会展示具体步骤。

在 MMDetection 中,一个模型被定义为一个配置文件 和对应被存储在 checkpoint 文件内的模型参数的集合。

首先,我们建议从 RTMDet 开始,其 配置 文件和 checkpoint 文件在此。 我们建议将 checkpoint 文件下载到 checkpoints 文件夹内。

推理的高层编程接口——推理器

在 OpenMMLab 中,所有的推理操作都被统一到了推理器 Inferencer 中。推理器被设计成为一个简洁易用的 API,它在不同的 OpenMMLab 库中都有着非常相似的接口。 下面介绍的演示样例都放在 demo/inference_demo.ipynb 中方便大家尝试。

基础用法

使用 DetInferencer,您只需 3 行代码就可以获得推理结果。

from mmdet.apis import DetInferencer

# 初始化模型
inferencer = DetInferencer('rtmdet_tiny_8xb32-300e_coco')

# 推理示例图片
inferencer('demo/demo.jpg', show=True)

可视化结果将被显示在一个新窗口中:

注解

如果你在没有 GUI 的服务器上,或者通过禁用 X11 转发的 SSH 隧道运行以上命令,show 选项将不起作用。然而,你仍然可以通过设置 out_dir 参数将可视化数据保存到文件。阅读 储存结果 了解详情。

初始化

每个推理器必须使用一个模型进行初始化。初始化时,可以手动选择推理设备。

模型初始化

  • 要用 MMDetection 的预训练模型进行推理,只需要把它的名字传给参数 model,权重将自动从 OpenMMLab 的模型库中下载和加载。

    inferencer = DetInferencer(model='rtmdet_tiny_8xb32-300e_coco')
    

    在 MMDetection 中有一个非常容易的方法,可以列出所有模型名称。

    # models 是一个模型名称列表,它们将自动打印
    models = DetInferencer.list_models('mmdet')
    

    你可以通过将权重的路径或 URL 传递给 weights 来让推理器加载自定义的权重。

    inferencer = DetInferencer(model='rtmdet_tiny_8xb32-300e_coco', weights='path/to/rtmdet.pth')
    
  • 要加载自定义的配置和权重,你可以把配置文件的路径传给 model,把权重的路径传给 weights

    inferencer = DetInferencer(model='path/to/rtmdet_config.py', weights='path/to/rtmdet.pth')
    
  • 默认情况下,MMEngine 会在训练模型时自动将配置文件转储到权重文件中。如果你有一个在 MMEngine 上训练的权重,你也可以将权重文件的路径传递给 weights,而不需要指定 model

    # 如果无法在权重中找到配置文件,则会引发错误。目前 MMDetection 模型库中只有 ddq-detr-4scale_r50 的权重可以这样加载。
    inferencer = DetInferencer(weights='https://download.openmmlab.com/mmdetection/v3.0/ddq/ddq-detr-4scale_r50_8xb2-12e_coco/ddq-detr-4scale_r50_8xb2-12e_coco_20230809_170711-42528127.pth')
    
  • 传递配置文件到 model 而不指定 weights 则会产生一个随机初始化的模型。

推理设备

每个推理器实例都会跟一个设备绑定。默认情况下,最佳设备是由 MMEngine 自动决定的。你也可以通过指定 device 参数来改变设备。例如,你可以使用以下代码在 GPU 1 上创建一个推理器。

inferencer = DetInferencer(model='rtmdet_tiny_8xb32-300e_coco', device='cuda:1')

如要在 CPU 上创建一个推理器:

inferencer = DetInferencer(model='rtmdet_tiny_8xb32-300e_coco', device='cpu')

请参考 torch.device 了解 device 参数支持的所有形式。

推理

当推理器初始化后,你可以直接传入要推理的原始数据,从返回值中获取推理结果。

输入

输入可以是以下任意一种格式:

  • str: 图像的路径/URL。

    inferencer('demo/demo.jpg')
    
  • array: 图像的 numpy 数组。它应该是 BGR 格式。

    import mmcv
    array = mmcv.imread('demo/demo.jpg')
    inferencer(array)
    
  • list: 基本类型的列表。列表中的每个元素都将单独处理。

    inferencer(['img_1.jpg', 'img_2.jpg])
    # 列表内混合类型也是允许的
    inferencer(['img_1.jpg', array])
    
  • str: 目录的路径。目录中的所有图像都将被处理。

    inferencer('path/to/your_imgs/')
    

输出

默认情况下,每个推理器都以字典格式返回预测结果。

  • visualization 包含可视化的预测结果。但默认情况下,它是一个空列表,除非 return_vis=True

  • predictions 包含以 json-可序列化格式返回的预测结果。

{
      'predictions' : [
        # 每个实例都对应于一个输入图像
        {
          'labels': [...],  # 整数列表,长度为 (N, )
          'scores': [...],  # 浮点列表,长度为 (N, )
          'bboxes': [...],  # 2d 列表,形状为 (N, 4),格式为 [min_x, min_y, max_x, max_y]
        },
        ...
      ],
      'visualization' : [
        array(..., dtype=uint8),
      ]
  }

如果你想要从模型中获取原始输出,可以将 return_datasamples 设置为 True 来获取原始的 DataSample,它将存储在 predictions 中。

储存结果

除了从返回值中获取预测结果,你还可以通过设置 out_dirno_save_pred/no_save_vis 参数将预测结果和可视化结果导出到文件中。

inferencer('demo/demo.jpg', out_dir='outputs/', no_save_pred=False)

结果目录结构如下:

outputs
├── preds
│   └── demo.json
└── vis
    └── demo.jpg

批量推理

你可以通过设置 batch_size 来自定义批量推理的批大小。默认批大小为 1。

API

这里列出了推理器详尽的参数列表。

  • DetInferencer.__init__():

参数 类型 默认值 描述
model str , 可选 None 配置文件的路径或 metafile 中定义的模型名称。例如,可以是 'rtmdet-s' 或 'rtmdet_s_8xb32-300e_coco' 或 'configs/rtmdet/rtmdet_s_8xb32-300e_coco.py'。如果未指定模型,用户必须提供 MMEngine 保存的包含配置字符串的 "weights"。
weights str, 可选 None 模型权重文件的路径。如果未指定且 model 是 metafile 中的模型名称,权重将从 metafile 中加载。
device str, 可选 None 推理使用的设备,接受 torch.device 允许的所有字符串。例如,'cuda:0' 或 'cpu'。如果为 None,将自动使用可用设备。 默认为 None。
scope str, 可选 'mmdet' 模型的”域名“。
palette str 'none' 用于可视化的配色。优先顺序为 palette -> config -> checkpoint。
show_progress bool True 控制是否在推理过程中显示进度条。
  • DetInferencer.__call__()

参数 类型 默认值 描述
inputs str/list/tuple/np.array 必需 它可以是一个图片/文件夹的路径,一个 numpy 数组,或者是一个包含图片路径或 numpy 数组的列表/元组
batch_size int 1 推理的批大小。
return_vis bool False 是否返回可视化结果。
show bool False 是否在弹出窗口中显示可视化结果。
wait_time float 0 弹窗展示可视化结果的时间间隔。
no_save_vis bool False 是否将可视化结果保存到 out_dir。默认为保存。
draw_pred bool True 是否绘制预测的边界框。
pred_score_thr float 0.3 显示预测框的最低置信度。
return_datasamples bool False 是否将结果作为 DetDataSample 返回。 如果为 False,则结果将被打包到一个 dict 中。
print_result bool False 是否将推理结果打印到控制台。
no_save_pred bool True 是否将推理结果保存到 out_dir。默认为不保存。
out_dir str '' 结果的输出目录。
texts str/list[str],可选 None 文本提示词。
stuff_texts str/list[str],可选 None 物体文本提示词。
custom_entities bool False 是否使用自定义实体。只用于 GLIP 算法。
**kwargs 传递给 :meth:preprocess、:meth:forward、:meth:visualize 和 :meth:postprocess 的其他关键字参数。kwargs 中的每个关键字都应在相应的 preprocess_kwargsforward_kwargsvisualize_kwargspostprocess_kwargs 中。

演示脚本样例

我们还提供了四个演示脚本,它们是使用高层编程接口实现的。源码在此

图片样例

这是在单张图片上进行推理的脚本。

python demo/image_demo.py \
    ${IMAGE_FILE} \
    ${CONFIG_FILE} \
    [--weights ${WEIGHTS}] \
    [--device ${GPU_ID}] \
    [--pred-score-thr ${SCORE_THR}]

运行样例:

python demo/image_demo.py demo/demo.jpg \
    configs/rtmdet/rtmdet_l_8xb32-300e_coco.py \
    --weights checkpoints/rtmdet_l_8xb32-300e_coco_20220719_112030-5a0be7c4.pth \
    --device cpu

摄像头样例

这是使用摄像头实时图片的推理脚本。

python demo/webcam_demo.py \
    ${CONFIG_FILE} \
    ${CHECKPOINT_FILE} \
    [--device ${GPU_ID}] \
    [--camera-id ${CAMERA-ID}] \
    [--score-thr ${SCORE_THR}]

运行样例:

python demo/webcam_demo.py \
    configs/rtmdet/rtmdet_l_8xb32-300e_coco.py \
    checkpoints/rtmdet_l_8xb32-300e_coco_20220719_112030-5a0be7c4.pth

视频样例

这是在视频样例上进行推理的脚本。

python demo/video_demo.py \
    ${VIDEO_FILE} \
    ${CONFIG_FILE} \
    ${CHECKPOINT_FILE} \
    [--device ${GPU_ID}] \
    [--score-thr ${SCORE_THR}] \
    [--out ${OUT_FILE}] \
    [--show] \
    [--wait-time ${WAIT_TIME}]

运行样例:

python demo/video_demo.py demo/demo.mp4 \
    configs/rtmdet/rtmdet_l_8xb32-300e_coco.py \
    checkpoints/rtmdet_l_8xb32-300e_coco_20220719_112030-5a0be7c4.pth \
    --out result.mp4

视频样例,显卡加速版本

这是在视频样例上进行推理的脚本,使用显卡加速。

python demo/video_gpuaccel_demo.py \
     ${VIDEO_FILE} \
     ${CONFIG_FILE} \
     ${CHECKPOINT_FILE} \
     [--device ${GPU_ID}] \
     [--score-thr ${SCORE_THR}] \
     [--nvdecode] \
     [--out ${OUT_FILE}] \
     [--show] \
     [--wait-time ${WAIT_TIME}]

运行样例:

python demo/video_gpuaccel_demo.py demo/demo.mp4 \
    configs/rtmdet/rtmdet_l_8xb32-300e_coco.py \
    checkpoints/rtmdet_l_8xb32-300e_coco_20220719_112030-5a0be7c4.pth \
    --nvdecode --out result.mp4

大图推理样例

这是在大图上进行切片推理的脚本。

python demo/large_image_demo.py \
	${IMG_PATH} \
	${CONFIG_FILE} \
	${CHECKPOINT_FILE} \
	--device ${GPU_ID}  \
	--show \
	--tta  \
	--score-thr ${SCORE_THR} \
	--patch-size ${PATCH_SIZE} \
	--patch-overlap-ratio ${PATCH_OVERLAP_RATIO} \
	--merge-iou-thr ${MERGE_IOU_THR} \
	--merge-nms-type ${MERGE_NMS_TYPE} \
	--batch-size ${BATCH_SIZE} \
	--debug \
	--save-patch

运行样例:

# inferecnce without tta
wget -P checkpoint https://download.openmmlab.com/mmdetection/v2.0/faster_rcnn/faster_rcnn_r101_fpn_2x_coco/faster_rcnn_r101_fpn_2x_coco_bbox_mAP-0.398_20200504_210455-1d2dac9c.pth

python demo/large_image_demo.py \
    demo/large_image.jpg \
    configs/faster_rcnn/faster-rcnn_r101_fpn_2x_coco.py \
    checkpoint/faster_rcnn_r101_fpn_2x_coco_bbox_mAP-0.398_20200504_210455-1d2dac9c.pth

# inference with tta
wget -P checkpoint https://download.openmmlab.com/mmdetection/v2.0/retinanet/retinanet_r50_fpn_1x_coco/retinanet_r50_fpn_1x_coco_20200130-c2398f9e.pth

python demo/large_image_demo.py \
    demo/large_image.jpg \
    configs/retinanet/retinanet_r50_fpn_1x_coco.py \
    checkpoint/retinanet_r50_fpn_1x_coco_20200130-c2398f9e.pth --tta

多模态算法的推理和验证

随着多模态视觉算法的不断发展,MMDetection 也完成了对这类算法的支持。这一小节我们通过 GLIP 算法和模型来演示如何使用对应多模态算法的 demo 和 eval 脚本。同时 MMDetection 也在 projects 下完成了 gradio_demo 项目,用户可以参照文档在本地快速体验 MMDetection 中支持的各类图片输入的任务。

模型准备

首先需要安装多模态依赖:

# if source
pip install -r requirements/multimodal.txt

# if wheel
mim install mmdet[multimodal]

MMDetection 已经集成了 glip 算法和模型,可以直接使用链接下载使用:

cd mmdetection
wget https://download.openmmlab.com/mmdetection/v3.0/glip/glip_tiny_a_mmdet-b3654169.pth

推理演示

下载完成后我们就可以利用 demo 下的多模态推理脚本完成推理:

python demo/image_demo.py demo/demo.jpg glip_tiny_a_mmdet-b3654169.pth --texts bench

demo 效果如下图所示:

如果想进行多种类型的识别,需要使用 xx. xx 的格式在 --texts 字段后声明目标类型:

python demo/image_demo.py demo/demo.jpg glip_tiny_a_mmdet-b3654169.pth --texts 'bench. car'

结果如下图所示:

推理脚本还支持输入一个句子作为 --texts 字段的输入:

python demo/image_demo.py demo/demo.jpg glip_tiny_a_mmdet-b3654169.pth --texts 'There are a lot of cars here.'

结果可以参考下图:

验证演示

MMDetection 支持后的 GLIP 算法对比官方版本没有精度上的损失, benchmark 如下所示:

Model official mAP mmdet mAP
glip_A_Swin_T_O365.yaml 42.9 43.0
glip_Swin_T_O365.yaml 44.9 44.9
glip_Swin_L.yaml 51.4 51.3

用户可以使用 test.py 脚本对模型精度进行验证,使用如下所示:

# 1 gpu
python tools/test.py configs/glip/glip_atss_swin-t_fpn_dyhead_pretrain_obj365.py glip_tiny_a_mmdet-b3654169.pth

# 8 GPU
./tools/dist_test.sh configs/glip/glip_atss_swin-t_fpn_dyhead_pretrain_obj365.py glip_tiny_a_mmdet-b3654169.pth 8
Read the Docs v: stable
Versions
latest
stable
3.x
v3.3.0
v3.2.0
v3.1.0
v3.0.0
v2.28.2
v2.28.1
v2.28.0
v2.27.0
v2.26.0
v2.25.3
v2.25.2
v2.25.1
v2.25.0
v2.24.1
v2.24.0
v2.23.0
v2.22.0
v2.21.0
v2.20.0
v2.19.1
v2.19.0
v2.18.1
v2.18.0
v2.17.0
v2.16.0
v2.15.1
v2.15.0
v2.14.0
v2.13.0
dev-3.x
dev
Downloads
epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.