models.rst 24.8 KB
Newer Older
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
1
torchvision.models
2
3
4
5
6
##################


The models subpackage contains definitions of models for addressing
different tasks, including: image classification, pixelwise semantic
7
8
segmentation, object detection, instance segmentation, person
keypoint detection and video classification.
9

10
11
.. note ::
    Backward compatibility is guaranteed for loading a serialized 
12
    ``state_dict`` to the model created using old PyTorch version. 
13
    On the contrary, loading entire saved models or serialized 
14
15
    ``ScriptModules`` (seralized using older versions of PyTorch) 
    may not preserve the historic behaviour. Refer to the following 
16
17
18
    `documentation 
    <https://pytorch.org/docs/stable/notes/serialization.html#id6>`_   

19
20
21

Classification
==============
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
22

Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
23
The models subpackage contains definitions for the following model
24
architectures for image classification:
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
25
26
27
28
29
30
31

-  `AlexNet`_
-  `VGG`_
-  `ResNet`_
-  `SqueezeNet`_
-  `DenseNet`_
-  `Inception`_ v3
32
-  `GoogLeNet`_
Bar's avatar
Bar committed
33
-  `ShuffleNet`_ v2
34
35
-  `MobileNetV2`_
-  `MobileNetV3`_
36
-  `ResNeXt`_
37
-  `Wide ResNet`_
38
-  `MNASNet`_
39
-  `EfficientNet`_
40
-  `RegNet`_
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
41
42
43
44
45
46
47
48
49
50

You can construct a model with random weights by calling its constructor:

.. code:: python

    import torchvision.models as models
    resnet18 = models.resnet18()
    alexnet = models.alexnet()
    vgg16 = models.vgg16()
    squeezenet = models.squeezenet1_0()
Ahmed Abdo's avatar
Ahmed Abdo committed
51
    densenet = models.densenet161()
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
52
    inception = models.inception_v3()
53
    googlenet = models.googlenet()
54
    shufflenet = models.shufflenet_v2_x1_0()
55
56
57
    mobilenet_v2 = models.mobilenet_v2()
    mobilenet_v3_large = models.mobilenet_v3_large()
    mobilenet_v3_small = models.mobilenet_v3_small()
58
    resnext50_32x4d = models.resnext50_32x4d()
59
    wide_resnet50_2 = models.wide_resnet50_2()
60
    mnasnet = models.mnasnet1_0()
61
62
63
64
65
66
67
68
    efficientnet_b0 = models.efficientnet_b0()
    efficientnet_b1 = models.efficientnet_b1()
    efficientnet_b2 = models.efficientnet_b2()
    efficientnet_b3 = models.efficientnet_b3()
    efficientnet_b4 = models.efficientnet_b4()
    efficientnet_b5 = models.efficientnet_b5()
    efficientnet_b6 = models.efficientnet_b6()
    efficientnet_b7 = models.efficientnet_b7()
69
70
71
72
73
74
75
76
77
78
79
80
81
82
    regnet_y_400mf = models.regnet_y_400mf()
    regnet_y_800mf = models.regnet_y_800mf()
    regnet_y_1_6gf = models.regnet_y_1_6gf()
    regnet_y_3_2gf = models.regnet_y_3_2gf()
    regnet_y_8gf = models.regnet_y_8gf()
    regnet_y_16gf = models.regnet_y_16gf()
    regnet_y_32gf = models.regnet_y_32gf()
    regnet_x_400mf = models.regnet_x_400mf()
    regnet_x_800mf = models.regnet_x_800mf()
    regnet_x_1_6gf = models.regnet_x_1_6gf()
    regnet_x_3_2gf = models.regnet_x_3_2gf()
    regnet_x_8gf = models.regnet_x_8gf()
    regnet_x_16gf = models.regnet_x_16gf()
    regnet_x_32gf = models.regnet_x_32gf()
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
83
84
85
86
87
88
89
90
91
92
93

We provide pre-trained models, using the PyTorch :mod:`torch.utils.model_zoo`.
These can be constructed by passing ``pretrained=True``:

