add model public keys

README.rst

@@ -19,11 +19,23 @@ It features:
 Installation
 ---------------
 
+1. Install PyTorch and torchvision following the `official instructions <https://pytorch.org/>`_.
+2. Install Cython.
+3. Clone ``deep-person-reid`` to your preferred directory.
+
 .. code-block:: bash
     
     $ git clone https://github.com/KaiyangZhou/deep-person-reid.git
+
+4. Install ``torchreid`` via
+
+.. code-block:: bash
+    
     $ cd deep-person-reid/
-    $ python setup.py install # or python3 setup.py install
+    $ python setup.py install # or python3
+    $ # If you wanna modify the source code without
+    $ # the need to re-build it, you can do
+    $ # python setup.py develop
 
 
 News
@@ -102,6 +114,30 @@ Get started: 30 seconds to Torchreid
     )
 
 
+A unified interface
+-----------------------
+In "deep-person-reid/scripts/", we provide a unified interface including a default parser file ``default_parser.py`` and the main script ``main.py``. For example, to train an image reid model on Market1501 using softmax, you can do
+
+.. code-block:: python
+    
+    python main.py \
+    --root path/to/reid-data \
+    --app image \
+    --loss softmax \
+    --label-smooth \
+    -s market1501 \
+    -a resnet50 \
+    --optim adam \
+    --lr 0.0003 \
+    --max-epoch 60 \
+    --stepsize 20 40 \
+    --batch-size 32 \
+    --save-dir log/resnet50-market-softmax \
+    --gpu-devices 0
+
+Please refer to ``default_parser.py`` and ``main.py`` for more details.
+
+
 Datasets
 --------
 

docs/user_guide.rst

@@ -5,6 +5,30 @@ How-to
    :local:
 
 
+Find model keys
+-----------------
+Keys are listed under the *Public keys* section within each model class in :ref:`torchreid_models`.
+
+
+Show available models
+----------------------
+
+.. code-block:: python
+    
+    import torchreid
+    torchreid.models.show_avai_models()
+
+
+Change the training sampler
+-----------------------------
+The default ``train_sampler`` is "RandomSampler". You can give the specific sampler name as input to ``train_sampler``, e.g. ``train_sampler='RandomIdentitySampler'`` for triplet loss.
+
+
+Choose an optimizer/lr_scheduler
+----------------------------------
+Please refer to the source code of ``build_optimizer``/``build_lr_scheduler`` in :ref:`torchreid_optim` for details.
+
+
 Resume training
 ----------------
 Suppose the checkpoint is saved in "log/resnet50/model.pth.tar-30", you can do

torchreid/models/__init__.py

