Torchreid =========== Torchreid is a library for deep-learning person re-identification, written in `PyTorch `_. It features: - multi-GPU training - support both image- and video-reid - end-to-end training and evaluation - incredibly easy preparation of reid datasets - multi-dataset training - cross-dataset evaluation - standard protocol used by most research papers - highly extensible (easy to add models, datasets, training methods, etc.) - implementations of state-of-the-art deep reid models - access to pretrained reid models - advanced training techniques - visualization tools (tensorboard, ranks, etc.) Code: https://github.com/KaiyangZhou/deep-person-reid. Documentation: https://kaiyangzhou.github.io/deep-person-reid/. How-to instructions: https://kaiyangzhou.github.io/deep-person-reid/user_guide. Model zoo: https://kaiyangzhou.github.io/deep-person-reid/MODEL_ZOO. Tech report: https://arxiv.org/abs/1910.10093. You can find some research projects that are built on top of Torchreid `here `_. What's new ------------ - [Feb 2021] We support the new multi-view multi-source geo-localization dataset `University-1652 `_. - [Feb 2021] ``v1.3.5``: Now the `cython code `_ works on Windows (credit to `lablabla `_). - [Jan 2021] Our recent work, `MixStyle `_ (mixing instance-level feature statistics of samples of different domains for improving domain generalization), has been accepted to ICLR'21. The code has been released at https://github.com/KaiyangZhou/mixstyle-release where the person re-ID part is based on Torchreid. - [Jan 2021] A new evaluation metric called `mean Inverse Negative Penalty (mINP)` for person re-ID has been introduced in `Deep Learning for Person Re-identification: A Survey and Outlook (TPAMI 2021) `_. Their code can be accessed at ``_. - [Aug 2020] ``v1.3.3``: Fixed bug in ``visrank`` (caused by not unpacking ``dsetid``). - [Aug 2020] ``v1.3.2``: Added ``_junk_pids`` to ``grid`` and ``prid``. This avoids using mislabeled gallery images for training when setting ``combineall=True``. - [Aug 2020] ``v1.3.0``: (1) Added ``dsetid`` to the existing 3-tuple data source, resulting in ``(impath, pid, camid, dsetid)``. This variable denotes the dataset ID and is useful when combining multiple datasets for training (as a dataset indicator). E.g., when combining ``market1501`` and ``cuhk03``, the former will be assigned ``dsetid=0`` while the latter will be assigned ``dsetid=1``. (2) Added ``RandomDatasetSampler``. Analogous to ``RandomDomainSampler``, ``RandomDatasetSampler`` samples a certain number of images (``batch_size // num_datasets``) from each of specified datasets (the amount is determined by ``num_datasets``). - [Aug 2020] ``v1.2.6``: Added ``RandomDomainSampler`` (it samples ``num_cams`` cameras each with ``batch_size // num_cams`` images to form a mini-batch). - [Jun 2020] ``v1.2.5``: (1) Dataloader's output from ``__getitem__`` has been changed from ``list`` to ``dict``. Previously, an element, e.g. image tensor, was fetched with ``imgs=data[0]``. Now it should be obtained by ``imgs=data['img']``. See this `commit `_ for detailed changes. (2) Added ``k_tfm`` as an option to image data loader, which allows data augmentation to be applied ``k_tfm`` times *independently* to an image. If ``k_tfm > 1``, ``imgs=data['img']`` returns a list with ``k_tfm`` image tensors. - [May 2020] Added the person attribute recognition code used in `Omni-Scale Feature Learning for Person Re-Identification (ICCV'19) `_. See ``projects/attribute_recognition/``. - [May 2020] ``v1.2.1``: Added a simple API for feature extraction (``torchreid/utils/feature_extractor.py``). See the `documentation `_ for the instruction. - [Apr 2020] Code for reproducing the experiments of `deep mutual learning `_ in the `OSNet paper `__ (Supp. B) has been released at ``projects/DML``. - [Apr 2020] Upgraded to ``v1.2.0``. The engine class has been made more model-agnostic to improve extensibility. See `Engine `_ and `ImageSoftmaxEngine `_ for more details. Credit to `Dassl.pytorch `_. - [Dec 2019] Our `OSNet paper `_ has been updated, with additional experiments (in section B of the supplementary) showing some useful techniques for improving OSNet's performance in practice. - [Nov 2019] ``ImageDataManager`` can load training data from target datasets by setting ``load_train_targets=True``, and the train-loader can be accessed with ``train_loader_t = datamanager.train_loader_t``. This feature is useful for domain adaptation research. Installation --------------- Make sure `conda `_ is installed. .. code-block:: bash # cd to your preferred directory and clone this repo git clone https://github.com/KaiyangZhou/deep-person-reid.git # create environment cd deep-person-reid/ conda create --name torchreid python=3.7 conda activate torchreid # install dependencies # make sure `which python` and `which pip` point to the correct path pip install -r requirements.txt # install torch and torchvision (select the proper cuda version to suit your machine) conda install pytorch torchvision cudatoolkit=9.0 -c pytorch # install torchreid (don't need to re-build it if you modify the source code) python setup.py develop Get started: 30 seconds to Torchreid ------------------------------------- 1. Import ``torchreid`` .. code-block:: python import torchreid 2. Load data manager .. code-block:: python datamanager = torchreid.data.ImageDataManager( root='reid-data', sources='market1501', targets='market1501', height=256, width=128, batch_size_train=32, batch_size_test=100, transforms=['random_flip', 'random_crop'] ) 3 Build model, optimizer and lr_scheduler .. code-block:: python model = torchreid.models.build_model( name='resnet50', num_classes=datamanager.num_train_pids, loss='softmax', pretrained=True ) model = model.cuda() optimizer = torchreid.optim.build_optimizer( model, optim='adam', lr=0.0003 ) scheduler = torchreid.optim.build_lr_scheduler( optimizer, lr_scheduler='single_step', stepsize=20 ) 4. Build engine .. code-block:: python engine = torchreid.engine.ImageSoftmaxEngine( datamanager, model, optimizer=optimizer, scheduler=scheduler, label_smooth=True ) 5. Run training and test .. code-block:: python engine.run( save_dir='log/resnet50', max_epoch=60, eval_freq=10, print_freq=10, test_only=False ) A unified interface ----------------------- In "deep-person-reid/scripts/", we provide a unified interface to train and test a model. See "scripts/main.py" and "scripts/default_config.py" for more details. The folder "configs/" contains some predefined configs which you can use as a starting point. Below we provide an example to train and test `OSNet (Zhou et al. ICCV'19) `_. Assume :code:`PATH_TO_DATA` is the directory containing reid datasets. The environmental variable :code:`CUDA_VISIBLE_DEVICES` is omitted, which you need to specify if you have a pool of gpus and want to use a specific set of them. Conventional setting ^^^^^^^^^^^^^^^^^^^^^ To train OSNet on Market1501, do .. code-block:: bash python scripts/main.py \ --config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad_cosine.yaml \ --transforms random_flip random_erase \ --root $PATH_TO_DATA The config file sets Market1501 as the default dataset. If you wanna use DukeMTMC-reID, do .. code-block:: bash python scripts/main.py \ --config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad_cosine.yaml \ -s dukemtmcreid \ -t dukemtmcreid \ --transforms random_flip random_erase \ --root $PATH_TO_DATA \ data.save_dir log/osnet_x1_0_dukemtmcreid_softmax_cosinelr The code will automatically (download and) load the ImageNet pretrained weights. After the training is done, the model will be saved as "log/osnet_x1_0_market1501_softmax_cosinelr/model.pth.tar-250". Under the same folder, you can find the `tensorboard `_ file. To visualize the learning curves using tensorboard, you can run :code:`tensorboard --logdir=log/osnet_x1_0_market1501_softmax_cosinelr` in the terminal and visit :code:`http://localhost:6006/` in your web browser. Evaluation is automatically performed at the end of training. To run the test again using the trained model, do .. code-block:: bash python scripts/main.py \ --config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad_cosine.yaml \ --root $PATH_TO_DATA \ model.load_weights log/osnet_x1_0_market1501_softmax_cosinelr/model.pth.tar-250 \ test.evaluate True Cross-domain setting ^^^^^^^^^^^^^^^^^^^^^ Suppose you wanna train OSNet on DukeMTMC-reID and test its performance on Market1501, you can do .. code-block:: bash python scripts/main.py \ --config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad.yaml \ -s dukemtmcreid \ -t market1501 \ --transforms random_flip color_jitter \ --root $PATH_TO_DATA Here we only test the cross-domain performance. However, if you also want to test the performance on the source dataset, i.e. DukeMTMC-reID, you can set :code:`-t dukemtmcreid market1501`, which will evaluate the model on the two datasets separately. Different from the same-domain setting, here we replace :code:`random_erase` with :code:`color_jitter`. This can improve the generalization performance on the unseen target dataset. Pretrained models are available in the `Model Zoo `_. Datasets -------- Image-reid datasets ^^^^^^^^^^^^^^^^^^^^^ - `Market1501 `_ - `CUHK03 `_ - `DukeMTMC-reID `_ - `MSMT17 `_ - `VIPeR `_ - `GRID `_ - `CUHK01 `_ - `SenseReID `_ - `QMUL-iLIDS `_ - `PRID `_ Geo-localization datasets ^^^^^^^^^^^^^^^^^^^^^^^ - `University-1652 `_ Video-reid datasets ^^^^^^^^^^^^^^^^^^^^^^^ - `MARS `_ - `iLIDS-VID `_ - `PRID2011 `_ - `DukeMTMC-VideoReID `_ Models ------- ImageNet classification models ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - `ResNet `_ - `ResNeXt `_ - `SENet `_ - `DenseNet `_ - `Inception-ResNet-V2 `_ - `Inception-V4 `_ - `Xception `_ - `IBN-Net `_ Lightweight models ^^^^^^^^^^^^^^^^^^^ - `NASNet `_ - `MobileNetV2 `_ - `ShuffleNet `_ - `ShuffleNetV2 `_ - `SqueezeNet `_ ReID-specific models ^^^^^^^^^^^^^^^^^^^^^^ - `MuDeep `_ - `ResNet-mid `_ - `HACNN `_ - `PCB `_ - `MLFN `_ - `OSNet `_ - `OSNet-AIN `_ Useful links ------------- - `OSNet-IBN1-Lite (test-only code with lite docker container) `_ - `Deep Learning for Person Re-identification: A Survey and Outlook `_ Citation --------- If you find this code useful to your research, please cite the following papers. .. code-block:: bash @article{torchreid, title={Torchreid: A Library for Deep Learning Person Re-Identification in Pytorch}, author={Zhou, Kaiyang and Xiang, Tao}, journal={arXiv preprint arXiv:1910.10093}, year={2019} } @inproceedings{zhou2019osnet, title={Omni-Scale Feature Learning for Person Re-Identification}, author={Zhou, Kaiyang and Yang, Yongxin and Cavallaro, Andrea and Xiang, Tao}, booktitle={ICCV}, year={2019} } @article{zhou2019learning, title={Learning Generalisable Omni-Scale Representations for Person Re-Identification}, author={Zhou, Kaiyang and Yang, Yongxin and Cavallaro, Andrea and Xiang, Tao}, journal={arXiv preprint arXiv:1910.06827}, year={2019} }