.. code:: python

    import torchvision.models as models
    resnet18 = models.resnet18(pretrained=True)
    alexnet = models.alexnet(pretrained=True)
    squeezenet = models.squeezenet1_0(pretrained=True)
    vgg16 = models.vgg16(pretrained=True)
Ahmed Abdo's avatar
Ahmed Abdo committed
94
    densenet = models.densenet161(pretrained=True)
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
95
    inception = models.inception_v3(pretrained=True)
96
    googlenet = models.googlenet(pretrained=True)
97
    shufflenet = models.shufflenet_v2_x1_0(pretrained=True)
98
99
    mobilenet_v2 = models.mobilenet_v2(pretrained=True)
    mobilenet_v3_large = models.mobilenet_v3_large(pretrained=True)
100
    mobilenet_v3_small = models.mobilenet_v3_small(pretrained=True)
101
    resnext50_32x4d = models.resnext50_32x4d(pretrained=True)
102
    wide_resnet50_2 = models.wide_resnet50_2(pretrained=True)
103
    mnasnet = models.mnasnet1_0(pretrained=True)
104
105
106
107
108
109
110
111
    efficientnet_b0 = models.efficientnet_b0(pretrained=True)
    efficientnet_b1 = models.efficientnet_b1(pretrained=True)
    efficientnet_b2 = models.efficientnet_b2(pretrained=True)
    efficientnet_b3 = models.efficientnet_b3(pretrained=True)
    efficientnet_b4 = models.efficientnet_b4(pretrained=True)
    efficientnet_b5 = models.efficientnet_b5(pretrained=True)
    efficientnet_b6 = models.efficientnet_b6(pretrained=True)
    efficientnet_b7 = models.efficientnet_b7(pretrained=True)
112
113
114
115
116
117
    regnet_y_400mf = models.regnet_y_400mf(pretrained=True)
    regnet_y_800mf = models.regnet_y_800mf(pretrained=True)
    regnet_y_8gf = models.regnet_y_8gf(pretrained=True)
    regnet_x_400mf = models.regnet_x_400mf(pretrained=True)
    regnet_x_800mf = models.regnet_x_800mf(pretrained=True)
    regnet_x_8gf = models.regnet_x_8gf(pretrained=True)
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
118

119
120
121
122
Instancing a pre-trained model will download its weights to a cache directory.
This directory can be set using the `TORCH_MODEL_ZOO` environment variable. See
:func:`torch.utils.model_zoo.load_url` for details.

123
124
125
Some models use modules which have different training and evaluation
behavior, such as batch normalization. To switch between these modes, use
``model.train()`` or ``model.eval()`` as appropriate. See
126
:meth:`~torch.nn.Module.train` or :meth:`~torch.nn.Module.eval` for details.
127

Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
128
129
130
131
132
133
134
135
136
137
138
139
140
All pre-trained models expect input images normalized in the same way,
i.e. mini-batches of 3-channel RGB images of shape (3 x H x W),
where H and W are expected to be at least 224.
The images have to be loaded in to a range of [0, 1] and then normalized
using ``mean = [0.485, 0.456, 0.406]`` and ``std = [0.229, 0.224, 0.225]``.
You can use the following transform to normalize::

    normalize = transforms.Normalize(mean=[0.485, 0.456, 0.406],
                                     std=[0.229, 0.224, 0.225])

An example of such normalization can be found in the imagenet example
`here <https://github.com/pytorch/examples/blob/42e5b996718797e45c46a25c55b031e6768f8440/imagenet/main.py#L89-L101>`_

141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
The process for obtaining the values of `mean` and `std` is roughly equivalent
to::

    import torch
    from torchvision import datasets, transforms as T

    transform = T.Compose([T.Resize(256), T.CenterCrop(224), T.ToTensor()])
    dataset = datasets.ImageNet(".", split="train", transform=transform)

    means = []
    stds = []
    for img in subset(dataset):
        means.append(torch.mean(img))
        stds.append(torch.std(img))

    mean = torch.mean(torch.tensor(means))
    std = torch.mean(torch.tensor(stds))