@@ -24,7 +24,11 @@ from .mlfn import *
 
 __model_factory = {
     # image classification models
+    'resnet18': resnet18,
+    'resnet34': resnet34,
     'resnet50': resnet50,
+    'resnet101': resnet101,
+    'resnet152': resnet152,
     'resnet50_fc512': resnet50_fc512,
     'resnext50_32x4d': resnext50_32x4d,
     'resnext50_32x4d_fc512': resnext50_32x4d_fc512,
@@ -34,6 +38,9 @@ __model_factory = {
     'se_resnext50_32x4d': se_resnext50_32x4d,
     'se_resnext101_32x4d': se_resnext101_32x4d,
     'densenet121': densenet121,
+    'densenet169': densenet169,
+    'densenet201': densenet201,
+    'densenet161': densenet161,
     'densenet121_fc512': densenet121_fc512,
     'inceptionresnetv2': inceptionresnetv2,
     'inceptionv4': inceptionv4,

torchreid/models/densenet.py

@@ -1,7 +1,7 @@
 from __future__ import absolute_import
 from __future__ import division
 
-__all__ = ['densenet121', 'densenet121_fc512']
+__all__ = ['densenet121', 'densenet169', 'densenet201', 'densenet161', 'densenet121_fc512']
 
 from collections import OrderedDict
 import math
@@ -65,6 +65,13 @@ class DenseNet(nn.Module):
     
     Reference:
         Huang et al. Densely Connected Convolutional Networks. CVPR 2017.
+
+    Public keys:
+        - ``densenet121``: DenseNet121.
+        - ``densenet169``: DenseNet169.
+        - ``densenet201``: DenseNet201.
+        - ``densenet161``: DenseNet161.
+        - ``densenet121_fc512``: DenseNet121 + FC.
     """
     def __init__(self, num_classes, loss, growth_rate=32, block_config=(6, 12, 24, 16),
                  num_init_features=64, bn_size=4, drop_rate=0, fc_dims=None, dropout_p=None, **kwargs):
@@ -223,6 +230,54 @@ def densenet121(num_classes, loss='softmax', pretrained=True, **kwargs):
     return model
 
 
+def densenet169(num_classes, loss='softmax', pretrained=True, **kwargs):
+    model = DenseNet(
+        num_classes=num_classes,
+        loss=loss,
+        num_init_features=64,
+        growth_rate=32,
+        block_config=(6, 12, 32, 32),
+        fc_dims=None,
+        dropout_p=None,
+        **kwargs
+    )
+    if pretrained:
+        init_pretrained_weights(model, model_urls['densenet169'])
+    return model
+
+
+def densenet201(num_classes, loss='softmax', pretrained=True, **kwargs):
+    model = DenseNet(
+        num_classes=num_classes,
+        loss=loss,
+        num_init_features=64,
+        growth_rate=32,
+        block_config=(6, 12, 48, 32),
+        fc_dims=None,
+        dropout_p=None,
+        **kwargs
+    )
+    if pretrained:
+        init_pretrained_weights(model, model_urls['densenet201'])
+    return model
+
+
+def densenet161(num_classes, loss='softmax', pretrained=True, **kwargs):
+    model = DenseNet(
+        num_classes=num_classes,
+        loss=loss,
+        num_init_features=96,
+        growth_rate=48,
+        block_config=(6, 12, 36, 24),
+        fc_dims=None,
+        dropout_p=None,
+        **kwargs
+    )
+    if pretrained:
+        init_pretrained_weights(model, model_urls['densenet161'])
+    return model
+
+
 def densenet121_fc512(num_classes, loss='softmax', pretrained=True, **kwargs):
     model = DenseNet(
         num_classes=num_classes,

torchreid/models/hacnn.py

@@ -190,6 +190,9 @@ class HACNN(nn.Module):
 
     Reference:
         Li et al. Harmonious Attention Network for Person Re-identification. CVPR 2018.
+
+    Public keys:
+        - ``hacnn``: HACNN.
     """
 
     # Args:

torchreid/models/inceptionresnetv2.py

@@ -279,6 +279,9 @@ class InceptionResNetV2(nn.Module):
     Reference:
         Szegedy et al. Inception-v4, Inception-ResNet and the Impact of Residual
         Connections on Learning. AAAI 2017.
+
+    Public keys:
+        - ``inceptionresnetv2``: Inception-ResNet-V2.
     """
     
     def __init__(self, num_classes, loss='softmax', **kwargs):

torchreid/models/inceptionv4.py

@@ -274,6 +274,9 @@ class InceptionV4(nn.Module):
     Reference:
         Szegedy et al. Inception-v4, Inception-ResNet and the Impact of Residual
         Connections on Learning. AAAI 2017.
+
+    Public keys:
+        - ``inceptionv4``: InceptionV4.
     """
     
     def __init__(self, num_classes, loss, **kwargs):

torchreid/models/mlfn.py

@@ -87,11 +87,14 @@ class MLFNBlock(nn.Module):
 
 
 class MLFN(nn.Module):
-    """Multi-Level Factorisation Nets.
+    """Multi-Level Factorisation Net.
 
     Reference:
         Chang et al. Multi-Level Factorisation Net for
         Person Re-Identification. CVPR 2018.
+
+    Public keys:
+        - ``mlfn``: MLFN (Multi-Level Factorisation Net).
     """
     
     def __init__(self, num_classes, loss='softmax', groups=32, channels=[64, 256, 512, 1024, 2048], embed_dim=1024, **kwargs):

torchreid/models/mobilenetv2.py

@@ -70,6 +70,10 @@ class MobileNetV2(nn.Module):
     Reference:
         Sandler et al. MobileNetV2: Inverted Residuals and
         Linear Bottlenecks. CVPR 2018.
+
+    Public keys:
+        - ``mobilenetv2_1dot0``: MobileNetV2 x1.0.
+        - ``mobilenetv2_1dot4``: MobileNetV2 x1.4.
     """
 
     def __init__(self, num_classes, width_mult=1, loss='softmax', fc_dims=None, dropout_p=None, **kwargs):

torchreid/models/mudeep.py

@@ -157,6 +157,9 @@ class MuDeep(nn.Module):
     Reference:
         Qian et al. Multi-scale Deep Learning Architectures
         for Person Re-identification. ICCV 2017.
+
+    Public keys:
+        - ``mudeep``: Multiscale deep neural network.
     """
     
     def __init__(self, num_classes, loss='softmax', **kwargs):

torchreid/models/nasnet.py

@@ -535,6 +535,9 @@ class NASNetAMobile(nn.Module):
     Reference:
         Zoph et al. Learning Transferable Architectures
         for Scalable Image Recognition. CVPR 2018.
+
+    Public keys:
+        - ``nasnetamobile``: NASNet-A Mobile.
     """
     
     def __init__(self, num_classes, loss, stem_filters=32, penultimate_filters=1056, filters_multiplier=2, **kwargs):

torchreid/models/pcb.py

@@ -121,6 +121,10 @@ class PCB(nn.Module):
     Reference:
         Sun et al. Beyond Part Models: Person Retrieval with Refined
         Part Pooling (and A Strong Convolutional Baseline). ECCV 2018.
+
+    Public keys:
+        - ``pcb_p4``: PCB with 4-part strips.
+        - ``pcb_p6``: PCB with 6-part strips.
     """
     
     def __init__(self, num_classes, loss, block, layers,

torchreid/models/resnet.py

@@ -1,7 +1,7 @@
 from __future__ import absolute_import
 from __future__ import division
 
-__all__ = ['resnet50', 'resnet50_fc512']
+__all__ = ['resnet18', 'resnet34', 'resnet50', 'resnet101', 'resnet152', 'resnet50_fc512']
 
 import torch
 from torch import nn
@@ -101,6 +101,14 @@ class ResNet(nn.Module):
     
     Reference:
         He et al. Deep Residual Learning for Image Recognition. CVPR 2016.
+
+    Public keys:
+        - ``resnet18``: ResNet18.
+        - ``resnet34``: ResNet34.
+        - ``resnet50``: ResNet50.
+        - ``resnet101``: ResNet101.
+        - ``resnet152``: ResNet152.
+        - ``resnet50_fc512``: ResNet50 + FC.
     """
     
     def __init__(self, num_classes, loss, block, layers,
@@ -246,6 +254,38 @@ resnet152: block=Bottleneck, layers=[3, 8, 36, 3]
 """
 
 
+def resnet18(num_classes, loss='softmax', pretrained=True, **kwargs):
+    model = ResNet(
+        num_classes=num_classes,
+        loss=loss,
+        block=BasicBlock,
+        layers=[2, 2, 2, 2],
+        last_stride=2,
+        fc_dims=None,
+        dropout_p=None,
+        **kwargs
+    )
+    if pretrained:
+        init_pretrained_weights(model, model_urls['resnet18'])
+    return model
+
+
+def resnet34(num_classes, loss='softmax', pretrained=True, **kwargs):
+    model = ResNet(
+        num_classes=num_classes,
+        loss=loss,
+        block=BasicBlock,
+        layers=[3, 4, 6, 3],
+        last_stride=2,
+        fc_dims=None,
+        dropout_p=None,
+        **kwargs
+    )
+    if pretrained:
+        init_pretrained_weights(model, model_urls['resnet34'])
+    return model
+
+
 def resnet50(num_classes, loss='softmax', pretrained=True, **kwargs):
     model = ResNet(
         num_classes=num_classes,
@@ -262,6 +302,41 @@ def resnet50(num_classes, loss='softmax', pretrained=True, **kwargs):
     return model
 
 
+def resnet101(num_classes, loss='softmax', pretrained=True, **kwargs):
+    model = ResNet(
+        num_classes=num_classes,
+        loss=loss,
+        block=Bottleneck,
+        layers=[3, 4, 23, 3],
+        last_stride=2,
+        fc_dims=None,
+        dropout_p=None,
+        **kwargs
+    )
+    if pretrained:
+        init_pretrained_weights(model, model_urls['resnet101'])
+    return model
+
+
+def resnet152(num_classes, loss='softmax', pretrained=True, **kwargs):
+    model = ResNet(
+        num_classes=num_classes,
+        loss=loss,
+        block=Bottleneck,
+        layers=[3, 8, 36, 3],
+        last_stride=2,
+        fc_dims=None,
+        dropout_p=None,
+        **kwargs
+    )
+    if pretrained:
+        init_pretrained_weights(model, model_urls['resnet152'])
+    return model
+
+
+"""
+resnet + fc
+"""
 def resnet50_fc512(num_classes, loss='softmax', pretrained=True, **kwargs):
     model = ResNet(
         num_classes=num_classes,

torchreid/models/resnetmid.py

@@ -102,6 +102,9 @@ class ResNetMid(nn.Module):
     Reference:
         Yu et al. The Devil is in the Middle: Exploiting Mid-level Representations for
         Cross-Domain Instance Matching. arXiv:1711.08106.
+
+    Public keys:
+        - ``resnet50mid``: ResNet50 + mid-level feature fusion.
     """
     
     def __init__(self, num_classes, loss, block, layers,

torchreid/models/resnext.py

@@ -63,6 +63,10 @@ class ResNeXt(nn.Module):
     Reference:
         Xie et al. Aggregated Residual Transformations for Deep
         Neural Networks. CVPR 2017.
+
+    Public keys:
+        - ``resnext50_32x4d``: ResNeXt50 (groups=32, width=4).
+        - ``resnext50_32x4d_fc512`` ResNeXt50 (groups=32, width=4) + FC.
     """
     
     def __init__(self, num_classes, loss, block, layers,

torchreid/models/senet.py

@@ -220,6 +220,15 @@ class SENet(nn.Module):
     
     Reference:
         Hu et al. Squeeze-and-Excitation Networks. CVPR 2018.
+
+    Public keys:
+        - ``senet154``: SENet154.
+        - ``se_resnet50``: ResNet50 + SE.
+        - ``se_resnet101``: ResNet101 + SE.
+        - ``se_resnet152``: ResNet152 + SE.
+        - ``se_resnext50_32x4d``: ResNeXt50 (groups=32, width=4) + SE.
+        - ``se_resnext101_32x4d``: ResNeXt101 (groups=32, width=4) + SE.
+        - ``se_resnet50_fc512``: (ResNet50 + SE) + FC.
     """
     
     def __init__(self, num_classes, loss, block, layers, groups, reduction, dropout_p=0.2,

torchreid/models/shufflenet.py

@@ -82,6 +82,9 @@ class ShuffleNet(nn.Module):
     Reference:
         Zhang et al. ShuffleNet: An Extremely Efficient Convolutional Neural
         Network for Mobile Devices. CVPR 2018.
+
+    Public keys:
+        - ``shufflenet``: ShuffleNet (groups=3).
     """
     
     def __init__(self, num_classes, loss='softmax', num_groups=3, **kwargs):

torchreid/models/squeezenet.py

@@ -54,6 +54,11 @@ class SqueezeNet(nn.Module):
     Reference:
         Iandola et al. SqueezeNet: AlexNet-level accuracy with 50x fewer parameters
         and< 0.5 MB model size. arXiv:1602.07360.
+
+    Public keys:
+        - ``squeezenet1_0``: SqueezeNet (version=1.0).
+        - ``squeezenet1_1``: SqueezeNet (version=1.1).
+        - ``squeezenet1_0_fc512``: SqueezeNet (version=1.0) + FC.
     """
     
     def __init__(self, num_classes, loss, version=1.0, fc_dims=None, dropout_p=None, **kwargs):

torchreid/models/xception.py

@@ -102,6 +102,9 @@ class Xception(nn.Module):
     Reference:
         Chollet. Xception: Deep Learning with Depthwise
         Separable Convolutions. CVPR 2017.
+
+    Public keys:
+        - ``xception``: Xception.
     """
     
     def __init__(self, num_classes, loss, fc_dims=None, dropout_p=None, **kwargs):