159
Unfortunately, the concrete `subset` that was used is lost. For more
160
161
162
information see `this discussion <https://github.com/pytorch/vision/issues/1439>`_
or `these experiments <https://github.com/pytorch/vision/pull/1965>`_.

163
164
165
166
The sizes of the EfficientNet models depend on the variant. For the exact input sizes
`check here <https://github.com/pytorch/vision/blob/d2bfd639e46e1c5dc3c177f889dc7750c8d137c7/references/classification/train.py#L92-L93>`_

ImageNet 1-crop error rates
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
167
168

================================  =============   =============
169
Model                             Acc@1           Acc@5
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
170
================================  =============   =============
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
AlexNet                           56.522          79.066
VGG-11                            69.020          88.628
VGG-13                            69.928          89.246
VGG-16                            71.592          90.382
VGG-19                            72.376          90.876
VGG-11 with batch normalization   70.370          89.810
VGG-13 with batch normalization   71.586          90.374
VGG-16 with batch normalization   73.360          91.516
VGG-19 with batch normalization   74.218          91.842
ResNet-18                         69.758          89.078
ResNet-34                         73.314          91.420
ResNet-50                         76.130          92.862
ResNet-101                        77.374          93.546
ResNet-152                        78.312          94.046
SqueezeNet 1.0                    58.092          80.420
SqueezeNet 1.1                    58.178          80.624
Densenet-121                      74.434          91.972
Densenet-169                      75.600          92.806
Densenet-201                      76.896          93.370
Densenet-161                      77.138          93.560
Inception v3                      77.294          93.450
GoogleNet                         69.778          89.530
ShuffleNet V2 x1.0                69.362          88.316
ShuffleNet V2 x0.5                60.552          81.746
MobileNet V2                      71.878          90.286
MobileNet V3 Large                74.042          91.340
197
MobileNet V3 Small                67.668          87.402
198
199
200
201
202
203
ResNeXt-50-32x4d                  77.618          93.698
ResNeXt-101-32x8d                 79.312          94.526
Wide ResNet-50-2                  78.468          94.086
Wide ResNet-101-2                 78.848          94.284
MNASNet 1.0                       73.456          91.510
MNASNet 0.5                       67.734          87.490
204
205
206
207
208
209
210
211
EfficientNet-B0                   77.692          93.532
EfficientNet-B1                   78.642          94.186
EfficientNet-B2                   80.608          95.310
EfficientNet-B3                   82.008          96.054
EfficientNet-B4                   83.384          96.594
EfficientNet-B5                   83.444          96.628
EfficientNet-B6                   84.008          96.916
EfficientNet-B7                   84.122          96.908
212
213
214
215
216
217
regnet_x_400mf                    72.834          90.950     
regnet_x_800mf                    75.190          92.418
regnet_x_8gf                      79.324          94.694
regnet_y_400mf                    74.024          91.680
regnet_y_800mf                    76.420          93.136
regnet_y_8gf                      79.966          95.100
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
218
219
220
221
222
223
224
225
226
================================  =============   =============


.. _AlexNet: https://arxiv.org/abs/1404.5997
.. _VGG: https://arxiv.org/abs/1409.1556
.. _ResNet: https://arxiv.org/abs/1512.03385
.. _SqueezeNet: https://arxiv.org/abs/1602.07360
.. _DenseNet: https://arxiv.org/abs/1608.06993
.. _Inception: https://arxiv.org/abs/1512.00567
227
.. _GoogLeNet: https://arxiv.org/abs/1409.4842
Bar's avatar
Bar committed
228
.. _ShuffleNet: https://arxiv.org/abs/1807.11164
229
230
.. _MobileNetV2: https://arxiv.org/abs/1801.04381
.. _MobileNetV3: https://arxiv.org/abs/1905.02244
231
.. _ResNeXt: https://arxiv.org/abs/1611.05431
232
.. _MNASNet: https://arxiv.org/abs/1807.11626
233
.. _EfficientNet: https://arxiv.org/abs/1905.11946
234
.. _RegNet: https://arxiv.org/abs/2003.13678
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
235
236
237

.. currentmodule:: torchvision.models

Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
Alexnet
-------

.. autofunction:: alexnet

VGG
---

.. autofunction:: vgg11
.. autofunction:: vgg11_bn
.. autofunction:: vgg13
.. autofunction:: vgg13_bn
.. autofunction:: vgg16
.. autofunction:: vgg16_bn
.. autofunction:: vgg19
.. autofunction:: vgg19_bn


ResNet
------

.. autofunction:: resnet18
.. autofunction:: resnet34
.. autofunction:: resnet50
.. autofunction:: resnet101
.. autofunction:: resnet152

SqueezeNet
----------

.. autofunction:: squeezenet1_0
.. autofunction:: squeezenet1_1

Sangwhan Moon's avatar
Sangwhan Moon committed
271
DenseNet
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
272
273
274
275
276
277
278
279
280
281
282
283
---------

.. autofunction:: densenet121
.. autofunction:: densenet169
.. autofunction:: densenet161
.. autofunction:: densenet201

Inception v3
------------

.. autofunction:: inception_v3

284
285
286
287
.. note ::
    This requires `scipy` to be installed


288
289
290
291
292
GoogLeNet
------------

.. autofunction:: googlenet

293
294
295
296
.. note ::
    This requires `scipy` to be installed


Bar's avatar
Bar committed
297
298
299
ShuffleNet v2
-------------

300
301
302
303
.. autofunction:: shufflenet_v2_x0_5
.. autofunction:: shufflenet_v2_x1_0
.. autofunction:: shufflenet_v2_x1_5
.. autofunction:: shufflenet_v2_x2_0
Bar's avatar
Bar committed
304

305
306
307
308
309
MobileNet v2
-------------

.. autofunction:: mobilenet_v2

310
311
312
313
314
315
MobileNet v3
-------------

.. autofunction:: mobilenet_v3_large
.. autofunction:: mobilenet_v3_small

316
ResNext
317
-------
318
319
320
321

.. autofunction:: resnext50_32x4d
.. autofunction:: resnext101_32x8d

322
323
324
325
326
327
Wide ResNet
-----------

.. autofunction:: wide_resnet50_2
.. autofunction:: wide_resnet101_2

328
329
330
331
332
333
334
335
MNASNet
--------

.. autofunction:: mnasnet0_5
.. autofunction:: mnasnet0_75
.. autofunction:: mnasnet1_0
.. autofunction:: mnasnet1_3

336
337
338
339
340
341
342
343
344
345
346
347
EfficientNet
------------

.. autofunction:: efficientnet_b0
.. autofunction:: efficientnet_b1
.. autofunction:: efficientnet_b2
.. autofunction:: efficientnet_b3
.. autofunction:: efficientnet_b4
.. autofunction:: efficientnet_b5
.. autofunction:: efficientnet_b6
.. autofunction:: efficientnet_b7

348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
RegNet
------------

.. autofunction:: regnet_y_400mf
.. autofunction:: regnet_y_800mf
.. autofunction:: regnet_y_1_6gf
.. autofunction:: regnet_y_3_2gf
.. autofunction:: regnet_y_8gf
.. autofunction:: regnet_y_16gf
.. autofunction:: regnet_y_32gf
.. autofunction:: regnet_x_400mf
.. autofunction:: regnet_x_800mf
.. autofunction:: regnet_x_1_6gf
.. autofunction:: regnet_x_3_2gf
.. autofunction:: regnet_x_8gf
.. autofunction:: regnet_x_16gf
.. autofunction:: regnet_x_32gf

366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
Quantized Models
----------------

The following architectures provide support for INT8 quantized models. You can get
a model with random weights by calling its constructor:

.. code:: python

    import torchvision.models as models
    googlenet = models.quantization.googlenet()
    inception_v3 = models.quantization.inception_v3()
    mobilenet_v2 = models.quantization.mobilenet_v2()
    mobilenet_v3_large = models.quantization.mobilenet_v3_large()
    resnet18 = models.quantization.resnet18()
    resnet50 = models.quantization.resnet50()
    resnext101_32x8d = models.quantization.resnext101_32x8d()
    shufflenet_v2_x0_5 = models.quantization.shufflenet_v2_x0_5()
    shufflenet_v2_x1_0 = models.quantization.shufflenet_v2_x1_0()
    shufflenet_v2_x1_5 = models.quantization.shufflenet_v2_x1_5()
    shufflenet_v2_x2_0 = models.quantization.shufflenet_v2_x2_0()

Obtaining a pre-trained quantized model can be done with a few lines of code:

.. code:: python

    import torchvision.models as models
    model = models.quantization.mobilenet_v2(pretrained=True, quantize=True)
    model.eval()
    # run the model with quantized inputs and weights
    out = model(torch.rand(1, 3, 224, 224))

We provide pre-trained quantized weights for the following models:

================================  =============  =============
Model                             Acc@1          Acc@5
================================  =============  =============
MobileNet V2                      71.658         90.150
MobileNet V3 Large                73.004         90.858
ShuffleNet V2                     68.360         87.582
ResNet 18                         69.494         88.882
ResNet 50                         75.920         92.814
ResNext 101 32x8d                 78.986         94.480
Inception V3                      77.176         93.354
GoogleNet                         69.826         89.404
================================  =============  =============

412
413
414
415

Semantic Segmentation
=====================

416
417
418
The models subpackage contains definitions for the following model
architectures for semantic segmentation:

419
- `FCN ResNet50, ResNet101 <https://arxiv.org/abs/1411.4038>`_
420
421
- `DeepLabV3 ResNet50, ResNet101, MobileNetV3-Large <https://arxiv.org/abs/1706.05587>`_
- `LR-ASPP MobileNetV3-Large <https://arxiv.org/abs/1905.02244>`_
422

423
424
425
426
427
As with image classification models, all pre-trained models expect input images normalized in the same way.
The images have to be loaded in to a range of ``[0, 1]`` and then normalized using
``mean = [0.485, 0.456, 0.406]`` and ``std = [0.229, 0.224, 0.225]``.
They have been trained on images resized such that their minimum size is 520.

428
429
For details on how to plot the masks of such models, you may refer to :ref:`semantic_seg_output`.

430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
The pre-trained models have been trained on a subset of COCO train2017, on the 20 categories that are
present in the Pascal VOC dataset. You can see more information on how the subset has been selected in
``references/segmentation/coco_utils.py``. The classes that the pre-trained model outputs are the following,
in order:

  .. code-block:: python

      ['__background__', 'aeroplane', 'bicycle', 'bird', 'boat', 'bottle', 'bus',
       'car', 'cat', 'chair', 'cow', 'diningtable', 'dog', 'horse', 'motorbike',
       'person', 'pottedplant', 'sheep', 'sofa', 'train', 'tvmonitor']

The accuracies of the pre-trained models evaluated on COCO val2017 are as follows

================================  =============  ====================
Network                           mean IoU       global pixelwise acc
================================  =============  ====================
446
FCN ResNet50                      60.5           91.4
447
FCN ResNet101                     63.7           91.9
448
DeepLabV3 ResNet50                66.4           92.4
449
DeepLabV3 ResNet101               67.4           92.4
450
451
DeepLabV3 MobileNetV3-Large       60.3           91.2
LR-ASPP MobileNetV3-Large         57.9           91.2
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
================================  =============  ====================


Fully Convolutional Networks
----------------------------

.. autofunction:: torchvision.models.segmentation.fcn_resnet50
.. autofunction:: torchvision.models.segmentation.fcn_resnet101


DeepLabV3
---------

.. autofunction:: torchvision.models.segmentation.deeplabv3_resnet50
.. autofunction:: torchvision.models.segmentation.deeplabv3_resnet101
467
468
469
470
471
472
473
.. autofunction:: torchvision.models.segmentation.deeplabv3_mobilenet_v3_large


LR-ASPP
-------

.. autofunction:: torchvision.models.segmentation.lraspp_mobilenet_v3_large
474

475
.. _object_det_inst_seg_pers_keypoint_det:
476
477
478
479

Object Detection, Instance Segmentation and Person Keypoint Detection
=====================================================================

480
481
482
The models subpackage contains definitions for the following model
architectures for detection:

483
484
485
486
- `Faster R-CNN <https://arxiv.org/abs/1506.01497>`_
- `Mask R-CNN <https://arxiv.org/abs/1703.06870>`_
- `RetinaNet <https://arxiv.org/abs/1708.02002>`_
- `SSD <https://arxiv.org/abs/1512.02325>`_
487
- `SSDlite <https://arxiv.org/abs/1801.04381>`_
488

489
490
491
492
493
The pre-trained models for detection, instance segmentation and
keypoint detection are initialized with the classification models
in torchvision.

The models expect a list of ``Tensor[C, H, W]``, in the range ``0-1``.
494
The models internally resize the images but the behaviour varies depending
495
496
on the model. Check the constructor of the models for more information. The
output format of such models is illustrated in :ref:`instance_seg_output`.
497
498
499
500
501
502
503
504
505


For object detection and instance segmentation, the pre-trained
models return the predictions of the following classes:

  .. code-block:: python

      COCO_INSTANCE_CATEGORY_NAMES = [
          '__background__', 'person', 'bicycle', 'car', 'motorcycle', 'airplane', 'bus',
506
507
          'train', 'truck', 'boat', 'traffic light', 'fire hydrant', 'N/A', 'stop sign',
          'parking meter', 'bench', 'bird', 'cat', 'dog', 'horse', 'sheep', 'cow',
508
          'elephant', 'bear', 'zebra', 'giraffe', 'N/A', 'backpack', 'umbrella', 'N/A', 'N/A',
509
510
511
512
513
514
515
516
          'handbag', 'tie', 'suitcase', 'frisbee', 'skis', 'snowboard', 'sports ball',
          'kite', 'baseball bat', 'baseball glove', 'skateboard', 'surfboard', 'tennis racket',
          'bottle', 'N/A', 'wine glass', 'cup', 'fork', 'knife', 'spoon', 'bowl',
          'banana', 'apple', 'sandwich', 'orange', 'broccoli', 'carrot', 'hot dog', 'pizza',
          'donut', 'cake', 'chair', 'couch', 'potted plant', 'bed', 'N/A', 'dining table',
          'N/A', 'N/A', 'toilet', 'N/A', 'tv', 'laptop', 'mouse', 'remote', 'keyboard', 'cell phone',
          'microwave', 'oven', 'toaster', 'sink', 'refrigerator', 'N/A', 'book',
          'clock', 'vase', 'scissors', 'teddy bear', 'hair drier', 'toothbrush'
517
518
519
520
521
522
      ]


Here are the summary of the accuracies for the models trained on
the instances set of COCO train2017 and evaluated on COCO val2017.

523
524
525
526
527
528
529
======================================  =======  ========  ===========
Network                                 box AP   mask AP   keypoint AP
======================================  =======  ========  ===========
Faster R-CNN ResNet-50 FPN              37.0     -         -
Faster R-CNN MobileNetV3-Large FPN      32.8     -         -
Faster R-CNN MobileNetV3-Large 320 FPN  22.8     -         -
RetinaNet ResNet-50 FPN                 36.4     -         -
530
531
SSD300 VGG16                            25.1     -         -
SSDlite320 MobileNetV3-Large            21.3     -         -
532
533
Mask R-CNN ResNet-50 FPN                37.9     34.6      -
======================================  =======  ========  ===========
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568

For person keypoint detection, the accuracies for the pre-trained
models are as follows

================================  =======  ========  ===========
Network                           box AP   mask AP   keypoint AP
================================  =======  ========  ===========
Keypoint R-CNN ResNet-50 FPN      54.6     -         65.0
================================  =======  ========  ===========

For person keypoint detection, the pre-trained model return the
keypoints in the following order:

  .. code-block:: python

    COCO_PERSON_KEYPOINT_NAMES = [
        'nose',
        'left_eye',
        'right_eye',
        'left_ear',
        'right_ear',
        'left_shoulder',
        'right_shoulder',
        'left_elbow',
        'right_elbow',
        'left_wrist',
        'right_wrist',
        'left_hip',
        'right_hip',
        'left_knee',
        'right_knee',
        'left_ankle',
        'right_ankle'
    ]

569
570
571
572
573
574
Runtime characteristics
-----------------------

The implementations of the models for object detection, instance segmentation
and keypoint detection are efficient.

575
576
577
In the following table, we use 8 GPUs to report the results. During training,
we use a batch size of 2 per GPU for all models except SSD which uses 4
and SSDlite which uses 24. During testing a batch size  of 1 is used.
578
579
580
581
582

For test time, we report the time for the model evaluation and postprocessing
(including mask pasting in image), but not the time for computing the
precision-recall.

583
584
585
586
587
588
589
======================================  ===================  ==================  ===========
Network                                 train time (s / it)  test time (s / it)  memory (GB)
======================================  ===================  ==================  ===========
Faster R-CNN ResNet-50 FPN              0.2288               0.0590              5.2
Faster R-CNN MobileNetV3-Large FPN      0.1020               0.0415              1.0
Faster R-CNN MobileNetV3-Large 320 FPN  0.0978               0.0376              0.6
RetinaNet ResNet-50 FPN                 0.2514               0.0939              4.1
590
591
SSD300 VGG16                            0.2093               0.0744              1.5
SSDlite320 MobileNetV3-Large            0.1773               0.0906              1.5
592
593
594
Mask R-CNN ResNet-50 FPN                0.2728               0.0903              5.4
Keypoint R-CNN ResNet-50 FPN            0.3789               0.1242              6.8
======================================  ===================  ==================  ===========
595
596
597
598
599
600


Faster R-CNN
------------

.. autofunction:: torchvision.models.detection.fasterrcnn_resnet50_fpn
601
.. autofunction:: torchvision.models.detection.fasterrcnn_mobilenet_v3_large_fpn
602
.. autofunction:: torchvision.models.detection.fasterrcnn_mobilenet_v3_large_320_fpn
603
604


605
RetinaNet
606
---------
607
608
609
610

.. autofunction:: torchvision.models.detection.retinanet_resnet50_fpn


611
SSD
612
---
613
614
615
616

.. autofunction:: torchvision.models.detection.ssd300_vgg16


617
SSDlite
618
-------
619
620
621
622

.. autofunction:: torchvision.models.detection.ssdlite320_mobilenet_v3_large


623
624
625
626
627
628
629
630
631
632
633
Mask R-CNN
----------

.. autofunction:: torchvision.models.detection.maskrcnn_resnet50_fpn


Keypoint R-CNN
--------------

.. autofunction:: torchvision.models.detection.keypointrcnn_resnet50_fpn

634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681

Video classification
====================

We provide models for action recognition pre-trained on Kinetics-400.
They have all been trained with the scripts provided in ``references/video_classification``.

All pre-trained models expect input images normalized in the same way,
i.e. mini-batches of 3-channel RGB videos of shape (3 x T x H x W),
where H and W are expected to be 112, and T is a number of video frames in a clip.
The images have to be loaded in to a range of [0, 1] and then normalized
using ``mean = [0.43216, 0.394666, 0.37645]`` and ``std = [0.22803, 0.22145, 0.216989]``.


.. note::
  The normalization parameters are different from the image classification ones, and correspond
  to the mean and std from Kinetics-400.

.. note::
  For now, normalization code can be found in ``references/video_classification/transforms.py``,
  see the ``Normalize`` function there. Note that it differs from standard normalization for
  images because it assumes the video is 4d.

Kinetics 1-crop accuracies for clip length 16 (16x112x112)

================================  =============   =============
Network                           Clip acc@1      Clip acc@5
================================  =============   =============
ResNet 3D 18                      52.75           75.45
ResNet MC 18                      53.90           76.29
ResNet (2+1)D                     57.50           78.81
================================  =============   =============


ResNet 3D
----------

.. autofunction:: torchvision.models.video.r3d_18

ResNet Mixed Convolution
------------------------

.. autofunction:: torchvision.models.video.mc3_18

ResNet (2+1)D
-------------

.. autofunction:: torchvision.models.video.r2plus1d_18